SYS/BIOS Release Notes

SYS/BIOS 6.32.01.38 Release Notes

This release note is divided into the following sections:

Introduction, Documentation, What's New, Upgrading And Compatibility Information, Host Support, Dependencies, Device Support, Validation Information, Known Issues, Benchmarks, Versioning, Technical Support And Product Updates,

Introduction

SYS/BIOS 6.32.01.38 is a release of SYS/BIOS 6.32.00.

SYS/ BIOS is a real-time operating system that provides pre-emptive deterministic multithreading. The SYS/BIOS 6.x releases introduce a completely new SYS/BIOS kernel and toolset. The SYS/BIOS 6.x releases include numerous major enhancements, including completely new kernel APIs. They also include compatibility layers and tooling to facilitate easy porting of applications developed on DSP/BIOS 5.x releases.

A number of tools and libraries that were provided as an integrated part of DSP/BIOS 5.x releases must now be downloaded separately to obtain a functional solution. It is essential for even experienced DSP/BIOS users to refer to the Getting Started Guide and to the Upgrading and Compatibility Information section for further details.

Please read the Getting Started Guide for help installing and setting up your environment to use SYS/BIOS 6.32.01.38.

back to top

Documentation

The following documentation is provided with this release. These documents are also available via teh CCS Eclipse help table of contents.

  • SYS/BIOS 6 Getting Started Guide
  • SYS/BIOS 6 User's Guide
  • SYS/BIOS 6 Microsoft HTML .chm help file
  • SYS/BIOS APIs (cdoc) (Indexed and Searchable within CCS/Eclipse Help)
  • Migrating a DSP/BIOS 5 Application to SYS/BIOS 6
License and manifest.
  • SYS/BIOS Manifest and License
Additional online sources of documentation.
  • SYS/BIOS 6 wiki pages

Release notes from previous releases are also available in the release notes archive directory.

back to top

What's New

SYS/BIOS 6.32.01.38 Release (this release).

  • Project wizard improvements for 28x (generic platform and linker .cmd files).
  • More graphical configuration tool improvements.
  • Updates to custom build flow.
  • Bug fixes (see list below).
Defects Fixed in SYS/BIOS 6.32.01.38 (Fixes since SYS/BIOS 6.32.00.28):
ID Headline
SDOCM00081682 gptimer: Timer_setPeriodMicroSecs is slightly off calculating TLDR value based on desired clock period
SDOCM00081681 (Parent) dmtimer: Timer_setPeriodMicroSecs is slightly off calculating TLDR value based on desired clock period
SDOCM00081645 put 28x interrupt vectors in const/FLASH and copy to 0xd00 at runtime to allow easy FLASH boot
SDOCM00081609 update rtdx to use .text:rtdx_text and .ebss:rtdx_data (for 28x) (or .far:rtdx_data for 6x)
SDOCM00081580 BIOS 6 examples build but do not run for 28x devices with external memory
SDOCM00081549 BIOS HeapBuf and Mailbox to use Hwi_disable/restore rather than Gate_enterSystem/Gate_leaveSystem.
SDOCM00081404 update BIOS and IPC custom builds to avoid "unused variable i" (etc) warnings
SDOCM00081403 (Child) dmtimer: Timer_setPeriodMicroSecs is slightly off calculating TLDR value based on desired clock period
SDOCM00081264 update BIOS.xs to allow BIOS profile to be "release" whill allowing other content to still use "whole_program" profile
SDOCM00081221 MSP430 - Change the default clock source when a timer is dedicated for timestamping to be ACLK
SDOCM00081201 Comment out the blinking of the LED in the MSP430-specific examples
SDOCM00081200 MSP430 interrupt stubs should call Hwi begin/end hooks before/after logging of LM_begin/LD_end
SDOCM00081017 Create separate configuation and build chapter in user guide
SDOCM00081012 2806x support is missing from BIOS 6.x conversion package
SDOCM00081010 Setting Power.idle to false for MSP430 causes build failure
SDOCM00080920 Problems rebuilding sysbios after installation
SDOCM00080890 (Child) configuring FatFS for no ramdisk causes warning
SDOCM00080854 BIOS 6: Heap manager module gates should be the same as gate BIOS uses for rts lock
SDOCM00080833 Provide an MSP430 Hwi-module config that globally turns on Hwi logging for all interrupts
SDOCM00080794 Should inline Hwi_enable(), Hwi_disable() and Hwi_restore() for MSP430
SDOCM00080782 fat filesystem utils (bios_6_31_00_18\packages\ti\sysbios\fatfs\utils\bin) are not supported on the windows platform
SDOCM00080746 update Agent.xdc to use 'Ptr' instead of Stream_Handle to break hard dependency on Stream.
SDOCM00080744 custom build option needs to display the sub-options in Grace view w/o needing the refresh step
SDOCM00080700 Group MSP and Stellaris devices in delegate HTML table
SDOCM00080673 Should ship a barebones SYS/BIOS example that will build for all supported MSP430 devices
SDOCM00080671 c28x .taskStackSection should be renamed as a subsection of a compiler section.
SDOCM00080665 add validation to the build flow to make sure config parameters make sense for inst/non-inst libraries
SDOCM00080614 Clock-tick related fields in ROV can show stale data when doing dynamic tick suppression
SDOCM00080609 review 28x Boot module and include BIOS/ Grace "Device Support" page for 28x
SDOCM00080464 optimize Hwi enter/exit stubs for MSP430 to use single function or file level optimization
SDOCM00079912 For MemoryProtection module, UMC_P0_BADDR is incorrect for DM647/8 device
SDOCM00079697 genx examples need to be fix to not get the GateMutex badContext assert
SDOCM00078956 BIOS 6: Verify 28x Generic Platform
SDOCM00078950 BIOS 6: Prepare Stellaris specific BIOS wiki page
SDOCM00078887 MSP430/Hwi module should warn if Log statements are enabled, but Diags bits are set to always off
SDOCM00078675 Load's ROV view needs enhancing (wrt Task and Swi)
SDOCM00071672 28x should be supported with generic platform similar to MSP430 (BIOS side of bugzilla Bug 317539)
back to top

Upgrading and Compatibility Information

SYS/BIOS 6.x releases have many significant changes from DSP/BIOS 5.x. It is important to understand the information below in order to successfully use SYS/BIOS 6.x and to migrate applications from DSP/BIOS 5.x.

SYS/BIOS software downloads

SYS/BIOS 6.32
  • We are planning to remove support for the whole_program and whole_program_debug profiles because of build time problems and compatibility problems when using different compiler versions. SYS/BIOS 6.32 will output a warning message when the whole_program or whole_program_debug profiles are used. We are now providing pre-built libraries which can be selected via the BIOS.libType configuration parameter (see section 7.6.1 of the BIOS User's Guide for details). The instrumented library contains Assert() and Log statements. The non-instrumented library does not. The custom library can be used to build a custom BIOS library which will be built using #define constants reflecting some of the key configuration parameters from your application .cfg file. The non-instrumented library and custom library should give you similar or better performance to SYS/BIOS 6.31 using the whole_program profile.
  • .taskStackSection has been renamed – The .taskStackSection linker section has been renamed to be a subsection of .far, .bss, or .ebss as appropriate for the given target. This allows BIOS to be used with CCS-supplied linker .cmd files for the MSP430, Stellaris and 28x devices. This section is used to place the stacks for tasks created at configuration time. The new name is provided in the Task.defaultStackSection field in your configuration. If you reference ‘.taskStackSection’ in your .cfg file, you should change the code to use Task.defaultStackSection.

SYS/BIOS 6.31
  • Added an assert to GateMutex. GateMutex_enter() calls BIOS_getThreadType() to validate the calling context. GateMutex_enter() will raise an assert if called from Hwi or Swi context. GateMutex internally calls Semaphore_pend/post to provide the mutex. Semaphore_pend() cannot be called from Swi or Hwi context if the semaphore is not available. Note that a GateMutex gate is registered with the TI compiler’s RTS library to make the RTS library reentrant. Calling printf() and a few other RTS functions from Swi or Hwi context will yield this assert.
  • This assert check will catch bad code that could cause a rare crash. While not recommended, this assert can be disabled by adding ‘GateMutex.common$.diags_ASSERT = Diags.ALWAYS_OFF;’ to your .cfg file.
  • Text footprint on the C6x increased by 2K due to Exception.enablePrint default now being set to ‘true’ by default. This enables better diagnostic output when an exception occurs. You can set this config parameter to ‘false’ to save memory and get a shorter, less informative diagnostic string.
  • MMU and Cache are now enabled by default for Arm9.
    • Arm9 applications will have larger data/text footprint due to the 16kbyte MMU table and MMU initialization code.
    • Moved ti.sysbios.arm.Cache module to ti.sysbios.arm.arm9.Cache since this module is Arm9-specific. .cfg scripts will have to be updated to use new name (‘ti.sysbios.family.arm.arm9.Cache’) and .c files will have to change to use ‘#include <ti/sysbios/arm/arm9/Cache.h>’.
  • Use BIOS_exit() rather than System_exit() if called from ISR or Swi context to avoid Assert() in GateMutex module. BIOS_exit() and System_exit() both flush the SysMin trace buffer using CIO. The CIO library is protected by GateMutex.

DA830 ROM

  • BIOS 6.30 and 6.31 cannot be used with the DA830 ROM. BIOS 6.21 is the preferred version for DA830 ROM.

The 'ti.sdo.io' and 'ti.sdo.utils' packages are no longer provided with SYS/BIOS

  • These packages are now provided in a separate "IPC" product. Users of these packages simply need to add this other product directory to their package path (XDCPATH) to build their applications.

The ti.sysbios.ipc package and its modules have been deprecated

  • The Semaphore, Event, and Mailbox modules were moved from the ti.sysbios.ipc package into the ti.sysbios.knl package. Please update your applications to use the ti.sysbios.knl package versions of the Semaphore, Event, and Mailbox modules. Using the ipc package versions of these modules will result in build warnings. In a subsequent release of BIOS, using any module within the ipc package will result in a build error.

The ti.sysbios.family.arm.m3.Exception module has been deprecated

  • The ti.sysbios.family.arm.m3.Exception module functionality has been enhanced and merged into the ti.sysbios.family.arm.m3.Hwi module. Please update your applications to use the ti.sysbios.family.arm.m3.Hwi module to configure exception handling. By default, exceptions will be reported to CIO with an Error message. Details of the exception can be seen using Hwi module's "Exception" ROV view. At the expense of additonal code size, some of this detailed information can ALSO be routed to the CIO console by setting the Hwi.enableException configuration flag to true.

Placing of sections using MEM configs is no longer supported (ie MEM.TEXTSEG is unsupported)

  • All of the legacy MEM memory segment placment functionality has been removed. Legacy BIOS users must use Program.sectMap to place memory sections.

The ti.sysbios.family.c64p.Cache.initSize configuration item is no longer supported

  • The ti.sysbios.family.c64p.Cache module no longer supports setting the Cache sizes. These settings are now managed within a platform and can be configured using the platform wizard.

SYS/BIOS no longer contains all the tools and objects you will need

  • The XDC tools now provide the SYS/BIOS configuration tools and Platform support. XDC also includes a minimal run-time environment that provides the LOG, System, Asserts, Error handling, Timestamp, and Memory Allocation APIs that will be used by SYS/BIOS applications. Please refer to the Getting Started Guide on where to download the XDC tools and run-time.
Migrating DSP/BIOS 5.x applications to SYS/BIOS 6.x
  • SYS/BIOS 6.x has different APIs compared to those in DSP/BIOS 5.x. Configuration scripts are also incompatible between the two releases. To provide easy migration of DSP/BIOS 5.x applications, an API compatibility layer is provided along with a conversion tool that converts configuration scripts to work with XDC and SYS/BIOS 6.x. The API compatibility layer provides 100% C source code compatibility with the exception of a few APIs that are no longer supported. For more complete details of migrating DSP/BIOS 5.x applications and configuration scripts, please refer to Migrating a DSP/BIOS 5 Application to SYS/BIOS 6 .
  • As mentioned above, some APIs previously supported in DSP/BIOS 5.x releases will no longer be supported in this release or the compatibility layer. Complete details are provided in the Migration document referenced above.
back to top

Host Support

  • Supported Operating Systems
    • Windows 7, Windows XP, Windows Vista
    • Linux [RH4], Ubuntu [10.1]
back to top

Dependencies

  • Required Software
    • Code Composer Studio v4.2.4, Code Composer Studio v5.0, Code Composer Studio v5.1 or later
    • Code Generation Tools
      • C28X version 6.0.1 or later
      • C6X version 7.2.3 or later
      • ARM version 4.9.0 or later
      • MSP430 version 3.3.3 or later
    • XDCtools 3.22.01.21 or later
    • IPC 1.23.01.25 or later
  • Required Hardware
    • See Device Support Section below.
back to top

Device Support

Click here for the list of supported devices.

back to top

Validation Information

Click here for the list of compilers used to build and validate this release (scroll down to Supported Targets section).

back to top

Known Issues

The following issues are known to affect this release:

  • If this version of SYS/BIOS is installed on the same system as SYS/BIOS 6.31.00.xx or older, and use the same version of CCS, the user may see two "SYS/BIOS" folders in the examples when creating a new project. The Eclipse plugins were updated to fix this in SYS/BIOS 6.31.01.19 and later. To work around this issue remove all versions of SYS/BIOS older than 6.31.01.19.
ID Headline
SDOCM00081912 BIOS needs to support Flash boot on Concerto
SDOCM00081684 DM8168: Timer0 interrupts at twice expected frequency
SDOCM00074130 ROV should reference kernel object names versus object addresses
SDOCM00069043 BIOS 6.x must support Concerto (dual-core M3/28x) including changes to timestamp. Work is mostly complete on this but complete validation is still in progress. There will be a 6.32.02 patch release in mid-July after validation on Concerto hardware has been completed.
SDOCM00068360 No data displayed in RTA Exec Graph when attaching to running target
SDOCM00064397 RTA crashes CCS 4.1 after a few reset/reload with USB emulator

back to top

Benchmarks

For a full description of Benchmarks please see the appendices in the SYS/BIOS 6 User's Guide.
  • Timing and Size Benchmarks
back to top

Versioning

All releases have 4 digits (M.mm.pp.bb). This includes GA and pre-releases (engineering, alpha/EA, beta, etc.). Pre-releases are denoted with a suffix (e.g. 6.30.00.00-eng or 6.30.00.10-beta).

This product's version follows a version format, M.mm.pp.bb, where M is a single digit Major number, mm is 2 digit minor number, pp is a 2 digit patch number, and b is an unrestricted set of digits used as an incrementing build counter.

To support multiple side-by-side installations of the product, the product version is encoded in the top level directory (e.g. bios_6_30_00_00).

Subsequent releases of patch upgrades will be identified by the patch number, ex. SYS/BIOS 6.30.01.15 with directory bios_6_30_01_15. Typically, these patches only include critical bug fixes.

Please note that version numbers and compatibility keys are NOT the same. For an explanation of compatibility keys, please refer to the 'Upgrade and Compatibility Information' section.

back to top

Technical Support and Product Updates

  • Please contact softwaresupport@ti.com for technical support.
  • SYS/BIOS software downloads
  • TI E2E Community
back to top

Last updated: June 16, 2011 Build Ver: 6.32.01.38 Rev: h38


package ti.sysbios
index URL

SYS/BIOS Scalable/Extensible Real-time Kernel

SYS/BIOS is a scalable real-time kernel. It is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. SYS/BIOS provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. SYS/BIOS is designed to minimize memory and CPU requirements on the target. [ more ... ]
XDCspec declarations sourced in ti/sysbios/package.xdc
requires ti.sysbios.family;
package ti.sysbios [2, 0, 0, 0] {
    module BIOS;
    // SYS/BIOS Master Manager
}
DETAILS
SYS/BIOS is a scalable real-time kernel. It is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. SYS/BIOS provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration tools. SYS/BIOS is designed to minimize memory and CPU requirements on the target.
This package contains the BIOS module, which serves as the "top level" configuration entry point for SYS/BIOS. The BIOS module provides basic configuration parameters necessary to use SYS/BIOS and provides links to more advanced configuration options that can be used to further optimize SYS/BIOS for your application.
SYS/BIOS is implemented as a set of RTSC packages, each of which delivers a subset of the functionality. The RTSC standard recommends a naming convention for packages to aid readability and uniqueness. If you are familiar with the Java package naming convention, you will find SYS/BIOS's packages to be quite similar.
SYS/BIOS packages conform to this convention with names that consist of a hierarchical naming pattern; each level is separated by a period ("."). Usually, the highest level of the name is the vendor ("ti"), followed by the product ("sysbios"), and then followed by the module and submodule names (for example, "knl").
These names have the added benefit of reflecting the physical layout of the package within the file system where SYS/BIOS has been installed. For example, the ti.sysbios.knl package files can be found at BIOS_INSTALL_DIR/bios_6_3#_##/packages/ti/sysbios/knl.
For more information about SYS/BIOS, see the following:
  • SYS/BIOS Getting Started Guide
  • SYS/BIOS 6.x User's Guide
  • Migrating a DSP/BIOS 5 Application to SYS/BIOS 6
  • RTSC-pedia wiki
  • SYS/BIOS Information Wiki
  • SYS/BIOS 6.x Product Information
  • SYS/BIOS forum in TI E2E Community
generated on Fri, 17 Jun 2011 00:22:25 GMT


module ti.sysbios.BIOS
index URL

SYS/BIOS Master Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module is responsible for setting up global parameters pertaining to SYS/BIOS and for performing the SYS/BIOS startup sequence. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/BIOS.xdc
#include <ti/sysbios/BIOS.h>
Functions
Void | BIOS_exit// Exit currently running SYS/BIOS executable(Int stat);
Void | BIOS_getCpuFreq// Get CPU frequency in Hz(Types_FreqHz *freq);
BIOS_ThreadType | BIOS_getThreadType// Get the current thread type();
Void | BIOS_setCpuFreq// Set CPU Frequency in Hz(Types_FreqHz *freq);
Void | BIOS_start// Start SYS/BIOS();
Functions common to all target modules
 | BIOS_Module_getMask// Returns the diagnostics mask for this module, BIOS_Module_hasMask// Test whether this module has a diagnostics mask, BIOS_Module_heap// The heap from which this module allocates memory, BIOS_Module_id// Get this module's unique id, BIOS_Module_setMask// Set the diagnostics mask for this module, BIOS_Module_startupDone// Test if this module has completed startup
Defines
#define | BIOS_NO_WAIT// Used in APIs that take a timeout to specify no waiting (UInt)0
#define | BIOS_WAIT_FOREVER// Used in APIs that take a timeout to specify wait forever (UInt)~(0)
Typedefs
typedef enum | BIOS_LibType// SYS/BIOS library selection options ...
typedef enum | BIOS_RtsLockType// Type of Gate to use in the TI RTS library ...
typedef Void | (*BIOS_StartupFuncPtr// User startup function type definition)(Void);
typedef enum | BIOS_ThreadType// Current thread type definitions ...
Constants
extern const Bool | BIOS_clockEnabled// SYS/BIOS Clock services enable flag;
extern const Types_FreqHz | BIOS_cpuFreq// CPU frequency in Hz;
extern const String | BIOS_heapSection// Section to place the system heap;
extern const SizeT | BIOS_heapSize// Size of system heap;
extern const Bool | BIOS_swiEnabled// SYS/BIOS Swi services enable flag;
extern const Bool | BIOS_taskEnabled// SYS/BIOS Task services enable flag;
DETAILS
This module is responsible for setting up global parameters pertaining to SYS/BIOS and for performing the SYS/BIOS startup sequence.
SYS/BIOS configures the Memory.defaultHeapInstance using a HeapMem instance of size heapSize.
The SYS/BIOS startup sequence is logically divided into two phases: those operations that occur prior to the application's "main()" function being called, and those operations that are performed after the application's "main()" function is invoked.
The "before main()" startup sequence is governed completely by the RTSC runtime package.
The "after main()" startup sequence is governed by SYS/BIOS and is initiated by an explicit call to the BIOS_start() function at the end of the application's main() function.
Control points are provided at various places in each of the two startup sequences for user startup operations to be inserted.
The RTSC runtime startup sequence is as follows:
  1. Immediately after CPU reset, perform target-specific CPU initialization (beginning at c_int00).
  2. Prior to cinit(), run the single user-supplied "reset function" (see Startup.resetFxn).
  3. Run cinit() to initialize C runtime environment.
  4. Run the user-supplied "first functions" (see Startup.firstFxns).
  5. Run all the module initialization functions.
  6. Run pinit().
  7. Run the user-supplied "last functions" (see Startup.lastFxns).
  8. Run main().
The SYS/BIOS startup sequence begins at the end of main() when BIOS_start() is called:
  1. Run the user-supplied "startup functions" (see BIOS.startupFxns).
  2. Enable Hardware Interrupts.
  3. Enable Software Interrupts. If the system supports Software Interrupts (Swis) (see BIOS.swiEnabled), then the SYS/BIOS startup sequence enables Swis at this point.
  4. Timer Startup. If the system supports Timers, then at this point all statically configured timers are initialized per their user-configuration. If a timer was configured to start "automatically", it is started here.
  5. Task Startup. If the system supports Tasks (see BIOS.taskEnabled), then task scheduling begins here. If there are no statically or dynamically created Tasks in the system, then execution proceeds directly to the Idle loop.
Below is a configuration script excerpt that installs a user-supplied startup function at every possible control point in the RTSC and SYS/BIOS startup sequence:
  // get handle to xdc Startup module
  var Startup = xdc.useModule('xdc.runtime.Startup');

  // install "reset function"
  Startup.resetFxn = '&myReset';

  // install a "first function"
  var len = Startup.firstFxns.length
  Startup.firstFxns.length++;
  Startup.firstFxns[len] = '&myFirst';

  // install a "last function"
  var len = Startup.lastFxns.length
  Startup.lastFxns.length++;
  Startup.lastFxns[len] = '&myLast';

  // get handle to SYS/BIOS module
  var BIOS = xdc.useModule('ti.sysbios.BIOS');

  // install a SYS/BIOS startup function
  BIOS.addUserStartupFunction('&myBiosStartup');

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getCpuFreq | Y | Y | Y | Y | Y
getThreadType | Y | Y | Y | Y | N
setCpuFreq | Y | Y | Y | Y | Y
start | N | N | N | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. BIOS_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. BIOS_Module_startupDone() returns FALSE).
const BIOS_NO_WAIT
index URL

Used in APIs that take a timeout to specify no waiting

C synopsis target-domain
#define BIOS_NO_WAIT (UInt)0
const BIOS_WAIT_FOREVER
index URL

Used in APIs that take a timeout to specify wait forever

C synopsis target-domain
#define BIOS_WAIT_FOREVER (UInt)~(0)
enum BIOS_LibType
index URL

SYS/BIOS library selection options

C synopsis target-domain
typedef enum BIOS_LibType {
    BIOS_LibType_Instrumented,
    // instrumented
    BIOS_LibType_NonInstrumented,
    // non-instrumented
    BIOS_LibType_Custom,
    // custom
    BIOS_LibType_Debug
    // debug
} BIOS_LibType;
VALUES
LibType_Instrumented — The library supplied is prebuilt with logging and assertions enabled.
LibType_NonInstrumented — The library supplied is prebuilt with logging and assertions disabled.
LibType_Debug — The library supplied is prebuilt with logging and assertions enabled together with full symbolic debug enabled. In addition, this library contains embedded information that enables it to participate in whole program optimization builds.
LibType_Custom — This option allows you to build the SYS/BIOS library from sources using the options specified by customCCOpts.
DETAILS
This enumeration defines all the SYS/BIOS library types provided by the product. You can select the library type by setting the BIOS.libType configuration parameter.
SEE
libType
enum BIOS_RtsLockType
index URL

Type of Gate to use in the TI RTS library

C synopsis target-domain
typedef enum BIOS_RtsLockType {
    BIOS_NoLocking,
    BIOS_GateHwi,
    BIOS_GateSwi,
    BIOS_GateMutex,
    BIOS_GateMutexPri
} BIOS_RtsLockType;
VALUES
NoLocking — no gate is added to the RTS library. In this case, the application needs to be careful to always serialize access to the inherently non-reentrant ANSI C functions (such as malloc(), printf(), etc.).
GateHwi — Interrupts are disabled and restored to maintain re-entrancy. This is a very efficient lock but will also result in unbounded interrupt latency times. If real-time responce to interrupts is important, you should not use this gate to lock the RTS library.
GateSwi — Swis are disabled and restored to maintain re-entrancy.
GateMutex — A single mutex is used to maintain re-entrancy.
GateMutexPri — A single priority inheriting mutex is used to maintain re-entrancy.
SEE
rtsGateType
enum BIOS_ThreadType
index URL

Current thread type definitions

C synopsis target-domain
typedef enum BIOS_ThreadType {
    BIOS_ThreadType_Hwi,
    // Current thread is a Hwi
    BIOS_ThreadType_Swi,
    // Current thread is a Swi
    BIOS_ThreadType_Task,
    // Current thread is a Task
    BIOS_ThreadType_Main
    // Current thread is Boot/Main
} BIOS_ThreadType;
DETAILS
These values are returned by BIOS_getThreadType.
SEE
getThreadType
typedef BIOS_StartupFuncPtr
index URL

User startup function type definition

C synopsis target-domain
typedef Void (*BIOS_StartupFuncPtr)(Void);
config BIOS_clockEnabled // module-wide
index URL

SYS/BIOS Clock services enable flag

C synopsis target-domain
extern const Bool BIOS_clockEnabled;
DETAILS
The following behaviors occur when clockEnabled is set to false:
  • Static Clock creation will result in a fatal build error.
  • No Clock Swi is created.
  • The Clock_tickSource is set to Clock_TickSource_NULL to prevent a Timer object from being created.
  • For APIs that take a timeout, values other than NO_WAIT will be equivalent to WAIT_FOREVER.
config BIOS_cpuFreq // module-wide
index URL

CPU frequency in Hz

C synopsis target-domain
extern const Types_FreqHz BIOS_cpuFreq;
DETAILS
This configuration parameter allow SYS/BIOS to convert various periods between timer ticks (or instruction cycles) and real-time units. For example, timer periods expressed in micro-seconds need to be converted into timer ticks in order to properly program the timers.
The default value of this parameter is obtained from the platform (the clockRate property of Program.cpu) which is the CPU clock rate when the processor is reset.
EXAMPLE
If CPU frequency is 720MHz, the following configuration script configures SYS/BIOS with the proper clock frequency:
     var BIOS = xdc.useModule('ti.sysbios.BIOS');
     BIOS.cpuFreq.hi = 0;
     BIOS.cpuFreq.lo = 720000000;
config BIOS_heapSection // module-wide
index URL

Section to place the system heap

C synopsis target-domain
extern const String BIOS_heapSection;
DETAILS
This configuration parameter allows you to specify a named output section that will contain the SYS/BIOS system heap. The system heap is, by default, used to allocate Task stacks and instance object state structures. So, giving this section a name and explicitly placing it via a linker command file can significantly improve system performance.
If heapSection is null (or undefined) the system heap is placed in the target's default data section.
config BIOS_heapSize // module-wide
index URL

Size of system heap

C synopsis target-domain
extern const SizeT BIOS_heapSize;
DETAILS
If the application configuration does not set Memory.defaultHeapInstance, then SYS/BIOS will create a HeapMem heap of this size. This heap will be assigned to Memory.defaultHeapInstance and will therefore be used as the default system heap. This heap will also be used by the SYS/BIOS version of the standard C library functions malloc(), calloc() and free().
config BIOS_swiEnabled // module-wide
index URL

SYS/BIOS Swi services enable flag

C synopsis target-domain
extern const Bool BIOS_swiEnabled;
DETAILS
The following behaviors occur when swiEnabled is set to false:
  • Static Swi creation will result in a fatal build error.
  • The Clock module is effectively disabled as it uses a Swi to process the Clock objects.
  • See other effects as noted for clockEnabled = false;
  • Runtime calls to Swi_create will trigger an assertion violation via xdc.runtime.Assert.isTrue.
config BIOS_taskEnabled // module-wide
index URL

SYS/BIOS Task services enable flag

C synopsis target-domain
extern const Bool BIOS_taskEnabled;
DETAILS
The following behaviors occur when taskEnabled is set to false:
  • Static Task creation will result in a fatal build error.
  • The Idle task object is not created. (The Idle functions are invoked within the start() thread.)
  • Runtime calls to Task_create will trigger an assertion violation via xdc.runtime.Assert.isTrue.
BIOS_exit() // module-wide
index URL

Exit currently running SYS/BIOS executable

C synopsis target-domain
Void BIOS_exit(Int stat);
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This function is called when a SYS/BIOS executable needs to terminate normally. This function sets the internal SYS/BIOS threadType to ThreadType_Main and then calls System_exit(stat), passing along the 'stat' argument.
All functions bound via System_atexit or the ANSI C Standard Library atexit function are then executed.
BIOS_getCpuFreq() // module-wide
index URL

Get CPU frequency in Hz

C synopsis target-domain
Void BIOS_getCpuFreq(Types_FreqHz *freq);
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_getThreadType() // module-wide
index URL

Get the current thread type

C synopsis target-domain
BIOS_ThreadType BIOS_getThreadType();
RETURNS
Current thread type
BIOS_setCpuFreq() // module-wide
index URL

Set CPU Frequency in Hz

C synopsis target-domain
Void BIOS_setCpuFreq(Types_FreqHz *freq);
DETAILS
This API is not thread safe. Please use appropriate locks.
BIOS_start() // module-wide
index URL

Start SYS/BIOS

C synopsis target-domain
Void BIOS_start();
DETAILS
The user's main() function is required to call this function after all other user initializations have been performed.
This function does not return.
This function performs any remaining SYS/BIOS initializations and then transfers control to the highest priority ready task if taskEnabled is true. If taskEnabled is false, control is transferred directly to the Idle Loop.
The SYS/BIOS start sequence is as follows:
  • Invoke all the functions in the startupFxns array.
  • call Hwi_startup() to enable interrupts.
  • if swiEnabled is true, call Swi_startup() to enable the Swi scheduler.
  • Start any statically created or constructed Timers in the Timer_StartMode_AUTO mode.
  • if taskEnabled is true, enable the Task scheduler and transfer the execution thread to the highest priority task in the Task_Mode_READY mode.
  • Otherwise, fall directly into the Idle Loop.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId BIOS_Module_id();
// Get this module's unique id
Bool BIOS_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle BIOS_Module_heap();
// The heap from which this module allocates memory
Bool BIOS_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 BIOS_Module_getMask();
// Returns the diagnostics mask for this module
Void BIOS_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/BIOS.xdc
var BIOS = xdc.useModule('ti.sysbios.BIOS');
module-wide constants & types
    const BIOS.NO_WAIT// Used in APIs that take a timeout to specify no waiting = 0;
    const BIOS.WAIT_FOREVER// Used in APIs that take a timeout to specify wait forever = ~(0);
    values of type BIOS.LibType// SYS/BIOS library selection options
        const BIOS.LibType_Instrumented// instrumented;
        const BIOS.LibType_NonInstrumented// non-instrumented;
        const BIOS.LibType_Custom// custom;
        const BIOS.LibType_Debug// debug;
    values of type BIOS.RtsLockType// Type of Gate to use in the TI RTS library
        const BIOS.NoLocking;
        const BIOS.GateHwi;
        const BIOS.GateSwi;
        const BIOS.GateMutex;
        const BIOS.GateMutexPri;
    values of type BIOS.ThreadType// Current thread type definitions
        const BIOS.ThreadType_Hwi// Current thread is a Hwi;
        const BIOS.ThreadType_Swi// Current thread is a Swi;
        const BIOS.ThreadType_Task// Current thread is a Task;
        const BIOS.ThreadType_Main// Current thread is Boot/Main;
module-wide config parameters
     BIOS.clockEnabled// SYS/BIOS Clock services enable flag = Bool true;
     BIOS.cpuFreq// CPU frequency in Hz = Types.FreqHz undefined;
     BIOS.heapSection// Section to place the system heap = String null;
     BIOS.heapSize// Size of system heap = SizeT 0x1000;
     BIOS.swiEnabled// SYS/BIOS Swi services enable flag = Bool true;
     BIOS.taskEnabled// SYS/BIOS Task services enable flag = Bool true;
     BIOS.assertsEnabled// SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag = Bool true;
     BIOS.common$// Common module configuration parameters = Types.Common$ undefined;
     BIOS.customCCOpts// Compiler options used to build custom library = String undefined;
     BIOS.libType// SYS/BIOS Library type = BIOS.LibType BIOS.LibType_Instrumented;
     BIOS.logsEnabled// SYS/BIOS Log support in Custom SYS/BIOS library enable flag = Bool true;
     BIOS.rtsGateType// Gate to make sure TI RTS library APIs are re-entrant = BIOS.RtsLockType undefined;
     BIOS.startupFxns// Functions to be executed at the beginning of BIOS_start() = BIOS.StartupFuncPtr[] [ ];
const BIOS.NO_WAIT
index URL

Used in APIs that take a timeout to specify no waiting

XDCscript usage meta-domain
const BIOS.NO_WAIT = 0;
C SYNOPSIS
BIOS_NO_WAIT
const BIOS.WAIT_FOREVER
index URL

Used in APIs that take a timeout to specify wait forever

XDCscript usage meta-domain
const BIOS.WAIT_FOREVER = ~(0);
C SYNOPSIS
BIOS_WAIT_FOREVER
enum BIOS.LibType
index URL

SYS/BIOS library selection options

XDCscript usage meta-domain
values of type BIOS.LibType
    const BIOS.LibType_Instrumented;
    // instrumented
    const BIOS.LibType_NonInstrumented;
    // non-instrumented
    const BIOS.LibType_Custom;
    // custom
    const BIOS.LibType_Debug;
    // debug
VALUES
LibType_Instrumented — The library supplied is prebuilt with logging and assertions enabled.
LibType_NonInstrumented — The library supplied is prebuilt with logging and assertions disabled.
LibType_Debug — The library supplied is prebuilt with logging and assertions enabled together with full symbolic debug enabled. In addition, this library contains embedded information that enables it to participate in whole program optimization builds.
LibType_Custom — This option allows you to build the SYS/BIOS library from sources using the options specified by customCCOpts.
DETAILS
This enumeration defines all the SYS/BIOS library types provided by the product. You can select the library type by setting the BIOS.libType configuration parameter.
SEE
libType
C SYNOPSIS
BIOS_LibType
enum BIOS.RtsLockType
index URL

Type of Gate to use in the TI RTS library

XDCscript usage meta-domain
values of type BIOS.RtsLockType
    const BIOS.NoLocking;
    const BIOS.GateHwi;
    const BIOS.GateSwi;
    const BIOS.GateMutex;
    const BIOS.GateMutexPri;
VALUES
NoLocking — no gate is added to the RTS library. In this case, the application needs to be careful to always serialize access to the inherently non-reentrant ANSI C functions (such as malloc(), printf(), etc.).
GateHwi — Interrupts are disabled and restored to maintain re-entrancy. This is a very efficient lock but will also result in unbounded interrupt latency times. If real-time responce to interrupts is important, you should not use this gate to lock the RTS library.
GateSwi — Swis are disabled and restored to maintain re-entrancy.
GateMutex — A single mutex is used to maintain re-entrancy.
GateMutexPri — A single priority inheriting mutex is used to maintain re-entrancy.
SEE
rtsGateType
C SYNOPSIS
BIOS_RtsLockType
enum BIOS.ThreadType
index URL

Current thread type definitions

XDCscript usage meta-domain
values of type BIOS.ThreadType
    const BIOS.ThreadType_Hwi;
    // Current thread is a Hwi
    const BIOS.ThreadType_Swi;
    // Current thread is a Swi
    const BIOS.ThreadType_Task;
    // Current thread is a Task
    const BIOS.ThreadType_Main;
    // Current thread is Boot/Main
DETAILS
These values are returned by BIOS_getThreadType.
SEE
getThreadType
C SYNOPSIS
BIOS_ThreadType
config BIOS.clockEnabled // module-wide
index URL

SYS/BIOS Clock services enable flag

XDCscript usage meta-domain
BIOS.clockEnabled = Bool true;
DETAILS
The following behaviors occur when clockEnabled is set to false:
  • Static Clock creation will result in a fatal build error.
  • No Clock Swi is created.
  • The Clock_tickSource is set to Clock_TickSource_NULL to prevent a Timer object from being created.
  • For APIs that take a timeout, values other than NO_WAIT will be equivalent to WAIT_FOREVER.
C SYNOPSIS
BIOS_clockEnabled
config BIOS.cpuFreq // module-wide
index URL

CPU frequency in Hz

XDCscript usage meta-domain
BIOS.cpuFreq = Types.FreqHz undefined;
DETAILS
This configuration parameter allow SYS/BIOS to convert various periods between timer ticks (or instruction cycles) and real-time units. For example, timer periods expressed in micro-seconds need to be converted into timer ticks in order to properly program the timers.
The default value of this parameter is obtained from the platform (the clockRate property of Program.cpu) which is the CPU clock rate when the processor is reset.
EXAMPLE
If CPU frequency is 720MHz, the following configuration script configures SYS/BIOS with the proper clock frequency:
     var BIOS = xdc.useModule('ti.sysbios.BIOS');
     BIOS.cpuFreq.hi = 0;
     BIOS.cpuFreq.lo = 720000000;
C SYNOPSIS
BIOS_cpuFreq
config BIOS.heapSection // module-wide
index URL

Section to place the system heap

XDCscript usage meta-domain
BIOS.heapSection = String null;
DETAILS
This configuration parameter allows you to specify a named output section that will contain the SYS/BIOS system heap. The system heap is, by default, used to allocate Task stacks and instance object state structures. So, giving this section a name and explicitly placing it via a linker command file can significantly improve system performance.
If heapSection is null (or undefined) the system heap is placed in the target's default data section.
C SYNOPSIS
BIOS_heapSection
config BIOS.heapSize // module-wide
index URL

Size of system heap

XDCscript usage meta-domain
BIOS.heapSize = SizeT 0x1000;
DETAILS
If the application configuration does not set Memory.defaultHeapInstance, then SYS/BIOS will create a HeapMem heap of this size. This heap will be assigned to Memory.defaultHeapInstance and will therefore be used as the default system heap. This heap will also be used by the SYS/BIOS version of the standard C library functions malloc(), calloc() and free().
C SYNOPSIS
BIOS_heapSize
config BIOS.swiEnabled // module-wide
index URL

SYS/BIOS Swi services enable flag

XDCscript usage meta-domain
BIOS.swiEnabled = Bool true;
DETAILS
The following behaviors occur when swiEnabled is set to false:
  • Static Swi creation will result in a fatal build error.
  • The Clock module is effectively disabled as it uses a Swi to process the Clock objects.
  • See other effects as noted for clockEnabled = false;
  • Runtime calls to Swi_create will trigger an assertion violation via xdc.runtime.Assert.isTrue.
C SYNOPSIS
BIOS_swiEnabled
config BIOS.taskEnabled // module-wide
index URL

SYS/BIOS Task services enable flag

XDCscript usage meta-domain
BIOS.taskEnabled = Bool true;
DETAILS
The following behaviors occur when taskEnabled is set to false:
  • Static Task creation will result in a fatal build error.
  • The Idle task object is not created. (The Idle functions are invoked within the start() thread.)
  • Runtime calls to Task_create will trigger an assertion violation via xdc.runtime.Assert.isTrue.
C SYNOPSIS
BIOS_taskEnabled
metaonly config BIOS.assertsEnabled // module-wide
index URL

SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag

XDCscript usage meta-domain
BIOS.assertsEnabled = Bool true;
DETAILS
When set to true, Assert checking code is compiled into the custom library created when BIOS.libType = BIOS.LibType_Custom.
When set to false, Assert checking code is removed from the custom library created when BIOS.libType = BIOS.LibType_Custom. This option can considerably improve runtime performance as well signficantly reduce the application's code size.
see BIOS.libType.
metaonly config BIOS.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
BIOS.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config BIOS.customCCOpts // module-wide
index URL

Compiler options used to build custom library

XDCscript usage meta-domain
BIOS.customCCOpts = String undefined;
metaonly config BIOS.libType // module-wide
index URL

SYS/BIOS Library type

XDCscript usage meta-domain
BIOS.libType = BIOS.LibType BIOS.LibType_Instrumented;
DETAILS
The SYS/BIOS runtime is provided in the form of a library that is linked with your application. Several forms of this library are provided with the SYS/BIOS product. In addition, there is an option to build the library from source. This configuration parameter allows you to select the form of SYS/BIOS to use.
The default value of libType is BIOS_LibType_Instrumented. For a complete list of options and what they offer see LibType.
metaonly config BIOS.logsEnabled // module-wide
index URL

SYS/BIOS Log support in Custom SYS/BIOS library enable flag

XDCscript usage meta-domain
BIOS.logsEnabled = Bool true;
DETAILS
When set to true, SYS/BIOS execution Log code is compiled into the custom library created when BIOS.libType = BIOS.LibType_Custom.
When set to false, all Log code is removed from the custom library created when BIOS.libType = BIOS.LibType_Custom. This option can considerably improve runtime performance as well signficantly reduce the application's code size.
see BIOS.libType.
metaonly config BIOS.rtsGateType // module-wide
index URL

Gate to make sure TI RTS library APIs are re-entrant

XDCscript usage meta-domain
BIOS.rtsGateType = BIOS.RtsLockType undefined;
DETAILS
The application gets to determine the type of gate (lock) that is used in the TI RTS library. The gate will be used to guarantee re-entrancy of the RTS APIs.
The type of gate depends on the type of threads that are going to be calling into the RTS library. For example, if both Swi and Task threads are going to be calling the RTS library's printf, GateSwi should be used. In this case, Hwi threads are not impacted (i.e. disabled) during the printf calls from the Swi or Task threads.
If NoLocking is used, the RTS lock is not plugged and re-entrancy for the TI RTS library calls are not guaranteed. The application can plug the RTS locks directly if it wants.
Numerous gate types are provided by SYS/BIOS. Each has its advantages and disadvantages. The following list summarizes when each type is appropriate for protecting an underlying non-reentrant RTS library.
GateHwi:
Interrupts are disabled and restored to maintain re-entrancy. Use if only making RTS calls from a Hwi, Swi and/or Task.
GateSwi:
Swis are disabled and restored to maintain re-entrancy. Use if only making RTS calls from a Swi and/or Task.
GateMutex:
A single mutex is used to maintain re-entrancy. Use if only making RTS calls from a Task. Blocks only Tasks that are also trying to execute critical regions of RTS library.
GateMutexPri:
A priority inheriting mutex is used to maintain re-entrancy. Blocks only Tasks that are also trying to execute critical regions of RTS library. Raises the priority of the Task that is executing the critical region in the RTS library to the level of the highest priority Task that is block by the mutex.
The default value of rtsGateType depends on the type of threading model enabled by other configuration parameters. If taskEnabled is true, GateMutex is used. If swiEnabled is true and taskEnabled is false: GateSwi is used. If both swiEnabled and taskEnabled are false: xdc.runtime.GateNull is used.
If taskEnabled is false, the user should not select GateMutex (or other Task level gates). Similarly, if taskEnabled and swiEnabledare false, the user should not select GateSwi or the Task level gates.
metaonly config BIOS.startupFxns // module-wide
index URL

Functions to be executed at the beginning of BIOS_start()

XDCscript usage meta-domain
BIOS.startupFxns = BIOS.StartupFuncPtr[] [ ];
DETAILS
These user (or middleware) functions are executed before Hwis, Swis, and Tasks are started.
generated on Fri, 17 Jun 2011 00:22:25 GMT


package ti.sysbios.benchmarks
index URL

BIOS 6 size and timing benchmarks

See Results.html for results. [ more ... ]
XDCspec declarations sourced in ti/sysbios/benchmarks/package.xdc
package ti.sysbios.benchmarks [1, 1, 0, 0] {
}
DETAILS
See Results.html for results.
Refer to the BIOS User's Guide Appendix for a complete description of the benchmarks.
generated on Fri, 17 Jun 2011 00:24:03 GMT


package ti.sysbios.family
index URL

Contains family-specific modules for SYS/BIOS

The ti.sysbios.family package contains family-specific implementations of modules in the Hardware Abstraction Layer (HAL) package. [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family [2, 0, 0, 0] {
    module Settings;
    // Select the device-specific family modules
}
DETAILS
The ti.sysbios.family package contains family-specific implementations of modules in the Hardware Abstraction Layer (HAL) package.
The SYS/BIOS ti.sysbios.hal package requires target/device-specific API implementations to achieve their functionality. To provide a common set of APIs for these modules across all supported families/devices, SYS/BIOS uses the RTSC proxy-delegate module mechanism. That is, the HAL modules serve as a proxies for a corresponding family-specific module implementation.
The generic HAL APIs are designed to cover the great majority of use cases. If you are concerned with easy portability between different TI devices, you should use the generic HAL APIs as much as possible. However, if the generic APIs cannot enable use of a device-specific hardware feature that is advantageous to the software application, you may choose to use the target/device-specific APIs.
During the configuration step of the application build, the modules in the ti.sysbios.hal package locate and bind themselves to appropriate delegate module implementations based on the current target and platform specified in your config.bld file. The delegate binding process is done internally.
For example, if your config.bld file specifies that one of your build targets is the C64P family, the ti.sysbios.hal.Hwi knows to bind itself to the ti.sysbios.family.c64p.Hwi implementation.
The SYS/BIOS Delegates Usage page lists the delegates available for every target and platform.
generated on Fri, 17 Jun 2011 00:22:41 GMT


module ti.sysbios.family.Settings

metaonly module ti.sysbios.family.Settings
index URL

Select the device-specific family modules

  • XDCscript usage
  • Individual elements
This module selects target-specific implementation modules required by the various SYS/BIOS packages. These modules are mainted in "family" packages which may also contain modules that are specific to a particular family; for example, cache or power management modules.
XDCscript usage meta-domain sourced in ti/sysbios/family/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilyName// Get SYS/BIOS device family name() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilyName() // module-wide
index URL

Get SYS/BIOS device family name

XDCscript usage meta-domain
Settings.getFamilyName() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:22:41 GMT


package ti.sysbios.family.arm
index URL

Contains specifications for the ARM family-specific SYS/BIOS functions

The link below provides SYS/BIOS ARMx register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/arm/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm [2, 0, 0, 0] {
    module Settings;
    // Device/Family-specific delegate assignment module for ARM9 target devices
    module TaskSupport;
    // ARM9 Task Support Module
}
DETAILS
The link below provides SYS/BIOS ARMx register usage information:
SYS/BIOS ARM Register Usage
generated on Fri, 17 Jun 2011 00:23:10 GMT


module ti.sysbios.family.arm.Settings

metaonly module ti.sysbios.family.arm.Settings
index URL

Device/Family-specific delegate assignment module for ARM9 target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.arm.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:23:10 GMT


module ti.sysbios.family.arm.TaskSupport
index URL

ARM9 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/arm/TaskSupport.xdc
#include <ti/sysbios/family/arm/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.arm.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 2048;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 8;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 2048;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 8;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:10 GMT


package ti.sysbios.family.arm.a8
index URL

Contains specifications for the a8 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/a8/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.a8 [2, 0, 0, 0] {
    module Cache;
    // ARM Cache Module
    module Mmu;
    // Memory Management Unit Manager
    module TimestampProvider;
    // A8 TimestampProvider
}
generated on Fri, 17 Jun 2011 00:23:12 GMT


module ti.sysbios.family.arm.a8.Cache
index URL

ARM Cache Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages the data and instruction caches on Cortex A8 processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/a8/Cache.xdc
#include <ti/sysbios/family/arm/a8/Cache.h>
Functions
Void | Cache_invL1dAll// Invalidate all of L1 data cache();
Void | Cache_invL1pAll// Invalidate all of L1 program cache();
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Defines
#define | Cache_sizeL1dCacheLine// Size of L1 data cache Line (UInt)64
#define | Cache_sizeL1pCacheLine// Size of L1 program cache Line (UInt)64
Typedefs
typedef enum | Cache_Type// Lists of bitmask cache types ...
Constants
extern const Bool | Cache_enableCache// Enable L1 and L2 data and program caches;
DETAILS
This module manages the data and instruction caches on Cortex A8 processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line.
The L1 data and program caches as well as the L2 cache are enabled by default early during the startup sequence (prior to any Module_startup()s). Data caching requires the MMU to be enabled and the cacheable attribute of the section/page descriptor for a corresponding memory region to be enabled. Program caching does not require the MMU to be enabled and therefore occurs when the L1 program cache is enabled.
Note: See the ti.sysbios.family.arm.a8.Mmu module for information about the MMU.
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
invL1dAll | Y | Y | Y | Y | Y
invL1pAll | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
wbInvL1dAll | Y | Y | Y | Y | Y
wbL1dAll | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
const Cache_sizeL1dCacheLine
index URL

Size of L1 data cache Line

C synopsis target-domain
#define Cache_sizeL1dCacheLine (UInt)64
const Cache_sizeL1pCacheLine
index URL

Size of L1 program cache Line

C synopsis target-domain
#define Cache_sizeL1pCacheLine (UInt)64
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
config Cache_enableCache // module-wide
index URL

Enable L1 and L2 data and program caches

C synopsis target-domain
extern const Bool Cache_enableCache;
DETAILS
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_invL1dAll() // module-wide
index URL

Invalidate all of L1 data cache

C synopsis target-domain
Void Cache_invL1dAll();
DETAILS
This function should be used with caution. In general, the L1 data cache may contain some stack variable or valid data that should not be invalidated. This function should be used only when all contents of L1 data cache is unwanted.
Cache_invL1pAll() // module-wide
index URL

Invalidate all of L1 program cache

C synopsis target-domain
Void Cache_invL1pAll();
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/a8/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.arm.a8.Cache');
module-wide constants & types
    const Cache.sizeL1dCacheLine// Size of L1 data cache Line = 64;
    const Cache.sizeL1pCacheLine// Size of L1 program cache Line = 64;
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
module-wide config parameters
     Cache.enableCache// Enable L1 and L2 data and program caches = Bool true;
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
const Cache.sizeL1dCacheLine
index URL

Size of L1 data cache Line

XDCscript usage meta-domain
const Cache.sizeL1dCacheLine = 64;
C SYNOPSIS
Cache_sizeL1dCacheLine
const Cache.sizeL1pCacheLine
index URL

Size of L1 program cache Line

XDCscript usage meta-domain
const Cache.sizeL1pCacheLine = 64;
C SYNOPSIS
Cache_sizeL1pCacheLine
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
config Cache.enableCache // module-wide
index URL

Enable L1 and L2 data and program caches

XDCscript usage meta-domain
Cache.enableCache = Bool true;
DETAILS
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
C SYNOPSIS
Cache_enableCache
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:12 GMT


module ti.sysbios.family.arm.a8.Mmu
index URL

Memory Management Unit Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module allows the ARM processor to map a virtual address to a different physical address and enable/disable the MMU. It does this through a translation table in memory. The translation table is 16KB and manages only the first level descriptor table. Each entry in the table defines the properties of memory areas of size 1MB. These properties include memory access permissions, cacheability, bufferability, and domain access. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/a8/Mmu.xdc
#include <ti/sysbios/family/arm/a8/Mmu.h>
Functions
Void | Mmu_enable// Enables the MMU();
Void | Mmu_initDescAttrs// Initializes the first level descriptor attribute structure(Mmu_FirstLevelDescAttrs *attrs);
Bool | Mmu_isEnabled// Determines if the MMU is enabled();
Void | Mmu_setFirstLevelDesc// Sets the descriptor for the virtual address(Ptr virtualAddr, Ptr phyAddr, Mmu_FirstLevelDescAttrs *attrs);
Functions common to all target modules
 | Mmu_Module_getMask// Returns the diagnostics mask for this module, Mmu_Module_hasMask// Test whether this module has a diagnostics mask, Mmu_Module_heap// The heap from which this module allocates memory, Mmu_Module_id// Get this module's unique id, Mmu_Module_setMask// Set the diagnostics mask for this module, Mmu_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Mmu_FirstLevelDesc// First Level descriptors ...
typedef struct | Mmu_FirstLevelDescAttrs// Structure for setting first level descriptor entries ...
Constants
extern const Assert_Id | Mmu_A_nullPointer// Assert raised when a pointer is null;
extern const Assert_Id | Mmu_A_unknownDescType// Assert raised when the descriptor type is not recognized;
extern const Mmu_FirstLevelDescAttrs | Mmu_defaultAttrs// default descriptor attributes structure;
extern const Bool | Mmu_enableMMU// Configuration parameter to enable MMU;
DETAILS
This module allows the ARM processor to map a virtual address to a different physical address and enable/disable the MMU. It does this through a translation table in memory. The translation table is 16KB and manages only the first level descriptor table. Each entry in the table defines the properties of memory areas of size 1MB. These properties include memory access permissions, cacheability, bufferability, and domain access.
By default, the MMU translation table is initialized with cache-enabled entries for every memory segment defined in the platform. Cache-disabled entries are also added for the peripheral addresses used by SYS/BIOS (i.e. Timers, Interrupt controller).
The translation table is placed in an output section called "ti.sysbios.family.arm.a8.mmuTableSection". This section is placed into the platform's default dataMemory and specified to not be initialized via the "NOINIT" type.
This module does not manage the second level descriptor tables. A 'SECTION' mapped access requires only a first level fetch. In this case, there is no need for a second level descriptor table. A 'PAGE_TABLE' mapped access requires a second level descriptor table which can be supplied by the user.
The following is an example of how to place the MMU table and how to enable L1 data caching for the address range 0x80000000-0x90000000 in the *.cfg file:
    var Cache = xdc.useModule('ti.sysbios.family.arm.a8.Cache');
    var Mmu = xdc.useModule('ti.sysbios.family.arm.a8.Mmu');

    // Enable the cache
    Cache.enableCache = true;

    // Enable the MMU (Required for L1/L2 data caching)
    Mmu.enableMMU = true;

    // descriptor attribute structure
    var attrs = {
        type: Mmu.FirstLevelDesc_SECTION,  // SECTION descriptor
        bufferable: true,                  // bufferable
        cacheable: true,                   // cacheable
    };

    // Set the descriptor for each entry in the address range
    for (var i=0x80000000; i < 0x90000000; i = i + 0x00100000) {
        // Each 'SECTION' descriptor entry spans a 1MB address range
        Mmu.setFirstLevelDescMeta(i, i, attrs);
    }

    var memmap = Program.cpu.memoryMap;
    var DDR = null;

    // Find DDR in memory map
    for (var i=0; i < memmap.length; i++) {
        if (memmap[i].name == "DDR") {
            DDR = memmap[i];
        }
    }

    // Place the MMU table in the DDR memory segment if it exists
    if (DDR != null) {
        var sectionName = "ti.sysbios.family.arm.a8.mmuTableSection";
        Program.sectMap[sectionName] = new Program.SectionSpec();
        Program.sectMap[sectionName].type = "NOINIT";
        Program.sectMap[sectionName].loadSegment = "DDR";
    }
    else {
        print("No DDR memory segment was found");
    }
Notes:
  • The 'Supersection' table descriptor is NOT supported.
  • The 'not global' page descriptor setting is NOT supported.
  • The 'non-secure' page descriptor setting is NOT supported.
  • There are size and alignment requirements on the second level descriptor tables depending on the page size.
  • See the ARM Architecture Reference Manual for more info.
enum Mmu_FirstLevelDesc
index URL

First Level descriptors

C synopsis target-domain
typedef enum Mmu_FirstLevelDesc {
    Mmu_FirstLevelDesc_FAULT,
    // Virtual address is unmapped
    Mmu_FirstLevelDesc_PAGE_TABLE,
    // Page table addr descriptor
    Mmu_FirstLevelDesc_SECTION
    // Section descriptor
} Mmu_FirstLevelDesc;
struct Mmu_FirstLevelDescAttrs
index URL

Structure for setting first level descriptor entries

C synopsis target-domain
typedef struct Mmu_FirstLevelDescAttrs {
     Mmu_FirstLevelDesc type;
    // first level descriptor type
    Bool bufferable;
    // is memory section bufferable
    Bool cacheable;
    // is memory section cacheable
    Bool shareable;
    // is memory section shareable
    Bool noexecute;
    // is memory section not executable
    UInt8 imp;
    // implementation defined
    UInt8 domain;
    // domain access control value 0-15
    UInt8 accPerm;
    // access permission bits value 0-3
} Mmu_FirstLevelDescAttrs;
DETAILS
If the 'cacheable' attribute is true and 'bufferable' is true, L1 data cache operates as a write-back cache. If 'cacheable' is true but 'bufferable' is false, L1 data cache operates as a write-through cache.
See the 'Translation Tables' section of the ARM v7 Architecture Reference Manual for more details.
config Mmu_A_nullPointer // module-wide
index URL

Assert raised when a pointer is null

C synopsis target-domain
extern const Assert_Id Mmu_A_nullPointer;
config Mmu_A_unknownDescType // module-wide
index URL

Assert raised when the descriptor type is not recognized

C synopsis target-domain
extern const Assert_Id Mmu_A_unknownDescType;
config Mmu_defaultAttrs // module-wide
index URL

default descriptor attributes structure

C synopsis target-domain
extern const Mmu_FirstLevelDescAttrs Mmu_defaultAttrs;
config Mmu_enableMMU // module-wide
index URL

Configuration parameter to enable MMU

C synopsis target-domain
extern const Bool Mmu_enableMMU;
Mmu_enable() // module-wide
index URL

Enables the MMU

C synopsis target-domain
Void Mmu_enable();
DETAILS
If the MMU is already enabled, then simply return. Otherwise this function does the following: If the L1 program cache is enabled, invalidate all of L1 program cache. This function does not change the L1 data/program cache settings.
Mmu_initDescAttrs() // module-wide
index URL

Initializes the first level descriptor attribute structure

C synopsis target-domain
Void Mmu_initDescAttrs(Mmu_FirstLevelDescAttrs *attrs);
ARGUMENTS
attrs — Pointer to first level descriptor attribute struct
Mmu_isEnabled() // module-wide
index URL

Determines if the MMU is enabled

C synopsis target-domain
Bool Mmu_isEnabled();
Mmu_setFirstLevelDesc() // module-wide
index URL

Sets the descriptor for the virtual address

C synopsis target-domain
Void Mmu_setFirstLevelDesc(Ptr virtualAddr, Ptr phyAddr, Mmu_FirstLevelDescAttrs *attrs);
ARGUMENTS
virtualAddr — The modified virtual address
phyAddr — The physical address
attrs — Pointer to first level descriptor attribute struct
DETAILS
The first level table entry for the virtual address is mapped to the physical address with the attributes specified. The descriptor table is effective when the MMU is enabled.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Mmu_Module_id();
// Get this module's unique id
Bool Mmu_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Mmu_Module_heap();
// The heap from which this module allocates memory
Bool Mmu_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Mmu_Module_getMask();
// Returns the diagnostics mask for this module
Void Mmu_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/a8/Mmu.xdc
var Mmu = xdc.useModule('ti.sysbios.family.arm.a8.Mmu');
module-wide constants & types
    values of type Mmu.FirstLevelDesc// First Level descriptors
        const Mmu.FirstLevelDesc_FAULT// Virtual address is unmapped;
        const Mmu.FirstLevelDesc_PAGE_TABLE// Page table addr descriptor;
        const Mmu.FirstLevelDesc_SECTION// Section descriptor;
    var obj = new Mmu.FirstLevelDescAttrs// Structure for setting first level descriptor entries;
        obj.type// first level descriptor type = Mmu.FirstLevelDesc ...
        obj.bufferable// is memory section bufferable = Bool ...
        obj.cacheable// is memory section cacheable = Bool ...
        obj.shareable// is memory section shareable = Bool ...
        obj.noexecute// is memory section not executable = Bool ...
        obj.imp// implementation defined = UInt8 ...
        obj.domain// domain access control value 0-15 = UInt8 ...
        obj.accPerm// access permission bits value 0-3 = UInt8 ...
module-wide config parameters
     Mmu.A_nullPointer// Assert raised when a pointer is null = Assert.Desc {
        msg: "A_nullPointer: Pointer is null"
    };
     Mmu.A_unknownDescType// Assert raised when the descriptor type is not recognized = Assert.Desc {
        msg: "A_unknownDescType: Descriptor type is not recognized"
    };
     Mmu.defaultAttrs// default descriptor attributes structure = Mmu.FirstLevelDescAttrs {
        type: Mmu.FirstLevelDesc_SECTION,
        bufferable: false,
        cacheable: false,
        shareable: false,
        noexecute: false,
        imp: 1,
        domain: 0,
        accPerm: 3
    };
     Mmu.enableMMU// Configuration parameter to enable MMU = Bool true;
     Mmu.cachePlatformMemory// Flag to automatically mark platform's code/data/stack memory as cacheable in MMU descriptor table = Bool true;
     Mmu.common$// Common module configuration parameters = Types.Common$ undefined;
     Mmu.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
module-wide functions
     Mmu.setFirstLevelDescMeta// Statically sets the descriptor for the virtual address(Ptr virtualAddr, Ptr phyAddr, Mmu.FirstLevelDescAttrs attrs) returns Void
enum Mmu.FirstLevelDesc
index URL

First Level descriptors

XDCscript usage meta-domain
values of type Mmu.FirstLevelDesc
    const Mmu.FirstLevelDesc_FAULT;
    // Virtual address is unmapped
    const Mmu.FirstLevelDesc_PAGE_TABLE;
    // Page table addr descriptor
    const Mmu.FirstLevelDesc_SECTION;
    // Section descriptor
C SYNOPSIS
Mmu_FirstLevelDesc
struct Mmu.FirstLevelDescAttrs
index URL

Structure for setting first level descriptor entries

XDCscript usage meta-domain
var obj = new Mmu.FirstLevelDescAttrs;
    obj.type = Mmu.FirstLevelDesc ...
    // first level descriptor type
    obj.bufferable = Bool ...
    // is memory section bufferable
    obj.cacheable = Bool ...
    // is memory section cacheable
    obj.shareable = Bool ...
    // is memory section shareable
    obj.noexecute = Bool ...
    // is memory section not executable
    obj.imp = UInt8 ...
    // implementation defined
    obj.domain = UInt8 ...
    // domain access control value 0-15
    obj.accPerm = UInt8 ...
    // access permission bits value 0-3
DETAILS
If the 'cacheable' attribute is true and 'bufferable' is true, L1 data cache operates as a write-back cache. If 'cacheable' is true but 'bufferable' is false, L1 data cache operates as a write-through cache.
See the 'Translation Tables' section of the ARM v7 Architecture Reference Manual for more details.
C SYNOPSIS
Mmu_FirstLevelDescAttrs
config Mmu.A_nullPointer // module-wide
index URL

Assert raised when a pointer is null

XDCscript usage meta-domain
Mmu.A_nullPointer = Assert.Desc {
    msg: "A_nullPointer: Pointer is null"
};
C SYNOPSIS
Mmu_A_nullPointer
config Mmu.A_unknownDescType // module-wide
index URL

Assert raised when the descriptor type is not recognized

XDCscript usage meta-domain
Mmu.A_unknownDescType = Assert.Desc {
    msg: "A_unknownDescType: Descriptor type is not recognized"
};
C SYNOPSIS
Mmu_A_unknownDescType
config Mmu.defaultAttrs // module-wide
index URL

default descriptor attributes structure

XDCscript usage meta-domain
Mmu.defaultAttrs = Mmu.FirstLevelDescAttrs {
    type: Mmu.FirstLevelDesc_SECTION,
    bufferable: false,
    cacheable: false,
    shareable: false,
    noexecute: false,
    imp: 1,
    domain: 0,
    accPerm: 3
};
C SYNOPSIS
Mmu_defaultAttrs
config Mmu.enableMMU // module-wide
index URL

Configuration parameter to enable MMU

XDCscript usage meta-domain
Mmu.enableMMU = Bool true;
C SYNOPSIS
Mmu_enableMMU
metaonly config Mmu.cachePlatformMemory // module-wide
index URL

Flag to automatically mark platform's code/data/stack memory as cacheable in MMU descriptor table

XDCscript usage meta-domain
Mmu.cachePlatformMemory = Bool true;
DETAILS
By default, all memory regions defined in the platform an application is built with are marked as cacheable.
If manual configuration of memory regions is required, set this config parameter to 'false'.
SEE
xdc.bld.Program.platform
metaonly config Mmu.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Mmu.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Mmu.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
Mmu.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly Mmu.setFirstLevelDescMeta() // module-wide
index URL

Statically sets the descriptor for the virtual address

XDCscript usage meta-domain
Mmu.setFirstLevelDescMeta(Ptr virtualAddr, Ptr phyAddr, Mmu.FirstLevelDescAttrs attrs) returns Void
ARGUMENTS
virtualAddr — The modified virtual address
phyAddr — The physical address
attrs — Pointer to first level descriptor attribute struct
DETAILS
The first level table entry for the virtual address is mapped to the physical address with the attributes specified. The descriptor table is effective when the MMU is enabled.
generated on Fri, 17 Jun 2011 00:23:12 GMT


module ti.sysbios.family.arm.a8.TimestampProvider
index URL

A8 TimestampProvider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The source of the timestamps for the A8 TimestampProvider is the A8's internal PMC counter which counts CPU cycles. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/a8/TimestampProvider.xdc
#include <ti/sysbios/family/arm/a8/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
DETAILS
The source of the timestamps for the A8 TimestampProvider is the A8's internal PMC counter which counts CPU cycles.
As this counter is only 32 bits in length, provision is made in the get64() API to test if an overflow has occurred since the last invocation of get64() and compensate the return value accordingly.
As it is possible for the 32 bit counter to roll over more than once between successive get64() calls, it is up to the user to call the get64() API often enough to guarantee coherency in successive timestamps. A simple mechanism to do this would be to add a Clock function that simply invokes get64():
  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
  var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.a8.TimestampProvider');
  var clockParams = new Clock.Params();
  clockParams.period = 1;     // call every Clock tick
  Clock.create($externModFxn(TimestampProvider.get64), 1, clockParams);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/a8/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.a8.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:12 GMT


package ti.sysbios.family.arm.a8.intcps
index URL

Contains specifications for the a8 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/a8/intcps/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.a8.intcps [2, 0, 0, 0] {
    module Hwi;
    // Hardware Interrupt Support Module
}
generated on Fri, 17 Jun 2011 00:23:14 GMT


module ti.sysbios.family.arm.a8.intcps.Hwi
index URL

Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/a8/intcps/Hwi.xdc
#include <ti/sysbios/family/arm/a8/intcps/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
UInt | Hwi_disableFIQ// Disable FIQ interrupts();
UInt | Hwi_disableIRQ// Disable IRQ interrupts();
Bits32 | Hwi_disableMIR0// Disable specific interrupts(Bits32 mask);
Bits32 | Hwi_disableMIR1// (Bits32 mask);
Bits32 | Hwi_disableMIR2// (Bits32 mask);
Bits32 | Hwi_disableMIR3// (Bits32 mask);
UInt | Hwi_enableFIQ// Enable FIQ interrupts();
UInt | Hwi_enableIRQ// Enable IRQ interrupts();
Bits32 | Hwi_enableMIR0// Enable specific interrupts(Bits32 mask);
Bits32 | Hwi_enableMIR1// (Bits32 mask);
Bits32 | Hwi_enableMIR2// (Bits32 mask);
Bits32 | Hwi_enableMIR3// (Bits32 mask);
Hwi_Handle | Hwi_getHandle// Returns Hwi_Handle associated with intNum(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Void | Hwi_restoreFIQ// Restore FIQ interrupts(UInt key);
Void | Hwi_restoreIRQ// Restore IRQ interrupts(UInt key);
Bits32 | Hwi_restoreMIR0// Restore maskable interrupts to the state they were in when either disableMIR0() or enableMIR0() was called(Bits32 mask);
Bits32 | Hwi_restoreMIR1// (Bits32 mask);
Bits32 | Hwi_restoreMIR2// (Bits32 mask);
Bits32 | Hwi_restoreMIR3// (Bits32 mask);
Void | Hwi_setPriority// Set an interrupt's priority(UInt intNum, UInt priority);
Void | Hwi_setType// Set an interrupt's type (FIQ/IRQ)(UInt intNum, Hwi_Type type);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// intcps supports 128 interrupts (Int)128
Typedefs
typedef struct | Hwi_ExcContext// Exception Context - Register contents at the time of an exception ...
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef struct | Hwi_Intc// Interrupt Controller. Symbol "Hwi_intc" is physical device ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef enum | Hwi_Type// Interrupt type. IRQ or FIQ ...
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Ptr | Hwi_excStack// Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when an attempt is made to create a Hwi that has already been created;
extern const Error_Id | Hwi_E_badIntNum// Error raised if an attempt is made to create a Hwi with an interrupt number greater than NUM_INTERRUPTS - 1;
extern const Error_Id | Hwi_E_excMin// Error raised when an exception occurs;
extern const Error_Id | Hwi_E_undefined// Error raised when an undefined interrupt has fired;
extern const Ptr | Hwi_fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const Bits32 | Hwi_mir0Mask// Initial MIR0 Interrupt Mask. Default is 0xffffffff;
extern const Bits32 | Hwi_mir1Mask// Initial MIR1 Interrupt Mask. Default is 0xffffffff;
extern const Bits32 | Hwi_mir2Mask// Initial MIR2 Interrupt Mask. Default is 0xffffffff;
extern const Bits32 | Hwi_mir3Mask// Initial MIR3 Interrupt Mask. Default is 0xffffffff;
DETAILS
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi.
Additional ARM device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.
const Hwi_NUM_INTERRUPTS
index URL

intcps supports 128 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)128
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
enum Hwi_Type
index URL

Interrupt type. IRQ or FIQ

C synopsis target-domain
typedef enum Hwi_Type {
    Hwi_Type_IRQ,
    // IRQ interrupt
    Hwi_Type_FIQ
    // FIQ interrupt
} Hwi_Type;
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_ExcContext
index URL

Exception Context - Register contents at the time of an exception

C synopsis target-domain
typedef struct Hwi_ExcContext {
     BIOS_ThreadType threadType;
    Ptr threadHandle;
    Ptr threadStack;
    Ptr r0;
    Ptr r1;
    Ptr r2;
    Ptr r3;
    Ptr r4;
    Ptr r5;
    Ptr r6;
    Ptr r7;
    Ptr r8;
    Ptr r9;
    Ptr r10;
    Ptr r11;
    Ptr r12;
    Ptr sp;
    Ptr lr;
    Ptr pc;
    Ptr psr;
} Hwi_ExcContext;
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
struct Hwi_Intc
index URL

Interrupt Controller. Symbol "Hwi_intc" is physical device

C synopsis target-domain
typedef struct Hwi_Intc {
    UInt32 REVISION;
    // 0x00 Config Register
    UInt32 hole0[3];
    // 0x04-0x0C
    UInt32 SYSCONFIG;
    // 0x10 Config Register
    UInt32 SYSSTATUS;
    // 0x14 Status Register
    UInt32 hole1[10];
    // 0x18-0x3c
    UInt32 SIR_IRQ;
    // 0x40 Source IRQ Register
    UInt32 SIR_FIQ;
    // 0x44 Source FIQ Register
    UInt32 CONTROL;
    // 0x48 Control Register
    UInt32 PROTECTION;
    // 0x4C Protection Register
    UInt32 IDLE;
    // 0x50 Idle Register
    UInt32 hole2[3];
    // 0x54-0x5C
    UInt32 IRQ_PRIORITY;
    // 0x60 IRQ Priority Register
    UInt32 FIQ_PRIORITY;
    // 0x64 IRQ Priority Register
    UInt32 THRESHOLD;
    // 0x68 Threshold Register
    UInt32 hole3[5];
    // 0x6C-0x7C
    UInt32 ITR0;
    // 0x80 Interrupt Input Register
    UInt32 MIR0;
    // 0x84 Mask Interrupt Register
    UInt32 MIR_CLEAR0;
    // 0x88 MIR Clear Register
    UInt32 MIR_SET0;
    // 0x8C MIR Set Register
    UInt32 ISR_SET0;
    // 0x90 Interrupt Set Register
    UInt32 ISR_CLEAR0;
    // 0x94 Interrupt Clear Register
    UInt32 PENDING_IRQ0;
    // 0x98 Pending IRQ Register
    UInt32 PENDING_FIQ0;
    // 0x9C Pending FIQ Register
    UInt32 ITR1;
    // 0xA0 Interrupt Input Register
    UInt32 MIR1;
    // 0xA4 Mask Interrupt Register
    UInt32 MIR_CLEAR1;
    // 0xA8 MIR Clear Register
    UInt32 MIR_SET1;
    // 0xAC MIR Set Register
    UInt32 ISR_SET1;
    // 0xB0 Interrupt Set Register
    UInt32 ISR_CLEAR1;
    // 0xB4 Interrupt Clear Register
    UInt32 PENDING_IRQ1;
    // 0xB8 Pending IRQ Register
    UInt32 PENDING_FIQ1;
    // 0xBC Pending FIQ Register
    UInt32 ITR2;
    // 0xC0 Interrupt Input Register
    UInt32 MIR2;
    // 0xC4 Mask Interrupt Register
    UInt32 MIR_CLEAR2;
    // 0xC8 MIR Clear Register
    UInt32 MIR_SET2;
    // 0xCC MIR Set Register
    UInt32 ISR_SET2;
    // 0xD0 Interrupt Set Register
    UInt32 ISR_CLEAR2;
    // 0xD4 Interrupt Clear Register
    UInt32 PENDING_IRQ2;
    // 0xD8 Pending IRQ Register
    UInt32 PENDING_FIQ2;
    // 0xDC Pending FIQ Register
    UInt32 ITR3;
    // 0xE0 Interrupt Input Register
    UInt32 MIR3;
    // 0xE4 Mask Interrupt Register
    UInt32 MIR_CLEAR3;
    // 0xE8 MIR Clear Register
    UInt32 MIR_SET3;
    // 0xEC MIR Set Register
    UInt32 ISR_SET3;
    // 0xF0 Interrupt Set Register
    UInt32 ISR_CLEAR3;
    // 0xF4 Interrupt Clear Register
    UInt32 PENDING_IRQ3;
    // 0xF8 Pending IRQ Register
    UInt32 PENDING_FIQ3;
    // 0xFC Pending FIQ Register
    UInt32 ILR[128];
    // 0x100 thru 0x2FC
} Hwi_Intc;
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when an attempt is made to create a Hwi that has already been created

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_badIntNum // module-wide
index URL

Error raised if an attempt is made to create a Hwi with an interrupt number greater than NUM_INTERRUPTS - 1

C synopsis target-domain
extern const Error_Id Hwi_E_badIntNum;
config Hwi_E_excMin // module-wide
index URL

Error raised when an exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_excMin;
config Hwi_E_undefined // module-wide
index URL

Error raised when an undefined interrupt has fired

C synopsis target-domain
extern const Error_Id Hwi_E_undefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_excStack // module-wide
index URL

Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_excStack;
config Hwi_fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_fiqStack;
config Hwi_mir0Mask // module-wide
index URL

Initial MIR0 Interrupt Mask. Default is 0xffffffff

C synopsis target-domain
extern const Bits32 Hwi_mir0Mask;
config Hwi_mir1Mask // module-wide
index URL

Initial MIR1 Interrupt Mask. Default is 0xffffffff

C synopsis target-domain
extern const Bits32 Hwi_mir1Mask;
config Hwi_mir2Mask // module-wide
index URL

Initial MIR2 Interrupt Mask. Default is 0xffffffff

C synopsis target-domain
extern const Bits32 Hwi_mir2Mask;
config Hwi_mir3Mask // module-wide
index URL

Initial MIR3 Interrupt Mask. Default is 0xffffffff

C synopsis target-domain
extern const Bits32 Hwi_mir3Mask;
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableFIQ() // module-wide
index URL

Disable FIQ interrupts

C synopsis target-domain
UInt Hwi_disableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_disableIRQ() // module-wide
index URL

Disable IRQ interrupts

C synopsis target-domain
UInt Hwi_disableIRQ();
RETURNS
previous IRQ interrupt enable/disable state
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_disableMIR0() // module-wide
index URL

Disable specific interrupts

C synopsis target-domain
Bits32 Hwi_disableMIR0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous MIR0 settings bitmask
DETAILS
Disables specific interrupts by setting the bits specified by mask in the Mask Interrupts Register (MIR).
Hwi_disableMIR1() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_disableMIR1(Bits32 mask);
Hwi_disableMIR2() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_disableMIR2(Bits32 mask);
Hwi_disableMIR3() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_disableMIR3(Bits32 mask);
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableFIQ() // module-wide
index URL

Enable FIQ interrupts

C synopsis target-domain
UInt Hwi_enableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_enableIRQ() // module-wide
index URL

Enable IRQ interrupts

C synopsis target-domain
UInt Hwi_enableIRQ();
ARGUMENTS
key — enable/disable state to restore
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_enableMIR0() // module-wide
index URL

Enable specific interrupts

C synopsis target-domain
Bits32 Hwi_enableMIR0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to enable
RETURNS
previous MIR settings bitmask
DETAILS
Enables specific interrupts by clearing the bits specified by mask in the Mask Interrupts Register (MIR).
Hwi_enableMIR1() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_enableMIR1(Bits32 mask);
Hwi_enableMIR2() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_enableMIR2(Bits32 mask);
Hwi_enableMIR3() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_enableMIR3(Bits32 mask);
Hwi_getHandle() // module-wide
index URL

Returns Hwi_Handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreFIQ() // module-wide
index URL

Restore FIQ interrupts

C synopsis target-domain
Void Hwi_restoreFIQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreIRQ() // module-wide
index URL

Restore IRQ interrupts

C synopsis target-domain
Void Hwi_restoreIRQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_restoreMIR0() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableMIR0() or enableMIR0() was called

C synopsis target-domain
Bits32 Hwi_restoreMIR0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous MIR0 settings bitmask
DETAILS
Simply writes mask to the MIR register.
Hwi_restoreMIR1() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_restoreMIR1(Bits32 mask);
Hwi_restoreMIR2() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_restoreMIR2(Bits32 mask);
Hwi_restoreMIR3() // module-wide
index URL
C synopsis target-domain
Bits32 Hwi_restoreMIR3(Bits32 mask);
Hwi_setPriority() // module-wide
index URL

Set an interrupt's priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
ARGUMENTS
intNum — ID of interrupt
priority — priority
DETAILS
Not an instance function so that it can be used with non-dispatched interrupts.
Hwi_setType() // module-wide
index URL

Set an interrupt's type (FIQ/IRQ)

C synopsis target-domain
Void Hwi_setType(UInt intNum, Hwi_Type type);
ARGUMENTS
intNum — ID of interrupt
type — type = FIQ/IRQ
DETAILS
Not an instance function so that it can be used with non-dispatched interrupts.
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // The interrupt controller is designed for priority based interrupts
    Int priority;
    // Interrupt priority
     Hwi_Type type;
    // Interrupt type (IRQ/FIQ. Default is IRQ
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

The interrupt controller is designed for priority based interrupts

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_type // instance
index URL

Interrupt type (IRQ/FIQ. Default is IRQ

C synopsis target-domain
struct Hwi_Params {
     ...
     Hwi_Type type;
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/a8/intcps/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.a8.intcps.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// intcps supports 128 interrupts = 128;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    values of type Hwi.Type// Interrupt type. IRQ or FIQ
        const Hwi.Type_IRQ// IRQ interrupt;
        const Hwi.Type_FIQ// FIQ interrupt;
    var obj = new Hwi.ExcContext// Exception Context - Register contents at the time of an exception;
        obj.threadType = BIOS.ThreadType ...
        obj.threadHandle = Ptr ...
        obj.threadStack = Ptr ...
        obj.r0 = Ptr ...
        obj.r1 = Ptr ...
        obj.r2 = Ptr ...
        obj.r3 = Ptr ...
        obj.r4 = Ptr ...
        obj.r5 = Ptr ...
        obj.r6 = Ptr ...
        obj.r7 = Ptr ...
        obj.r8 = Ptr ...
        obj.r9 = Ptr ...
        obj.r10 = Ptr ...
        obj.r11 = Ptr ...
        obj.r12 = Ptr ...
        obj.sp = Ptr ...
        obj.lr = Ptr ...
        obj.pc = Ptr ...
        obj.psr = Ptr ...
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.Intc// Interrupt Controller. Symbol "Hwi_intc" is physical device;
        obj.REVISION// 0x00 Config Register = UInt32 ...
        obj.hole0// 0x04-0x0C = UInt32[3] ...
        obj.SYSCONFIG// 0x10 Config Register = UInt32 ...
        obj.SYSSTATUS// 0x14 Status Register = UInt32 ...
        obj.hole1// 0x18-0x3c = UInt32[10] ...
        obj.SIR_IRQ// 0x40 Source IRQ Register = UInt32 ...
        obj.SIR_FIQ// 0x44 Source FIQ Register = UInt32 ...
        obj.CONTROL// 0x48 Control Register = UInt32 ...
        obj.PROTECTION// 0x4C Protection Register = UInt32 ...
        obj.IDLE// 0x50 Idle Register = UInt32 ...
        obj.hole2// 0x54-0x5C = UInt32[3] ...
        obj.IRQ_PRIORITY// 0x60 IRQ Priority Register = UInt32 ...
        obj.FIQ_PRIORITY// 0x64 IRQ Priority Register = UInt32 ...
        obj.THRESHOLD// 0x68 Threshold Register = UInt32 ...
        obj.hole3// 0x6C-0x7C = UInt32[5] ...
        obj.ITR0// 0x80 Interrupt Input Register = UInt32 ...
        obj.MIR0// 0x84 Mask Interrupt Register = UInt32 ...
        obj.MIR_CLEAR0// 0x88 MIR Clear Register = UInt32 ...
        obj.MIR_SET0// 0x8C MIR Set Register = UInt32 ...
        obj.ISR_SET0// 0x90 Interrupt Set Register = UInt32 ...
        obj.ISR_CLEAR0// 0x94 Interrupt Clear Register = UInt32 ...
        obj.PENDING_IRQ0// 0x98 Pending IRQ Register = UInt32 ...
        obj.PENDING_FIQ0// 0x9C Pending FIQ Register = UInt32 ...
        obj.ITR1// 0xA0 Interrupt Input Register = UInt32 ...
        obj.MIR1// 0xA4 Mask Interrupt Register = UInt32 ...
        obj.MIR_CLEAR1// 0xA8 MIR Clear Register = UInt32 ...
        obj.MIR_SET1// 0xAC MIR Set Register = UInt32 ...
        obj.ISR_SET1// 0xB0 Interrupt Set Register = UInt32 ...
        obj.ISR_CLEAR1// 0xB4 Interrupt Clear Register = UInt32 ...
        obj.PENDING_IRQ1// 0xB8 Pending IRQ Register = UInt32 ...
        obj.PENDING_FIQ1// 0xBC Pending FIQ Register = UInt32 ...
        obj.ITR2// 0xC0 Interrupt Input Register = UInt32 ...
        obj.MIR2// 0xC4 Mask Interrupt Register = UInt32 ...
        obj.MIR_CLEAR2// 0xC8 MIR Clear Register = UInt32 ...
        obj.MIR_SET2// 0xCC MIR Set Register = UInt32 ...
        obj.ISR_SET2// 0xD0 Interrupt Set Register = UInt32 ...
        obj.ISR_CLEAR2// 0xD4 Interrupt Clear Register = UInt32 ...
        obj.PENDING_IRQ2// 0xD8 Pending IRQ Register = UInt32 ...
        obj.PENDING_FIQ2// 0xDC Pending FIQ Register = UInt32 ...
        obj.ITR3// 0xE0 Interrupt Input Register = UInt32 ...
        obj.MIR3// 0xE4 Mask Interrupt Register = UInt32 ...
        obj.MIR_CLEAR3// 0xE8 MIR Clear Register = UInt32 ...
        obj.MIR_SET3// 0xEC MIR Set Register = UInt32 ...
        obj.ISR_SET3// 0xF0 Interrupt Set Register = UInt32 ...
        obj.ISR_CLEAR3// 0xF4 Interrupt Clear Register = UInt32 ...
        obj.PENDING_IRQ3// 0xF8 Pending IRQ Register = UInt32 ...
        obj.PENDING_FIQ3// 0xFC Pending FIQ Register = UInt32 ...
        obj.ILR// 0x100 thru 0x2FC = UInt32[128] ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when an attempt is made to create a Hwi that has already been created = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined, intnum: %d"
    };
     Hwi.E_badIntNum// Error raised if an attempt is made to create a Hwi with an interrupt number greater than NUM_INTERRUPTS - 1 = Error.Desc {
        msg: "E_badIntNum, intnum: %d is out of range"
    };
     Hwi.E_excMin// Error raised when an exception occurs = Error.Desc {
        msg: "E_exception: pc = 0x%08x, lr = 0x%08x."
    };
     Hwi.E_undefined// Error raised when an undefined interrupt has fired = Error.Desc {
        msg: "E_undefined: Hwi undefined, intnum: %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.excStack// Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.mir0Mask// Initial MIR0 Interrupt Mask. Default is 0xffffffff = Bits32 0xffffffff;
     Hwi.mir1Mask// Initial MIR1 Interrupt Mask. Default is 0xffffffff = Bits32 0xffffffff;
     Hwi.mir2Mask// Initial MIR2 Interrupt Mask. Default is 0xffffffff = Bits32 0xffffffff;
     Hwi.mir3Mask// Initial MIR3 Interrupt Mask. Default is 0xffffffff = Bits32 0xffffffff;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.dataAbortFunc// Data abort exception handler. Default is an internal exception handler = Void(*)(Void) undefined;
     Hwi.enableException// Enable full exception decoding = Bool false;
     Hwi.excStackSection// Memory section used for Exception stack Default is null = String null;
     Hwi.excStackSize// Exception stack size in MAUs. Default is 1024 bytes = SizeT 1024;
     Hwi.fiqFunc// FIQ interrupt handler. Default is internal FIQ dispatcher = Void(*)(Void) undefined;
     Hwi.fiqStackSection// Memory section used for FIQ stack Default is null = String null;
     Hwi.fiqStackSize// FIQ stack size in MAUs. Default is 1024 bytes = SizeT 1024;
     Hwi.irqFunc// IRQ interrupt handler. Default is internal IRQ dispatcher = Void(*)(Void) undefined;
     Hwi.prefetchAbortFunc// Prefetch abort exception handler. Default is an internal exception handler = Void(*)(Void) undefined;
     Hwi.reservedFunc// Reserved exception handler. Default is an internal exception handler = Void(*)(Void) undefined;
     Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
     Hwi.swiFunc// SWI Handler. Default is internal SWI handler. Default is an internal exception handler = Void(*)(Void) undefined;
     Hwi.undefinedInstFunc// Undefined instruction exception handler. Default is an internal exception handler = Void(*)(Void) undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// The interrupt controller is designed for priority based interrupts = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
        params.priority// Interrupt priority = Int 63;
        params.type// Interrupt type (IRQ/FIQ. Default is IRQ = Hwi.Type Hwi.Type_IRQ;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

intcps supports 128 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 128;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
enum Hwi.Type
index URL

Interrupt type. IRQ or FIQ

XDCscript usage meta-domain
values of type Hwi.Type
    const Hwi.Type_IRQ;
    // IRQ interrupt
    const Hwi.Type_FIQ;
    // FIQ interrupt
C SYNOPSIS
Hwi_Type
struct Hwi.ExcContext
index URL

Exception Context - Register contents at the time of an exception

XDCscript usage meta-domain
var obj = new Hwi.ExcContext;
    obj.threadType = BIOS.ThreadType ...
    obj.threadHandle = Ptr ...
    obj.threadStack = Ptr ...
    obj.r0 = Ptr ...
    obj.r1 = Ptr ...
    obj.r2 = Ptr ...
    obj.r3 = Ptr ...
    obj.r4 = Ptr ...
    obj.r5 = Ptr ...
    obj.r6 = Ptr ...
    obj.r7 = Ptr ...
    obj.r8 = Ptr ...
    obj.r9 = Ptr ...
    obj.r10 = Ptr ...
    obj.r11 = Ptr ...
    obj.r12 = Ptr ...
    obj.sp = Ptr ...
    obj.lr = Ptr ...
    obj.pc = Ptr ...
    obj.psr = Ptr ...
C SYNOPSIS
Hwi_ExcContext
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
struct Hwi.Intc
index URL

Interrupt Controller. Symbol "Hwi_intc" is physical device

XDCscript usage meta-domain
var obj = new Hwi.Intc;
    obj.REVISION = UInt32 ...
    // 0x00 Config Register
    obj.hole0 = UInt32[3] ...
    // 0x04-0x0C
    obj.SYSCONFIG = UInt32 ...
    // 0x10 Config Register
    obj.SYSSTATUS = UInt32 ...
    // 0x14 Status Register
    obj.hole1 = UInt32[10] ...
    // 0x18-0x3c
    obj.SIR_IRQ = UInt32 ...
    // 0x40 Source IRQ Register
    obj.SIR_FIQ = UInt32 ...
    // 0x44 Source FIQ Register
    obj.CONTROL = UInt32 ...
    // 0x48 Control Register
    obj.PROTECTION = UInt32 ...
    // 0x4C Protection Register
    obj.IDLE = UInt32 ...
    // 0x50 Idle Register
    obj.hole2 = UInt32[3] ...
    // 0x54-0x5C
    obj.IRQ_PRIORITY = UInt32 ...
    // 0x60 IRQ Priority Register
    obj.FIQ_PRIORITY = UInt32 ...
    // 0x64 IRQ Priority Register
    obj.THRESHOLD = UInt32 ...
    // 0x68 Threshold Register
    obj.hole3 = UInt32[5] ...
    // 0x6C-0x7C
    obj.ITR0 = UInt32 ...
    // 0x80 Interrupt Input Register
    obj.MIR0 = UInt32 ...
    // 0x84 Mask Interrupt Register
    obj.MIR_CLEAR0 = UInt32 ...
    // 0x88 MIR Clear Register
    obj.MIR_SET0 = UInt32 ...
    // 0x8C MIR Set Register
    obj.ISR_SET0 = UInt32 ...
    // 0x90 Interrupt Set Register
    obj.ISR_CLEAR0 = UInt32 ...
    // 0x94 Interrupt Clear Register
    obj.PENDING_IRQ0 = UInt32 ...
    // 0x98 Pending IRQ Register
    obj.PENDING_FIQ0 = UInt32 ...
    // 0x9C Pending FIQ Register
    obj.ITR1 = UInt32 ...
    // 0xA0 Interrupt Input Register
    obj.MIR1 = UInt32 ...
    // 0xA4 Mask Interrupt Register
    obj.MIR_CLEAR1 = UInt32 ...
    // 0xA8 MIR Clear Register
    obj.MIR_SET1 = UInt32 ...
    // 0xAC MIR Set Register
    obj.ISR_SET1 = UInt32 ...
    // 0xB0 Interrupt Set Register
    obj.ISR_CLEAR1 = UInt32 ...
    // 0xB4 Interrupt Clear Register
    obj.PENDING_IRQ1 = UInt32 ...
    // 0xB8 Pending IRQ Register
    obj.PENDING_FIQ1 = UInt32 ...
    // 0xBC Pending FIQ Register
    obj.ITR2 = UInt32 ...
    // 0xC0 Interrupt Input Register
    obj.MIR2 = UInt32 ...
    // 0xC4 Mask Interrupt Register
    obj.MIR_CLEAR2 = UInt32 ...
    // 0xC8 MIR Clear Register
    obj.MIR_SET2 = UInt32 ...
    // 0xCC MIR Set Register
    obj.ISR_SET2 = UInt32 ...
    // 0xD0 Interrupt Set Register
    obj.ISR_CLEAR2 = UInt32 ...
    // 0xD4 Interrupt Clear Register
    obj.PENDING_IRQ2 = UInt32 ...
    // 0xD8 Pending IRQ Register
    obj.PENDING_FIQ2 = UInt32 ...
    // 0xDC Pending FIQ Register
    obj.ITR3 = UInt32 ...
    // 0xE0 Interrupt Input Register
    obj.MIR3 = UInt32 ...
    // 0xE4 Mask Interrupt Register
    obj.MIR_CLEAR3 = UInt32 ...
    // 0xE8 MIR Clear Register
    obj.MIR_SET3 = UInt32 ...
    // 0xEC MIR Set Register
    obj.ISR_SET3 = UInt32 ...
    // 0xF0 Interrupt Set Register
    obj.ISR_CLEAR3 = UInt32 ...
    // 0xF4 Interrupt Clear Register
    obj.PENDING_IRQ3 = UInt32 ...
    // 0xF8 Pending IRQ Register
    obj.PENDING_FIQ3 = UInt32 ...
    // 0xFC Pending FIQ Register
    obj.ILR = UInt32[128] ...
    // 0x100 thru 0x2FC
C SYNOPSIS
Hwi_Intc
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when an attempt is made to create a Hwi that has already been created

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined, intnum: %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_badIntNum // module-wide
index URL

Error raised if an attempt is made to create a Hwi with an interrupt number greater than NUM_INTERRUPTS - 1

XDCscript usage meta-domain
Hwi.E_badIntNum = Error.Desc {
    msg: "E_badIntNum, intnum: %d is out of range"
};
C SYNOPSIS
Hwi_E_badIntNum
config Hwi.E_excMin // module-wide
index URL

Error raised when an exception occurs

XDCscript usage meta-domain
Hwi.E_excMin = Error.Desc {
    msg: "E_exception: pc = 0x%08x, lr = 0x%08x."
};
C SYNOPSIS
Hwi_E_excMin
config Hwi.E_undefined // module-wide
index URL

Error raised when an undefined interrupt has fired

XDCscript usage meta-domain
Hwi.E_undefined = Error.Desc {
    msg: "E_undefined: Hwi undefined, intnum: %d"
};
C SYNOPSIS
Hwi_E_undefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.excStack // module-wide
index URL

Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.excStack = Ptr null;
C SYNOPSIS
Hwi_excStack
config Hwi.fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.fiqStack = Ptr null;
C SYNOPSIS
Hwi_fiqStack
config Hwi.mir0Mask // module-wide
index URL

Initial MIR0 Interrupt Mask. Default is 0xffffffff

XDCscript usage meta-domain
Hwi.mir0Mask = Bits32 0xffffffff;
C SYNOPSIS
Hwi_mir0Mask
config Hwi.mir1Mask // module-wide
index URL

Initial MIR1 Interrupt Mask. Default is 0xffffffff

XDCscript usage meta-domain
Hwi.mir1Mask = Bits32 0xffffffff;
C SYNOPSIS
Hwi_mir1Mask
config Hwi.mir2Mask // module-wide
index URL

Initial MIR2 Interrupt Mask. Default is 0xffffffff

XDCscript usage meta-domain
Hwi.mir2Mask = Bits32 0xffffffff;
C SYNOPSIS
Hwi_mir2Mask
config Hwi.mir3Mask // module-wide
index URL

Initial MIR3 Interrupt Mask. Default is 0xffffffff

XDCscript usage meta-domain
Hwi.mir3Mask = Bits32 0xffffffff;
C SYNOPSIS
Hwi_mir3Mask
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.dataAbortFunc // module-wide
index URL

Data abort exception handler. Default is an internal exception handler

XDCscript usage meta-domain
Hwi.dataAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.enableException // module-wide
index URL

Enable full exception decoding

XDCscript usage meta-domain
Hwi.enableException = Bool false;
DETAILS
When this is enabled, the exception handler will fully decode an exception and dump the registers to the system console.
metaonly config Hwi.excStackSection // module-wide
index URL

Memory section used for Exception stack Default is null

XDCscript usage meta-domain
Hwi.excStackSection = String null;
metaonly config Hwi.excStackSize // module-wide
index URL

Exception stack size in MAUs. Default is 1024 bytes

XDCscript usage meta-domain
Hwi.excStackSize = SizeT 1024;
metaonly config Hwi.fiqFunc // module-wide
index URL

FIQ interrupt handler. Default is internal FIQ dispatcher

XDCscript usage meta-domain
Hwi.fiqFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqStackSection // module-wide
index URL

Memory section used for FIQ stack Default is null

XDCscript usage meta-domain
Hwi.fiqStackSection = String null;
metaonly config Hwi.fiqStackSize // module-wide
index URL

FIQ stack size in MAUs. Default is 1024 bytes

XDCscript usage meta-domain
Hwi.fiqStackSize = SizeT 1024;
metaonly config Hwi.irqFunc // module-wide
index URL

IRQ interrupt handler. Default is internal IRQ dispatcher

XDCscript usage meta-domain
Hwi.irqFunc = Void(*)(Void) undefined;
metaonly config Hwi.prefetchAbortFunc // module-wide
index URL

Prefetch abort exception handler. Default is an internal exception handler

XDCscript usage meta-domain
Hwi.prefetchAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.reservedFunc // module-wide
index URL

Reserved exception handler. Default is an internal exception handler

XDCscript usage meta-domain
Hwi.reservedFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetFunc // module-wide
index URL

Reset Handler. Default is c_int00

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
metaonly config Hwi.swiFunc // module-wide
index URL

SWI Handler. Default is internal SWI handler. Default is an internal exception handler

XDCscript usage meta-domain
Hwi.swiFunc = Void(*)(Void) undefined;
metaonly config Hwi.undefinedInstFunc // module-wide
index URL

Undefined instruction exception handler. Default is an internal exception handler

XDCscript usage meta-domain
Hwi.undefinedInstFunc = Void(*)(Void) undefined;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
    // The interrupt controller is designed for priority based interrupts
    params.priority = Int 63;
    // Interrupt priority
    params.type = Hwi.Type Hwi.Type_IRQ;
    // Interrupt type (IRQ/FIQ. Default is IRQ
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

The interrupt controller is designed for priority based interrupts

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 63;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.type // instance
index URL

Interrupt type (IRQ/FIQ. Default is IRQ

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.type = Hwi.Type Hwi.Type_IRQ;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:14 GMT


package ti.sysbios.family.arm.a8.omap3430
index URL

Contains specifications for the a8 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/a8/omap3430/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.a8.omap3430 [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:23:15 GMT


package ti.sysbios.family.arm.a8.sim
index URL

Contains specifications for the a8 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/a8/sim/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.a8.sim [2, 0, 0, 0] {
    module TaskSupport;
    // ARM9 Task Support Module
}
generated on Fri, 17 Jun 2011 00:23:15 GMT


module ti.sysbios.family.arm.a8.sim.TaskSupport
index URL

ARM9 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/arm/a8/sim/TaskSupport.xdc
#include <ti/sysbios/family/arm/a8/sim/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/a8/sim/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.arm.a8.sim.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 2048;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 8;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 2048;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 8;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:15 GMT


package ti.sysbios.family.arm.a8.ti81xx
index URL

Contains specifications for the a8 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/a8/ti81xx/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.a8.ti81xx [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:23:12 GMT


package ti.sysbios.family.arm.arm9
index URL

Contains specifications for the ARM9 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/arm9/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.arm9 [2, 0, 0, 0] {
    module Cache;
    // ARM Cache Module
    module Mmu;
    // Memory Management Unit Manager
}
generated on Fri, 17 Jun 2011 00:23:16 GMT


module ti.sysbios.family.arm.arm9.Cache
index URL

ARM Cache Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages the data and instruction caches on ARM processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/arm9/Cache.xdc
#include <ti/sysbios/family/arm/arm9/Cache.h>
Functions
Void | Cache_invL1dAll// Invalidate all of L1 data cache();
Void | Cache_invL1pAll// Invalidate all of L1 program cache();
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Defines
#define | Cache_sizeL1dCacheLine// Size of L1 data cache Line (UInt)32
#define | Cache_sizeL1pCacheLine// Size of L1 program cache Line (UInt)32
Typedefs
typedef enum | Cache_Type// Lists of bitmask cache types ...
Constants
extern const Bool | Cache_enableCache// Enable L1 data and program caches;
DETAILS
This module manages the data and instruction caches on ARM processors. It provides a list of functions that perform cache operations. The functions operate on a per cache line except for the 'All' functions which operate on the entire cache specified. Any Address that is not aligned to a cache line gets rounded down to the address of the nearest cache line.
The L1 data and program caches are enabled by default early during the startup sequence (prior to any Module_startup()s). Data caching requires the MMU to be enabled and the cacheable attribute of the section/page descriptor for a corresponding memory region to be enabled. Program caching does not require the MMU to be enabled and therefore occurs when the L1 program cache is enabled.
Note: See the ti.sysbios.family.arm.arm9.Mmu module for information about the MMU.
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
invL1dAll | Y | Y | Y | Y | Y
invL1pAll | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
wbInvL1dAll | Y | Y | Y | Y | Y
wbL1dAll | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
const Cache_sizeL1dCacheLine
index URL

Size of L1 data cache Line

C synopsis target-domain
#define Cache_sizeL1dCacheLine (UInt)32
const Cache_sizeL1pCacheLine
index URL

Size of L1 program cache Line

C synopsis target-domain
#define Cache_sizeL1pCacheLine (UInt)32
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
config Cache_enableCache // module-wide
index URL

Enable L1 data and program caches

C synopsis target-domain
extern const Bool Cache_enableCache;
DETAILS
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_invL1dAll() // module-wide
index URL

Invalidate all of L1 data cache

C synopsis target-domain
Void Cache_invL1dAll();
DETAILS
This function should be used with caution. In general, the L1 data cache may contain some stack variable or valid data that should not be invalidated. This function should be used only when all contents of L1 data cache is unwanted.
Cache_invL1pAll() // module-wide
index URL

Invalidate all of L1 program cache

C synopsis target-domain
Void Cache_invL1pAll();
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/arm9/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.arm.arm9.Cache');
module-wide constants & types
    const Cache.sizeL1dCacheLine// Size of L1 data cache Line = 32;
    const Cache.sizeL1pCacheLine// Size of L1 program cache Line = 32;
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
module-wide config parameters
     Cache.enableCache// Enable L1 data and program caches = Bool true;
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
const Cache.sizeL1dCacheLine
index URL

Size of L1 data cache Line

XDCscript usage meta-domain
const Cache.sizeL1dCacheLine = 32;
C SYNOPSIS
Cache_sizeL1dCacheLine
const Cache.sizeL1pCacheLine
index URL

Size of L1 program cache Line

XDCscript usage meta-domain
const Cache.sizeL1pCacheLine = 32;
C SYNOPSIS
Cache_sizeL1pCacheLine
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
config Cache.enableCache // module-wide
index URL

Enable L1 data and program caches

XDCscript usage meta-domain
Cache.enableCache = Bool true;
DETAILS
To enable a subset of the caches, set this parameter to 'false' and call Cache_enable() within main, passing it only the Cache_Type(s) to be enabled.
Data caching requires the MMU and the memory section/page descriptor cacheable attribute to be enabled.
C SYNOPSIS
Cache_enableCache
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:16 GMT


module ti.sysbios.family.arm.arm9.Mmu
index URL

Memory Management Unit Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module allows the ARM processor to map a virtual address to a different physical address and enable/disable the MMU. It does this through a translation table in memory. The translation table is 16KB and manages only the first level descriptor table. Each entry in the table defines the properties of memory areas of size 1MB. These properties include memory access permissions, cacheability, bufferability, and domain access. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/arm9/Mmu.xdc
#include <ti/sysbios/family/arm/arm9/Mmu.h>
Functions
Void | Mmu_disable// Disables the MMU();
Void | Mmu_enable// Enables the MMU();
Void | Mmu_initDescAttrs// Initializes the first level descriptor attribute structure(Mmu_FirstLevelDescAttrs *attrs);
Bool | Mmu_isEnabled// Determines if the MMU is enabled();
Void | Mmu_setFirstLevelDesc// Sets the descriptor for the virtual address(Ptr virtualAddr, Ptr phyAddr, Mmu_FirstLevelDescAttrs *attrs);
Functions common to all target modules
 | Mmu_Module_getMask// Returns the diagnostics mask for this module, Mmu_Module_hasMask// Test whether this module has a diagnostics mask, Mmu_Module_heap// The heap from which this module allocates memory, Mmu_Module_id// Get this module's unique id, Mmu_Module_setMask// Set the diagnostics mask for this module, Mmu_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Mmu_FirstLevelDesc// First Level descriptors ...
typedef struct | Mmu_FirstLevelDescAttrs// Structure for setting first level descriptor entries ...
Constants
extern const Assert_Id | Mmu_A_nullPointer// Assert raised when a pointer is null;
extern const Assert_Id | Mmu_A_unknownDescType// Assert raised when the descriptor type is not recognized;
extern const Mmu_FirstLevelDescAttrs | Mmu_defaultAttrs// default descriptor attributes structure;
extern const Bool | Mmu_enableMMU// Configuration parameter to enable MMU;
DETAILS
This module allows the ARM processor to map a virtual address to a different physical address and enable/disable the MMU. It does this through a translation table in memory. The translation table is 16KB and manages only the first level descriptor table. Each entry in the table defines the properties of memory areas of size 1MB. These properties include memory access permissions, cacheability, bufferability, and domain access.
By default, the MMU translation table contains cache-enabled entries for every memory segment from the platform. Cache-disabled entries are added the peripheral addresses used by SYS/BIOS (i.e. Timers, Interrupt controller). The translation table is placed in an output section called "ti.sysbios.family.arm.arm9.mmuTableSection". This section is placed into the platform's default dataMemory and specified to not be initialized via the "NOINIT" type. If cacheable is true and bufferable is true, L1 data cache operates as a write-back cache. If cacheable is true but bufferable is false, L1 data cache operates as a write-through cache.
This module does not manage the second level descriptor tables. A 'SECTION' mapped access requires only a first level fetch. In this case, there is no need for a second level descriptor table. A 'COARSE' or 'FINE' mapped access requires a second level descriptor table which can be supplied by the user.
Note: There are size and alignment requirements on the second level descriptor tables depending on the page size. See the ARM Architecture Reference Manual for more info.
The following is an example of how to place the MMU table and how to enable L1 data caching for the address range 0xC3000000-0xC4000000 in the *.cfg file:
    var Cache = xdc.useModule('ti.sysbios.family.arm.arm9.Cache');
    var Mmu = xdc.useModule('ti.sysbios.family.arm.arm9.Mmu');

    // Enable the cache
    Cache.enableCache = true;

    // Enable the MMU (Required for L1 data caching)
    Mmu.enableMMU = true;

    // descriptor attribute structure
    var attrs = {
        type: Mmu.FirstLevelDesc_SECTION,  // SECTION descriptor
        bufferable: true,                  // bufferable
        cacheable: true,                   // cacheable
        imp: 1,                            // implementation defined
        domain: 0,                         // domain between 0-15
        accPerm: 3,                        // read/write permission
    };

    // Set the descriptor for each entry in the address range
    for (var i=0xC3000000; i < 0xC4000000; i = i + 0x00100000) {
        // Each 'SECTION' descriptor entry spans a 1MB address range
        Mmu.setFirstLevelDescMeta(i, i, attrs);
    }

    var memmap = Program.cpu.memoryMap;
    var DDR = null;

    // Find DDR in memory map
    for (var i=0; i < memmap.length; i++) {
        if (memmap[i].name == "DDR") {
            DDR = memmap[i];
        }
    }

    // Place the MMU table in the DDR memory segment if it exists
    if (DDR != null) {
        var sectionName = "ti.sysbios.family.arm.arm9.mmuTableSection";
        Program.sectMap[sectionName] = new Program.SectionSpec();
        Program.sectMap[sectionName].type = "NOINIT";
        Program.sectMap[sectionName].loadSegment = "DDR";
    }
    else {
        print("No DDR memory segment was found");
    }
The following is an example of using a second level descriptor to specify a 4KB block of memory. The first level descriptor is specified as a COARSE page table. The second level descriptors are specified as a small page, cacheable, and bufferable for the addresses 0xFFFEE000-0xFFFF0000. This code is be placed in main() in the *.c file. The MMU should not be enabled prior to initializing the second level descriptors.
    #define MMU_LEVEL2DESC_SMALLPAGE    0x2
    #define MMU_LEVEL2DESC_BUFFERABLE   0x4
    #define MMU_LEVEL2DESC_CACHEABLE    0x8

    #pragma DATA_ALIGN(mmuL2Table, 4096);    // align to 4KB

    UInt32 mmuL2Table[256];   // each level 2 descriptor specifies a 4KB block

    Void main(Int argc, Char * argv[])
    {
        Mmu_FirstLevelDescAttrs attrs;
        Int i;

        // initialize the second level descriptors
        for (i=0; i < 256; i++) {
             mmuL2Table[i] = 0;
        }

        // change the address starting at 0xFFFEE000 to be a small page
        mmuL2Table[0xEE] = 0xFFFEE000 | // set the physical address
            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
            0xFF0;                      // set Access Permission bits to 1

        // change the address starting at 0xFFFEF000 to be a small page
        mmuL2Table[0xEF] = 0xFFFEF000 | // set the physical address
            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
            0xFF0;                      // set Access Permission bits to 1

        // change the address starting at 0xFFFF0000 to be a small page
        mmuL2Table[0xF0] = 0xFFFF0000 | // set the physical address
            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
            MMU_LEVEL2DESC_CACHEABLE |  // set cacheable bit to true
            MMU_LEVEL2DESC_BUFFERABLE | // set bufferable bit to true
            0xFF0;                      // set Access Permission bits to 1

        // first level descriptor properties
        attrs.type = Mmu_FirstLevelDesc_COARSE; // set to a coarse descriptor
        attrs.imp = 1;                          // defined to be 1 for ARM9
        attrs.domain = 0;                       // set domain to 0

        // Set the first level descriptor for the virtual address 0xFFFF0000.
        Mmu_setFirstLevelDesc((Ptr)0xFFFF0000, &mmuL2Table, &attrs);

        // enable MMU
        Mmu_enable();

        BIOS_start();
    }
enum Mmu_FirstLevelDesc
index URL

First Level descriptors

C synopsis target-domain
typedef enum Mmu_FirstLevelDesc {
    Mmu_FirstLevelDesc_FAULT,
    // Virtual address is unmapped
    Mmu_FirstLevelDesc_COARSE,
    // Coarse page table descriptor
    Mmu_FirstLevelDesc_SECTION,
    // Section descriptor
    Mmu_FirstLevelDesc_FINE
    // Fine page table descriptor
} Mmu_FirstLevelDesc;
struct Mmu_FirstLevelDescAttrs
index URL

Structure for setting first level descriptor entries

C synopsis target-domain
typedef struct Mmu_FirstLevelDescAttrs {
     Mmu_FirstLevelDesc type;
    // first level descriptor type
    Bool bufferable;
    // is memory section bufferable
    Bool cacheable;
    // is memory section cacheable
    UInt8 imp;
    // implementation defined
    UInt8 domain;
    // domain access control value 0-15
    UInt8 accPerm;
    // access permission bits value 0-3
} Mmu_FirstLevelDescAttrs;
DETAILS
See the 'Translation Tables' section of the ARM Architecture Reference Manual for details
config Mmu_A_nullPointer // module-wide
index URL

Assert raised when a pointer is null

C synopsis target-domain
extern const Assert_Id Mmu_A_nullPointer;
config Mmu_A_unknownDescType // module-wide
index URL

Assert raised when the descriptor type is not recognized

C synopsis target-domain
extern const Assert_Id Mmu_A_unknownDescType;
config Mmu_defaultAttrs // module-wide
index URL

default descriptor attributes structure

C synopsis target-domain
extern const Mmu_FirstLevelDescAttrs Mmu_defaultAttrs;
config Mmu_enableMMU // module-wide
index URL

Configuration parameter to enable MMU

C synopsis target-domain
extern const Bool Mmu_enableMMU;
Mmu_disable() // module-wide
index URL

Disables the MMU

C synopsis target-domain
Void Mmu_disable();
DETAILS
If the MMU is already disabled, then simply return. Otherwise this function does the following: If the L1 data cache is enabled, write back invalidate all of L1 data cache. If the L1 program cache is enabled, invalidate all of L1 program cache. This function does not change the cache L1 data/program settings.
Mmu_enable() // module-wide
index URL

Enables the MMU

C synopsis target-domain
Void Mmu_enable();
DETAILS
If the MMU is already enabled, then simply return. Otherwise this function does the following: If the L1 program cache is enabled, invalidate all of L1 program cache. This function does not change the L1 data/program cache settings.
Mmu_initDescAttrs() // module-wide
index URL

Initializes the first level descriptor attribute structure

C synopsis target-domain
Void Mmu_initDescAttrs(Mmu_FirstLevelDescAttrs *attrs);
ARGUMENTS
attrs — Pointer to first level descriptor attribute struct
Mmu_isEnabled() // module-wide
index URL

Determines if the MMU is enabled

C synopsis target-domain
Bool Mmu_isEnabled();
Mmu_setFirstLevelDesc() // module-wide
index URL

Sets the descriptor for the virtual address

C synopsis target-domain
Void Mmu_setFirstLevelDesc(Ptr virtualAddr, Ptr phyAddr, Mmu_FirstLevelDescAttrs *attrs);
ARGUMENTS
virtualAddr — The modified virtual address
phyAddr — The physical address
attrs — Pointer to first level descriptor attribute struct
DETAILS
The first level table entry for the virtual address is mapped to the physical address with the attributes specified. The descriptor table is effective when the MMU is enabled.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Mmu_Module_id();
// Get this module's unique id
Bool Mmu_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Mmu_Module_heap();
// The heap from which this module allocates memory
Bool Mmu_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Mmu_Module_getMask();
// Returns the diagnostics mask for this module
Void Mmu_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/arm9/Mmu.xdc
var Mmu = xdc.useModule('ti.sysbios.family.arm.arm9.Mmu');
module-wide constants & types
    values of type Mmu.FirstLevelDesc// First Level descriptors
        const Mmu.FirstLevelDesc_FAULT// Virtual address is unmapped;
        const Mmu.FirstLevelDesc_COARSE// Coarse page table descriptor;
        const Mmu.FirstLevelDesc_SECTION// Section descriptor;
        const Mmu.FirstLevelDesc_FINE// Fine page table descriptor;
    var obj = new Mmu.FirstLevelDescAttrs// Structure for setting first level descriptor entries;
        obj.type// first level descriptor type = Mmu.FirstLevelDesc ...
        obj.bufferable// is memory section bufferable = Bool ...
        obj.cacheable// is memory section cacheable = Bool ...
        obj.imp// implementation defined = UInt8 ...
        obj.domain// domain access control value 0-15 = UInt8 ...
        obj.accPerm// access permission bits value 0-3 = UInt8 ...
module-wide config parameters
     Mmu.A_nullPointer// Assert raised when a pointer is null = Assert.Desc {
        msg: "A_nullPointer: Pointer is null"
    };
     Mmu.A_unknownDescType// Assert raised when the descriptor type is not recognized = Assert.Desc {
        msg: "A_unknownDescType: Descriptor type is not recognized"
    };
     Mmu.defaultAttrs// default descriptor attributes structure = Mmu.FirstLevelDescAttrs {
        type: Mmu.FirstLevelDesc_SECTION,
        bufferable: false,
        cacheable: false,
        imp: 1,
        domain: 0,
        accPerm: 3
    };
     Mmu.enableMMU// Configuration parameter to enable MMU = Bool true;
     Mmu.cachePlatformMemory// Flag to automatically mark platform's code/data/stack memory as cacheable in MMU descriptor table = Bool true;
     Mmu.common$// Common module configuration parameters = Types.Common$ undefined;
     Mmu.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
module-wide functions
     Mmu.setFirstLevelDescMeta// Statically sets the descriptor for the virtual address(Ptr virtualAddr, Ptr phyAddr, Mmu.FirstLevelDescAttrs attrs) returns Void
enum Mmu.FirstLevelDesc
index URL

First Level descriptors

XDCscript usage meta-domain
values of type Mmu.FirstLevelDesc
    const Mmu.FirstLevelDesc_FAULT;
    // Virtual address is unmapped
    const Mmu.FirstLevelDesc_COARSE;
    // Coarse page table descriptor
    const Mmu.FirstLevelDesc_SECTION;
    // Section descriptor
    const Mmu.FirstLevelDesc_FINE;
    // Fine page table descriptor
C SYNOPSIS
Mmu_FirstLevelDesc
struct Mmu.FirstLevelDescAttrs
index URL

Structure for setting first level descriptor entries

XDCscript usage meta-domain
var obj = new Mmu.FirstLevelDescAttrs;
    obj.type = Mmu.FirstLevelDesc ...
    // first level descriptor type
    obj.bufferable = Bool ...
    // is memory section bufferable
    obj.cacheable = Bool ...
    // is memory section cacheable
    obj.imp = UInt8 ...
    // implementation defined
    obj.domain = UInt8 ...
    // domain access control value 0-15
    obj.accPerm = UInt8 ...
    // access permission bits value 0-3
DETAILS
See the 'Translation Tables' section of the ARM Architecture Reference Manual for details
C SYNOPSIS
Mmu_FirstLevelDescAttrs
config Mmu.A_nullPointer // module-wide
index URL

Assert raised when a pointer is null

XDCscript usage meta-domain
Mmu.A_nullPointer = Assert.Desc {
    msg: "A_nullPointer: Pointer is null"
};
C SYNOPSIS
Mmu_A_nullPointer
config Mmu.A_unknownDescType // module-wide
index URL

Assert raised when the descriptor type is not recognized

XDCscript usage meta-domain
Mmu.A_unknownDescType = Assert.Desc {
    msg: "A_unknownDescType: Descriptor type is not recognized"
};
C SYNOPSIS
Mmu_A_unknownDescType
config Mmu.defaultAttrs // module-wide
index URL

default descriptor attributes structure

XDCscript usage meta-domain
Mmu.defaultAttrs = Mmu.FirstLevelDescAttrs {
    type: Mmu.FirstLevelDesc_SECTION,
    bufferable: false,
    cacheable: false,
    imp: 1,
    domain: 0,
    accPerm: 3
};
C SYNOPSIS
Mmu_defaultAttrs
config Mmu.enableMMU // module-wide
index URL

Configuration parameter to enable MMU

XDCscript usage meta-domain
Mmu.enableMMU = Bool true;
C SYNOPSIS
Mmu_enableMMU
metaonly config Mmu.cachePlatformMemory // module-wide
index URL

Flag to automatically mark platform's code/data/stack memory as cacheable in MMU descriptor table

XDCscript usage meta-domain
Mmu.cachePlatformMemory = Bool true;
DETAILS
By default, all memory regions defined in the platform an application is built with are marked as cacheable.
If manual configuration of memory regions is required, set this config parameter to 'false'.
SEE
xdc.bld.Program.platform
metaonly config Mmu.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Mmu.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Mmu.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
Mmu.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly Mmu.setFirstLevelDescMeta() // module-wide
index URL

Statically sets the descriptor for the virtual address

XDCscript usage meta-domain
Mmu.setFirstLevelDescMeta(Ptr virtualAddr, Ptr phyAddr, Mmu.FirstLevelDescAttrs attrs) returns Void
ARGUMENTS
virtualAddr — The modified virtual address
phyAddr — The physical address
attrs — Pointer to first level descriptor attribute struct
DETAILS
The first level table entry for the virtual address is mapped to the physical address with the attributes specified. The descriptor table is effective when the MMU is enabled.
generated on Fri, 17 Jun 2011 00:23:16 GMT


package ti.sysbios.family.arm.da830
index URL

Contains specifications for the.da830 device-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/da830/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.da830 [2, 0, 0, 0] {
    module Hwi;
    // Hardware Interrupt Support Module
    module TimestampProvider;
    // Provides.da830 specific timestamp APIs to xdc.runtime.Timestamp
}
generated on Fri, 17 Jun 2011 00:23:23 GMT


module ti.sysbios.family.arm.da830.Hwi
index URL

Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/da830/Hwi.xdc
#include <ti/sysbios/family/arm/da830/Hwi.h>
Functions
Void | Hwi_beginFIQ// Function to be invoked at the beginning of a non-dispatched FIQ handler. Services cpIntc();
Void | Hwi_beginIRQ// Function to be invoked at the beginning of a non-dispatched IRQ handler. Services cpIntc();
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
UInt | Hwi_disableFIQ// Disable FIQ interrupts();
UInt | Hwi_disableIRQ// Disable IRQ interrupts();
UInt | Hwi_enableFIQ// Enable FIQ interrupts();
UInt | Hwi_enableIRQ// Enable IRQ interrupts();
Void | Hwi_endFIQ// Function to be invoked at the end of a non-dispatched FIQ handler. Services cpIntc();
Void | Hwi_endIRQ// Function to be invoked at the end of a non-dispatched IRQ handler. Services cpIntc();
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with intNum(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Void | Hwi_restoreFIQ// Restore FIQ interrupts(UInt key);
Void | Hwi_restoreIRQ// Restore IRQ interrupts(UInt key);
Void | Hwi_setPriority// Set an interrupt's relative priority(UInt intNum, UInt priority);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// The DA830 ARM Interrupt Controller has 101 defined interrupts (Int)101
Typedefs
typedef struct | Hwi_CPINTC// Common Platform Interrupt Controller ...
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Assert_Id | Hwi_A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided;
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Ptr | Hwi_fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Ptr | Hwi_irqStack// IRQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi.
Additional ARM device-specific APIs are also provided.
IRQ Interrupts are nestable and can invoke SYS/BIOS functions. FIQ Interrupts are non-nestable and cannot invoke SYS/BIOS functions.
The IRQ dispatcher re-enables IRQ interrupts prior to invoking the ISR function associated with an interrupt but uses the CP INTC's Host Interrupt Nesting Level Register (HINLR) to suppress lower priority interrupts while the interrupt is being serviced.
The default FIQ handler does not re-enable FIQ interrupts nor use the HINLR. It simply calls the registered FIQ ISR and returns.
To statically configure a non-dispatched interrupt: To dynamically configure a non-dispatched interrupt:

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableFIQ | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
disableIRQ | Y | Y | Y | Y | Y
enable | Y | Y | Y | N | N
enableFIQ | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
enableIRQ | Y | Y | Y | N | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreFIQ | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
restoreIRQ | Y | Y | Y | Y | Y
setPriority | Y | Y | Y | Y | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

The DA830 ARM Interrupt Controller has 101 defined interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)101
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_CPINTC
index URL

Common Platform Interrupt Controller

C synopsis target-domain
typedef struct Hwi_CPINTC {
    UInt32 REV;
    // 0x00 Revision Register
    UInt32 CR;
    // 0x04 Control Register
    UInt32 RES_08;
    // 0x08 reserved
    UInt32 HCR;
    // 0x0C Host Control Register
    UInt32 GER;
    // 0x10 Global Enable Register
    UInt32 RES_14;
    // 0x14 reserved
    UInt32 RES_18;
    // 0x18 reserved
    UInt32 GNLR;
    // 0x1C Global Nesting Level Register
    UInt32 SISR;
    // 0x20 Status Index Set Register
    UInt32 SICR;
    // 0x24 Status Index Clear Register
    UInt32 EISR;
    // 0x28 Enable Index Set Register
    UInt32 EICR;
    // 0x2C Enable Index Clear Register
    UInt32 GWER;
    // 0x30 Global Wakeup Enable Register
    UInt32 HIEISR;
    // 0x34 Host Int Enable Index Set Register
    UInt32 HIDISR;
    // 0x38 Host Int Disable Index Set Register
    UInt32 RES_3C;
    // 0x3C reserved
    UInt32 PPR;
    // 0x40 Pacer Prescale Register
    UInt32 RES_44;
    // 0x44 reserved
    UInt32 RES_48;
    // 0x48 reserved
    UInt32 RES_4C;
    // 0x4C reserved
    Ptr *VBR;
    // 0x50 Vector Base Register
    UInt32 VSR;
    // 0x54 Vector Size Register
    Ptr VNR;
    // 0x58 Vector Null Register
    UInt32 RES_5C[9];
    // 0x5C-0x7C reserved
    Int32 GPIR;
    // 0x80 Global Prioritized Index Register
    Ptr *GPVR;
    // 0x84 Global Prioritized Vector Register
    UInt32 RES_88;
    // 0x88 reserved
    UInt32 RES_8C;
    // 0x8C reserved
    UInt32 GSIER;
    // 0x90 Global Secure Interrupt Enable Register
    UInt32 SPIR;
    // 0x94 Secure Prioritized Index Register
    UInt32 RES_98[26];
    // 0x98-0xFC reserved
    UInt32 PPMR[64];
    // 0x100-0x1FC Pacer Parameter/Map Registers
    UInt32 SRSR[32];
    // 0x200-0x27C Status Raw/Set Registers
    UInt32 SECR[32];
    // 0x280-0x2FC Status Enabled/Clear Registers
    UInt32 ESR[32];
    // 0x300-0x37C Enable Set Registers
    UInt32 ECR[32];
    // 0x380-0x3FC Enable Clear Registers
    UInt8 CMR[1024];
    // 0x400-0x7FC Channel Map Registers
    UInt8 HIMR[256];
    // 0x800-0x8FC Host Interrupt Map Registers
    UInt32 HIPIR[256];
    // 0x900-0xCFC Host Interrupt Pri Index Registers
    UInt32 PR[32];
    // 0xD00-0xD7C Polarity Registers
    UInt32 TR[32];
    // 0xD80-0xDFC Type Registers
    UInt32 WER[64];
    // 0xE00-0xEFC Wakeup Enable Registers
    UInt32 DSR[64];
    // 0xF00-0xFFC Debug Select Registers
    UInt32 SER[32];
    // 0x1000-0x107C Secure Enable Registers
    UInt32 SDR[32];
    // 0x1080-0x10FC Secure Disable Registers
    UInt32 HINLR[256];
    // 0x1100-0x14FC Host Interrupt Nesting Level Registers
    UInt32 HIER[8];
    // 0x1500-0x151F Host Interrupt Enable Registers
    UInt32 RES_1520[56];
    // 0x1520-0x15fC Reserved
    Ptr *HIPVR[256];
    // 0x1600-0x19fC Host Interrupt Prioritized Vector
} Hwi_CPINTC;
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

C synopsis target-domain
extern const Assert_Id Hwi_A_unsupportedMaskingOption;
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_fiqStack;
config Hwi_irqStack // module-wide
index URL

IRQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_irqStack;
Hwi_beginFIQ() // module-wide
index URL

Function to be invoked at the beginning of a non-dispatched FIQ handler. Services cpIntc

C synopsis target-domain
Void Hwi_beginFIQ();
Hwi_beginIRQ() // module-wide
index URL

Function to be invoked at the beginning of a non-dispatched IRQ handler. Services cpIntc

C synopsis target-domain
Void Hwi_beginIRQ();
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableFIQ() // module-wide
index URL

Disable FIQ interrupts

C synopsis target-domain
UInt Hwi_disableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_disableIRQ() // module-wide
index URL

Disable IRQ interrupts

C synopsis target-domain
UInt Hwi_disableIRQ();
RETURNS
previous IRQ interrupt enable/disable state
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableFIQ() // module-wide
index URL

Enable FIQ interrupts

C synopsis target-domain
UInt Hwi_enableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_enableIRQ() // module-wide
index URL

Enable IRQ interrupts

C synopsis target-domain
UInt Hwi_enableIRQ();
ARGUMENTS
key — enable/disable state to restore
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_endFIQ() // module-wide
index URL

Function to be invoked at the end of a non-dispatched FIQ handler. Services cpIntc

C synopsis target-domain
Void Hwi_endFIQ();
Hwi_endIRQ() // module-wide
index URL

Function to be invoked at the end of a non-dispatched IRQ handler. Services cpIntc

C synopsis target-domain
Void Hwi_endIRQ();
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreFIQ() // module-wide
index URL

Restore FIQ interrupts

C synopsis target-domain
Void Hwi_restoreFIQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreIRQ() // module-wide
index URL

Restore IRQ interrupts

C synopsis target-domain
Void Hwi_restoreIRQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_setPriority() // module-wide
index URL

Set an interrupt's relative priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
ARGUMENTS
intNum — ID of interrupt
priority — priority
DETAILS
Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt.
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt. The default is 31 which is the lowest priority IRQ interrupt
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt. The default is 31 which is the lowest priority IRQ interrupt

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/da830/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.da830.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// The DA830 ARM Interrupt Controller has 101 defined interrupts = 101;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.CPINTC// Common Platform Interrupt Controller;
        obj.REV// 0x00 Revision Register = UInt32 ...
        obj.CR// 0x04 Control Register = UInt32 ...
        obj.RES_08// 0x08 reserved = UInt32 ...
        obj.HCR// 0x0C Host Control Register = UInt32 ...
        obj.GER// 0x10 Global Enable Register = UInt32 ...
        obj.RES_14// 0x14 reserved = UInt32 ...
        obj.RES_18// 0x18 reserved = UInt32 ...
        obj.GNLR// 0x1C Global Nesting Level Register = UInt32 ...
        obj.SISR// 0x20 Status Index Set Register = UInt32 ...
        obj.SICR// 0x24 Status Index Clear Register = UInt32 ...
        obj.EISR// 0x28 Enable Index Set Register = UInt32 ...
        obj.EICR// 0x2C Enable Index Clear Register = UInt32 ...
        obj.GWER// 0x30 Global Wakeup Enable Register = UInt32 ...
        obj.HIEISR// 0x34 Host Int Enable Index Set Register = UInt32 ...
        obj.HIDISR// 0x38 Host Int Disable Index Set Register = UInt32 ...
        obj.RES_3C// 0x3C reserved = UInt32 ...
        obj.PPR// 0x40 Pacer Prescale Register = UInt32 ...
        obj.RES_44// 0x44 reserved = UInt32 ...
        obj.RES_48// 0x48 reserved = UInt32 ...
        obj.RES_4C// 0x4C reserved = UInt32 ...
        obj.VBR// 0x50 Vector Base Register = Ptr* ...
        obj.VSR// 0x54 Vector Size Register = UInt32 ...
        obj.VNR// 0x58 Vector Null Register = Ptr ...
        obj.RES_5C// 0x5C-0x7C reserved = UInt32[9] ...
        obj.GPIR// 0x80 Global Prioritized Index Register = Int32 ...
        obj.GPVR// 0x84 Global Prioritized Vector Register = Ptr* ...
        obj.RES_88// 0x88 reserved = UInt32 ...
        obj.RES_8C// 0x8C reserved = UInt32 ...
        obj.GSIER// 0x90 Global Secure Interrupt Enable Register = UInt32 ...
        obj.SPIR// 0x94 Secure Prioritized Index Register = UInt32 ...
        obj.RES_98// 0x98-0xFC reserved = UInt32[26] ...
        obj.PPMR// 0x100-0x1FC Pacer Parameter/Map Registers = UInt32[64] ...
        obj.SRSR// 0x200-0x27C Status Raw/Set Registers = UInt32[32] ...
        obj.SECR// 0x280-0x2FC Status Enabled/Clear Registers = UInt32[32] ...
        obj.ESR// 0x300-0x37C Enable Set Registers = UInt32[32] ...
        obj.ECR// 0x380-0x3FC Enable Clear Registers = UInt32[32] ...
        obj.CMR// 0x400-0x7FC Channel Map Registers = UInt8[1024] ...
        obj.HIMR// 0x800-0x8FC Host Interrupt Map Registers = UInt8[256] ...
        obj.HIPIR// 0x900-0xCFC Host Interrupt Pri Index Registers = UInt32[256] ...
        obj.PR// 0xD00-0xD7C Polarity Registers = UInt32[32] ...
        obj.TR// 0xD80-0xDFC Type Registers = UInt32[32] ...
        obj.WER// 0xE00-0xEFC Wakeup Enable Registers = UInt32[64] ...
        obj.DSR// 0xF00-0xFFC Debug Select Registers = UInt32[64] ...
        obj.SER// 0x1000-0x107C Secure Enable Registers = UInt32[32] ...
        obj.SDR// 0x1080-0x10FC Secure Disable Registers = UInt32[32] ...
        obj.HINLR// 0x1100-0x14FC Host Interrupt Nesting Level Registers = UInt32[256] ...
        obj.HIER// 0x1500-0x151F Host Interrupt Enable Registers = UInt32[8] ...
        obj.RES_1520// 0x1520-0x15fC Reserved = UInt32[56] ...
        obj.HIPVR// 0x1600-0x19fC Host Interrupt Prioritized Vector = Ptr*[256] ...
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.fxn// "Hwi_plug'd" ISR function = Void(*)(Void) ...
        obj.priority = UInt ...
        obj.enableInt = Bool ...
module-wide config parameters
     Hwi.A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided = Assert.Desc {
        msg: "A_unsupportedMaskingOption: unsupported maskSetting."
    };
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.irqStack// IRQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.dataAbortFunc// Data abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.fiqFunc// FIQ interrupt handler. Default is internal FIQ dispatcher = Void(*)(Void) undefined;
     Hwi.fiqStackSection// Memory section used for FIQ stack Default is null = String null;
     Hwi.fiqStackSize// FIQ stack size in bytes. Default is 1024 bytes = SizeT 1024;
     Hwi.irqFunc// IRQ interrupt handler. Default is internal IRQ dispatcher = Void(*)(Void) undefined;
     Hwi.irqStackSection// Memory section used for IRQ stack Default is null = String null;
     Hwi.irqStackSize// IRQ stack size in bytes. Default is 256 bytes. This is enough room for 32 nested IRQ interrupts = SizeT 256;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.prefetchAbortFunc// Prefetch abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.reservedFunc// Reserved exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
     Hwi.swiFunc// SWI Handler. Default is internal SWI handler = Void(*)(Void) undefined;
     Hwi.undefinedInstFunc// Undefined instruction exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.vectorTableAddress// Location of the Interrupt Vector Table = Ptr 0xffff0040;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt. The default is 31 which is the lowest priority IRQ interrupt = Int 31;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

The DA830 ARM Interrupt Controller has 101 defined interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 101;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.CPINTC
index URL

Common Platform Interrupt Controller

XDCscript usage meta-domain
var obj = new Hwi.CPINTC;
    obj.REV = UInt32 ...
    // 0x00 Revision Register
    obj.CR = UInt32 ...
    // 0x04 Control Register
    obj.RES_08 = UInt32 ...
    // 0x08 reserved
    obj.HCR = UInt32 ...
    // 0x0C Host Control Register
    obj.GER = UInt32 ...
    // 0x10 Global Enable Register
    obj.RES_14 = UInt32 ...
    // 0x14 reserved
    obj.RES_18 = UInt32 ...
    // 0x18 reserved
    obj.GNLR = UInt32 ...
    // 0x1C Global Nesting Level Register
    obj.SISR = UInt32 ...
    // 0x20 Status Index Set Register
    obj.SICR = UInt32 ...
    // 0x24 Status Index Clear Register
    obj.EISR = UInt32 ...
    // 0x28 Enable Index Set Register
    obj.EICR = UInt32 ...
    // 0x2C Enable Index Clear Register
    obj.GWER = UInt32 ...
    // 0x30 Global Wakeup Enable Register
    obj.HIEISR = UInt32 ...
    // 0x34 Host Int Enable Index Set Register
    obj.HIDISR = UInt32 ...
    // 0x38 Host Int Disable Index Set Register
    obj.RES_3C = UInt32 ...
    // 0x3C reserved
    obj.PPR = UInt32 ...
    // 0x40 Pacer Prescale Register
    obj.RES_44 = UInt32 ...
    // 0x44 reserved
    obj.RES_48 = UInt32 ...
    // 0x48 reserved
    obj.RES_4C = UInt32 ...
    // 0x4C reserved
    obj.VBR = Ptr* ...
    // 0x50 Vector Base Register
    obj.VSR = UInt32 ...
    // 0x54 Vector Size Register
    obj.VNR = Ptr ...
    // 0x58 Vector Null Register
    obj.RES_5C = UInt32[9] ...
    // 0x5C-0x7C reserved
    obj.GPIR = Int32 ...
    // 0x80 Global Prioritized Index Register
    obj.GPVR = Ptr* ...
    // 0x84 Global Prioritized Vector Register
    obj.RES_88 = UInt32 ...
    // 0x88 reserved
    obj.RES_8C = UInt32 ...
    // 0x8C reserved
    obj.GSIER = UInt32 ...
    // 0x90 Global Secure Interrupt Enable Register
    obj.SPIR = UInt32 ...
    // 0x94 Secure Prioritized Index Register
    obj.RES_98 = UInt32[26] ...
    // 0x98-0xFC reserved
    obj.PPMR = UInt32[64] ...
    // 0x100-0x1FC Pacer Parameter/Map Registers
    obj.SRSR = UInt32[32] ...
    // 0x200-0x27C Status Raw/Set Registers
    obj.SECR = UInt32[32] ...
    // 0x280-0x2FC Status Enabled/Clear Registers
    obj.ESR = UInt32[32] ...
    // 0x300-0x37C Enable Set Registers
    obj.ECR = UInt32[32] ...
    // 0x380-0x3FC Enable Clear Registers
    obj.CMR = UInt8[1024] ...
    // 0x400-0x7FC Channel Map Registers
    obj.HIMR = UInt8[256] ...
    // 0x800-0x8FC Host Interrupt Map Registers
    obj.HIPIR = UInt32[256] ...
    // 0x900-0xCFC Host Interrupt Pri Index Registers
    obj.PR = UInt32[32] ...
    // 0xD00-0xD7C Polarity Registers
    obj.TR = UInt32[32] ...
    // 0xD80-0xDFC Type Registers
    obj.WER = UInt32[64] ...
    // 0xE00-0xEFC Wakeup Enable Registers
    obj.DSR = UInt32[64] ...
    // 0xF00-0xFFC Debug Select Registers
    obj.SER = UInt32[32] ...
    // 0x1000-0x107C Secure Enable Registers
    obj.SDR = UInt32[32] ...
    // 0x1080-0x10FC Secure Disable Registers
    obj.HINLR = UInt32[256] ...
    // 0x1100-0x14FC Host Interrupt Nesting Level Registers
    obj.HIER = UInt32[8] ...
    // 0x1500-0x151F Host Interrupt Enable Registers
    obj.RES_1520 = UInt32[56] ...
    // 0x1520-0x15fC Reserved
    obj.HIPVR = Ptr*[256] ...
    // 0x1600-0x19fC Host Interrupt Prioritized Vector
C SYNOPSIS
Hwi_CPINTC
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    // "Hwi_plug'd" ISR function
    obj.priority = UInt ...
    obj.enableInt = Bool ...
config Hwi.A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

XDCscript usage meta-domain
Hwi.A_unsupportedMaskingOption = Assert.Desc {
    msg: "A_unsupportedMaskingOption: unsupported maskSetting."
};
C SYNOPSIS
Hwi_A_unsupportedMaskingOption
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.fiqStack = Ptr null;
C SYNOPSIS
Hwi_fiqStack
config Hwi.irqStack // module-wide
index URL

IRQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.irqStack = Ptr null;
C SYNOPSIS
Hwi_irqStack
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.dataAbortFunc // module-wide
index URL

Data abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.dataAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqFunc // module-wide
index URL

FIQ interrupt handler. Default is internal FIQ dispatcher

XDCscript usage meta-domain
Hwi.fiqFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqStackSection // module-wide
index URL

Memory section used for FIQ stack Default is null

XDCscript usage meta-domain
Hwi.fiqStackSection = String null;
metaonly config Hwi.fiqStackSize // module-wide
index URL

FIQ stack size in bytes. Default is 1024 bytes

XDCscript usage meta-domain
Hwi.fiqStackSize = SizeT 1024;
metaonly config Hwi.irqFunc // module-wide
index URL

IRQ interrupt handler. Default is internal IRQ dispatcher

XDCscript usage meta-domain
Hwi.irqFunc = Void(*)(Void) undefined;
metaonly config Hwi.irqStackSection // module-wide
index URL

Memory section used for IRQ stack Default is null

XDCscript usage meta-domain
Hwi.irqStackSection = String null;
metaonly config Hwi.irqStackSize // module-wide
index URL

IRQ stack size in bytes. Default is 256 bytes. This is enough room for 32 nested IRQ interrupts

XDCscript usage meta-domain
Hwi.irqStackSize = SizeT 256;
DETAILS
An IRQ interrupt pushes 2 32bit words onto the IRQ stack.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.prefetchAbortFunc // module-wide
index URL

Prefetch abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.prefetchAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.reservedFunc // module-wide
index URL

Reserved exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.reservedFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetFunc // module-wide
index URL

Reset Handler. Default is c_int00

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
metaonly config Hwi.swiFunc // module-wide
index URL

SWI Handler. Default is internal SWI handler

XDCscript usage meta-domain
Hwi.swiFunc = Void(*)(Void) undefined;
metaonly config Hwi.undefinedInstFunc // module-wide
index URL

Undefined instruction exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.undefinedInstFunc = Void(*)(Void) undefined;
metaonly config Hwi.vectorTableAddress // module-wide
index URL

Location of the Interrupt Vector Table

XDCscript usage meta-domain
Hwi.vectorTableAddress = Ptr 0xffff0040;
DETAILS
The default placement of the Interrupt Vector Table is immediately after the ARM exception table located at 0xffff0000.
The vector table is internally assigned to the ".vectorTable" memory section.
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 31;
    // Interrupt priority. Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt. The default is 31 which is the lowest priority IRQ interrupt
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Valid priorities are 0 - 31. 0 is highest priority. Priorities 0 - 1 are routed to the ARM's FIQ interrupt. Priorities 2 - 31 are routed to the ARM's IRQ interrupt. The default is 31 which is the lowest priority IRQ interrupt

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 31;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:23 GMT


module ti.sysbios.family.arm.da830.TimestampProvider
index URL

Provides.da830 specific timestamp APIs to xdc.runtime.Timestamp

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Uses the iceCrusher Benchmark counters. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/da830/TimestampProvider.xdc
#include <ti/sysbios/family/arm/da830/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | TimestampProvider_CountType// CountType ...
typedef struct | TimestampProvider_IceCrusherRegs// ...
Constants
extern const Assert_Id | TimestampProvider_A_counterInUse// Assert when configured benchmark counter is owned by CCS;
extern const Assert_Id | TimestampProvider_A_intControlInUse// Assert if interrupt control register is owned by CCS;
extern const UInt | TimestampProvider_benchmarkCounterId// ICECrusher Benchmark Counter id. 0 or 1. Default is 1;
extern const TimestampProvider_CountType | TimestampProvider_countType// Timestamp count type. Default is CYCLES. CountType_INSTRUCTIONS only supported on benchmarkCounterId 1!!!;
DETAILS
Uses the iceCrusher Benchmark counters.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
enum TimestampProvider_CountType
index URL

CountType

C synopsis target-domain
typedef enum TimestampProvider_CountType {
    TimestampProvider_CountType_CYCLES,
    // count cycles
    TimestampProvider_CountType_INSTRUCTIONS
    // count instructions
} TimestampProvider_CountType;
VALUES
CountType_CYCLES — Timestamp is in cycles.
CountType_INSTRUCTIONS — Timestamp is in instructions.
struct TimestampProvider_IceCrusherRegs
index URL
C synopsis target-domain
typedef struct TimestampProvider_IceCrusherRegs {
    UInt32 VER;
    // 0x00 Revision
    UInt32 DBGCFG;
    // 0x04 Debug Config
    UInt32 DBGCNTL;
    // 0x08 Debug Control & Status
    UInt32 RES_0C;
    // 0x0C Reserved
    UInt32 TRIGCNTL;
    // 0x10 Trigger Control
    UInt32 RSTCNTL;
    // 0x14 Reset Control
    UInt32 THRDIDCLM;
    // 0x18 Thread ID Claim
    UInt32 THRDID;
    // 0x1c Thread ID
    UInt32 INTCNTL;
    // 0x20 Interrupt Control
    UInt32 ETMCNTL;
    // 0x24 ETM Control
    UInt32 ETMPID;
    // 0x28 ETM Process ID
    UInt32 TEST;
    // 0x2C Test
    UInt32 SWBRKCTL;
    // 0x30 Software Breakpoint Control
    UInt32 SWBRKVAL;
    // 0x34 Software Breakpoint Value
    UInt32 RES_38;
    // 0x38 Reserved
    UInt32 RES_3C;
    // 0x3C Reserved
    UInt32 BCNT0CTRL;
    // 0x40 Benchmark Counter 0 Control
    UInt32 BCNT0;
    // 0x44 Benchmark Counter 0
    UInt32 RES_48;
    // 0x48 Reserved
    UInt32 RES_4C;
    // 0x4C Reserved
    UInt32 BCNT1CTRL;
    // 0x50 Benchmark Counter 1 Control
    UInt32 BCNT1;
    // 0x54 Benchmark Counter 1
    UInt32 RES_58[10];
    // 0x58 - 0x7C Reserved
    UInt32 HWBRK0CTL;
    // 0x80 Hardware Breakpoint 0 Control
    UInt32 HWBRK0ADR;
    // 0x84 Hardware Breakpoint 0 Address
    UInt32 HWBRK0ADRMASK;
    // 0x88 Hardware Breakpoint 0 Address Mask
    UInt32 RES_8C;
    // 0x8C Reserved
    UInt32 HWBRK1CTL;
    // 0x90 Hardware Breakpoint 1 Control
    UInt32 HWBRK1ADR;
    // 0x94 Hardware Breakpoint 1 Address
    UInt32 HWBRK1ADRMASK;
    // 0x98 Hardware Breakpoint 1 Address Mask
    UInt32 RES_9C;
    // 0x9C Reserved
    UInt32 HWBRK2CTL;
    // 0xA0 Hardware Breakpoint 2 Control
    UInt32 HWBRK2ADR;
    // 0xA4 Hardware Breakpoint 2 Address
    UInt32 HWBRK2ADRMASK;
    // 0xA8 Hardware Breakpoint 2 Address Mask
    UInt32 RES_AC;
    // 0xAC Reserved
    UInt32 HWBRK3CTL;
    // 0xB0 Hardware Breakpoint 3 Control
    UInt32 HWBRK3ADR;
    // 0xB4 Hardware Breakpoint 3 Address
    UInt32 HWBRK3ADRMASK;
    // 0xB8 Hardware Breakpoint 3 Address Mask
    UInt32 RES_BC[14];
    // 0xBC - 0xF0 Reserved
    UInt32 OS_LOCKSTS;
    // 0xF4 OS Lock Status
    UInt32 OS_LOCK;
    // 0xF8 OS Lock
    UInt32 DCON;
    // 0xFC DCON Register
} TimestampProvider_IceCrusherRegs;
config TimestampProvider_A_counterInUse // module-wide
index URL

Assert when configured benchmark counter is owned by CCS

C synopsis target-domain
extern const Assert_Id TimestampProvider_A_counterInUse;
config TimestampProvider_A_intControlInUse // module-wide
index URL

Assert if interrupt control register is owned by CCS

C synopsis target-domain
extern const Assert_Id TimestampProvider_A_intControlInUse;
config TimestampProvider_benchmarkCounterId // module-wide
index URL

ICECrusher Benchmark Counter id. 0 or 1. Default is 1

C synopsis target-domain
extern const UInt TimestampProvider_benchmarkCounterId;
config TimestampProvider_countType // module-wide
index URL

Timestamp count type. Default is CYCLES. CountType_INSTRUCTIONS only supported on benchmarkCounterId 1!!!

C synopsis target-domain
extern const TimestampProvider_CountType TimestampProvider_countType;
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/da830/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.da830.TimestampProvider');
module-wide constants & types
    values of type TimestampProvider.CountType// CountType
        const TimestampProvider.CountType_CYCLES// count cycles;
        const TimestampProvider.CountType_INSTRUCTIONS// count instructions;
    var obj = new TimestampProvider.IceCrusherRegs// ;
        obj.VER// 0x00 Revision = UInt32 ...
        obj.DBGCFG// 0x04 Debug Config = UInt32 ...
        obj.DBGCNTL// 0x08 Debug Control & Status = UInt32 ...
        obj.RES_0C// 0x0C Reserved = UInt32 ...
        obj.TRIGCNTL// 0x10 Trigger Control = UInt32 ...
        obj.RSTCNTL// 0x14 Reset Control = UInt32 ...
        obj.THRDIDCLM// 0x18 Thread ID Claim = UInt32 ...
        obj.THRDID// 0x1c Thread ID = UInt32 ...
        obj.INTCNTL// 0x20 Interrupt Control = UInt32 ...
        obj.ETMCNTL// 0x24 ETM Control = UInt32 ...
        obj.ETMPID// 0x28 ETM Process ID = UInt32 ...
        obj.TEST// 0x2C Test = UInt32 ...
        obj.SWBRKCTL// 0x30 Software Breakpoint Control = UInt32 ...
        obj.SWBRKVAL// 0x34 Software Breakpoint Value = UInt32 ...
        obj.RES_38// 0x38 Reserved = UInt32 ...
        obj.RES_3C// 0x3C Reserved = UInt32 ...
        obj.BCNT0CTRL// 0x40 Benchmark Counter 0 Control = UInt32 ...
        obj.BCNT0// 0x44 Benchmark Counter 0 = UInt32 ...
        obj.RES_48// 0x48 Reserved = UInt32 ...
        obj.RES_4C// 0x4C Reserved = UInt32 ...
        obj.BCNT1CTRL// 0x50 Benchmark Counter 1 Control = UInt32 ...
        obj.BCNT1// 0x54 Benchmark Counter 1 = UInt32 ...
        obj.RES_58// 0x58 - 0x7C Reserved = UInt32[10] ...
        obj.HWBRK0CTL// 0x80 Hardware Breakpoint 0 Control = UInt32 ...
        obj.HWBRK0ADR// 0x84 Hardware Breakpoint 0 Address = UInt32 ...
        obj.HWBRK0ADRMASK// 0x88 Hardware Breakpoint 0 Address Mask = UInt32 ...
        obj.RES_8C// 0x8C Reserved = UInt32 ...
        obj.HWBRK1CTL// 0x90 Hardware Breakpoint 1 Control = UInt32 ...
        obj.HWBRK1ADR// 0x94 Hardware Breakpoint 1 Address = UInt32 ...
        obj.HWBRK1ADRMASK// 0x98 Hardware Breakpoint 1 Address Mask = UInt32 ...
        obj.RES_9C// 0x9C Reserved = UInt32 ...
        obj.HWBRK2CTL// 0xA0 Hardware Breakpoint 2 Control = UInt32 ...
        obj.HWBRK2ADR// 0xA4 Hardware Breakpoint 2 Address = UInt32 ...
        obj.HWBRK2ADRMASK// 0xA8 Hardware Breakpoint 2 Address Mask = UInt32 ...
        obj.RES_AC// 0xAC Reserved = UInt32 ...
        obj.HWBRK3CTL// 0xB0 Hardware Breakpoint 3 Control = UInt32 ...
        obj.HWBRK3ADR// 0xB4 Hardware Breakpoint 3 Address = UInt32 ...
        obj.HWBRK3ADRMASK// 0xB8 Hardware Breakpoint 3 Address Mask = UInt32 ...
        obj.RES_BC// 0xBC - 0xF0 Reserved = UInt32[14] ...
        obj.OS_LOCKSTS// 0xF4 OS Lock Status = UInt32 ...
        obj.OS_LOCK// 0xF8 OS Lock = UInt32 ...
        obj.DCON// 0xFC DCON Register = UInt32 ...
module-wide config parameters
     TimestampProvider.A_counterInUse// Assert when configured benchmark counter is owned by CCS = Assert.Desc {
        msg: "A_counterInUse: Benchmark counter already claimed."
    };
     TimestampProvider.A_intControlInUse// Assert if interrupt control register is owned by CCS = Assert.Desc {
        msg: "A_intCOntrolInUse: iceCrusher Int Control Register already claimed."
    };
     TimestampProvider.benchmarkCounterId// ICECrusher Benchmark Counter id. 0 or 1. Default is 1 = UInt 1;
     TimestampProvider.countType// Timestamp count type. Default is CYCLES. CountType_INSTRUCTIONS only supported on benchmarkCounterId 1!!! = TimestampProvider.CountType TimestampProvider.CountType_CYCLES;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
enum TimestampProvider.CountType
index URL

CountType

XDCscript usage meta-domain
values of type TimestampProvider.CountType
    const TimestampProvider.CountType_CYCLES;
    // count cycles
    const TimestampProvider.CountType_INSTRUCTIONS;
    // count instructions
VALUES
CountType_CYCLES — Timestamp is in cycles.
CountType_INSTRUCTIONS — Timestamp is in instructions.
C SYNOPSIS
TimestampProvider_CountType
struct TimestampProvider.IceCrusherRegs
index URL
XDCscript usage meta-domain
var obj = new TimestampProvider.IceCrusherRegs;
    obj.VER = UInt32 ...
    // 0x00 Revision
    obj.DBGCFG = UInt32 ...
    // 0x04 Debug Config
    obj.DBGCNTL = UInt32 ...
    // 0x08 Debug Control & Status
    obj.RES_0C = UInt32 ...
    // 0x0C Reserved
    obj.TRIGCNTL = UInt32 ...
    // 0x10 Trigger Control
    obj.RSTCNTL = UInt32 ...
    // 0x14 Reset Control
    obj.THRDIDCLM = UInt32 ...
    // 0x18 Thread ID Claim
    obj.THRDID = UInt32 ...
    // 0x1c Thread ID
    obj.INTCNTL = UInt32 ...
    // 0x20 Interrupt Control
    obj.ETMCNTL = UInt32 ...
    // 0x24 ETM Control
    obj.ETMPID = UInt32 ...
    // 0x28 ETM Process ID
    obj.TEST = UInt32 ...
    // 0x2C Test
    obj.SWBRKCTL = UInt32 ...
    // 0x30 Software Breakpoint Control
    obj.SWBRKVAL = UInt32 ...
    // 0x34 Software Breakpoint Value
    obj.RES_38 = UInt32 ...
    // 0x38 Reserved
    obj.RES_3C = UInt32 ...
    // 0x3C Reserved
    obj.BCNT0CTRL = UInt32 ...
    // 0x40 Benchmark Counter 0 Control
    obj.BCNT0 = UInt32 ...
    // 0x44 Benchmark Counter 0
    obj.RES_48 = UInt32 ...
    // 0x48 Reserved
    obj.RES_4C = UInt32 ...
    // 0x4C Reserved
    obj.BCNT1CTRL = UInt32 ...
    // 0x50 Benchmark Counter 1 Control
    obj.BCNT1 = UInt32 ...
    // 0x54 Benchmark Counter 1
    obj.RES_58 = UInt32[10] ...
    // 0x58 - 0x7C Reserved
    obj.HWBRK0CTL = UInt32 ...
    // 0x80 Hardware Breakpoint 0 Control
    obj.HWBRK0ADR = UInt32 ...
    // 0x84 Hardware Breakpoint 0 Address
    obj.HWBRK0ADRMASK = UInt32 ...
    // 0x88 Hardware Breakpoint 0 Address Mask
    obj.RES_8C = UInt32 ...
    // 0x8C Reserved
    obj.HWBRK1CTL = UInt32 ...
    // 0x90 Hardware Breakpoint 1 Control
    obj.HWBRK1ADR = UInt32 ...
    // 0x94 Hardware Breakpoint 1 Address
    obj.HWBRK1ADRMASK = UInt32 ...
    // 0x98 Hardware Breakpoint 1 Address Mask
    obj.RES_9C = UInt32 ...
    // 0x9C Reserved
    obj.HWBRK2CTL = UInt32 ...
    // 0xA0 Hardware Breakpoint 2 Control
    obj.HWBRK2ADR = UInt32 ...
    // 0xA4 Hardware Breakpoint 2 Address
    obj.HWBRK2ADRMASK = UInt32 ...
    // 0xA8 Hardware Breakpoint 2 Address Mask
    obj.RES_AC = UInt32 ...
    // 0xAC Reserved
    obj.HWBRK3CTL = UInt32 ...
    // 0xB0 Hardware Breakpoint 3 Control
    obj.HWBRK3ADR = UInt32 ...
    // 0xB4 Hardware Breakpoint 3 Address
    obj.HWBRK3ADRMASK = UInt32 ...
    // 0xB8 Hardware Breakpoint 3 Address Mask
    obj.RES_BC = UInt32[14] ...
    // 0xBC - 0xF0 Reserved
    obj.OS_LOCKSTS = UInt32 ...
    // 0xF4 OS Lock Status
    obj.OS_LOCK = UInt32 ...
    // 0xF8 OS Lock
    obj.DCON = UInt32 ...
    // 0xFC DCON Register
C SYNOPSIS
TimestampProvider_IceCrusherRegs
config TimestampProvider.A_counterInUse // module-wide
index URL

Assert when configured benchmark counter is owned by CCS

XDCscript usage meta-domain
TimestampProvider.A_counterInUse = Assert.Desc {
    msg: "A_counterInUse: Benchmark counter already claimed."
};
C SYNOPSIS
TimestampProvider_A_counterInUse
config TimestampProvider.A_intControlInUse // module-wide
index URL

Assert if interrupt control register is owned by CCS

XDCscript usage meta-domain
TimestampProvider.A_intControlInUse = Assert.Desc {
    msg: "A_intCOntrolInUse: iceCrusher Int Control Register already claimed."
};
C SYNOPSIS
TimestampProvider_A_intControlInUse
config TimestampProvider.benchmarkCounterId // module-wide
index URL

ICECrusher Benchmark Counter id. 0 or 1. Default is 1

XDCscript usage meta-domain
TimestampProvider.benchmarkCounterId = UInt 1;
C SYNOPSIS
TimestampProvider_benchmarkCounterId
config TimestampProvider.countType // module-wide
index URL

Timestamp count type. Default is CYCLES. CountType_INSTRUCTIONS only supported on benchmarkCounterId 1!!!

XDCscript usage meta-domain
TimestampProvider.countType = TimestampProvider.CountType TimestampProvider.CountType_CYCLES;
C SYNOPSIS
TimestampProvider_countType
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:23 GMT


package ti.sysbios.family.arm.dm6446
index URL

Contains specifications for the dm6446 device-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/dm6446/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.dm6446 [2, 0, 0, 0] {
    module Hwi;
    // Hardware Interrupt Support Module
}
generated on Fri, 17 Jun 2011 00:23:21 GMT


module ti.sysbios.family.arm.dm6446.Hwi
index URL

Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/dm6446/Hwi.xdc
#include <ti/sysbios/family/arm/dm6446/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits32 | Hwi_disableEINT0// Disable specific interrupts (0-31)(Bits32 mask);
Bits32 | Hwi_disableEINT1// Disable specific interrupts (32-63)(Bits32 mask);
UInt | Hwi_disableFIQ// Disable FIQ interrupts();
UInt | Hwi_disableIRQ// Disable IRQ interrupts();
Bits32 | Hwi_enableEINT0// Enable specific interrupts (0-31)(Bits32 mask);
Bits32 | Hwi_enableEINT1// Enable specific interrupts (32-63)(Bits32 mask);
UInt | Hwi_enableFIQ// Enable FIQ interrupts();
UInt | Hwi_enableIRQ// Enable IRQ interrupts();
Hwi_Object * | Hwi_getHandle// Returns pointer to Hwi instance object(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits32 | Hwi_restoreEINT0// Restore maskable interrupts to the state they were in when either disableEINT0() or enableEINT0() was called(Bits32 mask);
Bits32 | Hwi_restoreEINT1// Restore maskable interrupts to the state they were in when either disableEINT1() or enableEINT1() was called(Bits32 mask);
Void | Hwi_restoreFIQ// Restore FIQ interrupts(UInt key);
Void | Hwi_restoreIRQ// Restore IRQ interrupts(UInt key);
Void | Hwi_setPriority// Set an interrupt's relative priority(UInt intNum, UInt priority);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// The DM6446 ARM Interrupt Controller supports 64 interrupts (Int)64
Typedefs
typedef struct | Hwi_AINTC// ARM Interrupt Controller ...
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Bits32 | Hwi_eabaseSize// EABASE Size Setting. Default is 4 bytes per entry. Options are 4, 8, 16, 32 bytes per entry;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Ptr | Hwi_fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides ARM family-specific implementations of the APIs defined in IHwi.
Additional ARM device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableEINT0 | Y | Y | Y | Y | N
disableEINT1 | Y | Y | Y | Y | N
disableFIQ | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
disableIRQ | Y | Y | Y | Y | Y
enable | Y | Y | Y | N | N
enableEINT0 | Y | Y | Y | Y | N
enableEINT1 | Y | Y | Y | Y | N
enableFIQ | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
enableIRQ | Y | Y | Y | N | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreEINT0 | Y | Y | Y | Y | N
restoreEINT1 | Y | Y | Y | Y | N
restoreFIQ | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
restoreIRQ | Y | Y | Y | Y | Y
setPriority | Y | Y | Y | Y | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

The DM6446 ARM Interrupt Controller supports 64 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)64
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_AINTC
index URL

ARM Interrupt Controller

C synopsis target-domain
typedef struct Hwi_AINTC {
    UInt32 FIQ0;
    // 0x00 Interrupt Status of INT [31:0] if mapped to FIQ
    UInt32 FIQ1;
    // 0x04 Interrupt Status of INT [63:32] if mapped to FIQ
    UInt32 IRQ0;
    // 0x08 Interrupt Status of INT [31:0] if mapped to IRQ
    UInt32 IRQ1;
    // 0x0C Interrupt Status of INT [63:32] if mapped to IRQ
    UInt32 FIQENTRY;
    // 0x10 Entry Address [28:0] for valid FIQ interrupt
    UInt32 IRQENTRY;
    // 0x14 Entry Address [28:0] for valid IRQ interrupt
    UInt32 EINT0;
    // 0x18 Interrupt Enable Register 0
    UInt32 EINT1;
    // 0x1C Interrupt Enable Register 1
    UInt32 INTCTL;
    // 0x20 Interrupt Operation Control Register
    UInt32 EABASE;
    // 0x24 Interrupt Entry Base Address
    UInt32 RES[2];
    // 0x28 reserved
    UInt32 INTPR[8];
    // 0x30 Interrupt 0-7 Priority select
} Hwi_AINTC;
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_eabaseSize // module-wide
index URL

EABASE Size Setting. Default is 4 bytes per entry. Options are 4, 8, 16, 32 bytes per entry

C synopsis target-domain
extern const Bits32 Hwi_eabaseSize;
config Hwi_fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_fiqStack;
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableEINT0() // module-wide
index URL

Disable specific interrupts (0-31)

C synopsis target-domain
Bits32 Hwi_disableEINT0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous EINT0 settings bitmask
DETAILS
Disables specific interrupts by clearing the bits specified by 'mask' in the EINT0.
Hwi_disableEINT1() // module-wide
index URL

Disable specific interrupts (32-63)

C synopsis target-domain
Bits32 Hwi_disableEINT1(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous EINT1 settings bitmask
DETAILS
Disables specific interrupts by clearing the bits specified by 'mask' in the EINT1.
Hwi_disableFIQ() // module-wide
index URL

Disable FIQ interrupts

C synopsis target-domain
UInt Hwi_disableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_disableIRQ() // module-wide
index URL

Disable IRQ interrupts

C synopsis target-domain
UInt Hwi_disableIRQ();
RETURNS
previous IRQ interrupt enable/disable state
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableEINT0() // module-wide
index URL

Enable specific interrupts (0-31)

C synopsis target-domain
Bits32 Hwi_enableEINT0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous EINT0 settings bitmask
DETAILS
Enables specific interrupts by clearing the bits specified by 'mask' in the EINT0.
Hwi_enableEINT1() // module-wide
index URL

Enable specific interrupts (32-63)

C synopsis target-domain
Bits32 Hwi_enableEINT1(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous EINT0 settings bitmask
DETAILS
Enables specific interrupts by clearing the bits specified by 'mask' in the EINT0.
Hwi_enableFIQ() // module-wide
index URL

Enable FIQ interrupts

C synopsis target-domain
UInt Hwi_enableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_enableIRQ() // module-wide
index URL

Enable IRQ interrupts

C synopsis target-domain
UInt Hwi_enableIRQ();
ARGUMENTS
key — enable/disable state to restore
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_getHandle() // module-wide
index URL

Returns pointer to Hwi instance object

C synopsis target-domain
Hwi_Object *Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreEINT0() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableEINT0() or enableEINT0() was called

C synopsis target-domain
Bits32 Hwi_restoreEINT0(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous EINT0 settings bitmask
DETAILS
Simply writes mask to the EINT0 register.
Hwi_restoreEINT1() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableEINT1() or enableEINT1() was called

C synopsis target-domain
Bits32 Hwi_restoreEINT1(Bits32 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous EINT1 settings bitmask
DETAILS
Simply writes mask to the EINT1 register.
Hwi_restoreFIQ() // module-wide
index URL

Restore FIQ interrupts

C synopsis target-domain
Void Hwi_restoreFIQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreIRQ() // module-wide
index URL

Restore IRQ interrupts

C synopsis target-domain
Void Hwi_restoreIRQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_setPriority() // module-wide
index URL

Set an interrupt's relative priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
ARGUMENTS
intNum — ID of interrupt
priority — priority
DETAILS
Priority 0-1 define the interrupt as an FIQ interrupt Priority 2-7 define the interrupt as an IRQ interrupt
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits32 disableMask0;
    // disableMask0. default is derived from MaskingOption_SELF maskSetting
    Bits32 disableMask1;
    // disableMask1. default is derived from MaskingOption_SELF maskSetting
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority (0-7). Default is 7 which is the lowest priority IRQ interrupt
    Bits32 restoreMask0;
    // restoreMask0. default is derived from MaskingOption_SELF maskSetting
    Bits32 restoreMask1;
    // restoreMask1. default is derived from MaskingOption_SELF maskSetting
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask0 // instance
index URL

disableMask0. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 disableMask0;
config Hwi_disableMask1 // instance
index URL

disableMask1. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 disableMask1;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority (0-7). Default is 7 which is the lowest priority IRQ interrupt

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask0 // instance
index URL

restoreMask0. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 restoreMask0;
config Hwi_restoreMask1 // instance
index URL

restoreMask1. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 restoreMask1;
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/dm6446/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.dm6446.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// The DM6446 ARM Interrupt Controller supports 64 interrupts = 64;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.AINTC// ARM Interrupt Controller;
        obj.FIQ0// 0x00 Interrupt Status of INT [31:0] if mapped to FIQ = UInt32 ...
        obj.FIQ1// 0x04 Interrupt Status of INT [63:32] if mapped to FIQ = UInt32 ...
        obj.IRQ0// 0x08 Interrupt Status of INT [31:0] if mapped to IRQ = UInt32 ...
        obj.IRQ1// 0x0C Interrupt Status of INT [63:32] if mapped to IRQ = UInt32 ...
        obj.FIQENTRY// 0x10 Entry Address [28:0] for valid FIQ interrupt = UInt32 ...
        obj.IRQENTRY// 0x14 Entry Address [28:0] for valid IRQ interrupt = UInt32 ...
        obj.EINT0// 0x18 Interrupt Enable Register 0 = UInt32 ...
        obj.EINT1// 0x1C Interrupt Enable Register 1 = UInt32 ...
        obj.INTCTL// 0x20 Interrupt Operation Control Register = UInt32 ...
        obj.EABASE// 0x24 Interrupt Entry Base Address = UInt32 ...
        obj.RES// 0x28 reserved = UInt32[2] ...
        obj.INTPR// 0x30 Interrupt 0-7 Priority select = UInt32[8] ...
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.eabaseSize// EABASE Size Setting. Default is 4 bytes per entry. Options are 4, 8, 16, 32 bytes per entry = Bits32 4;
     Hwi.fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.dataAbortFunc// Data abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.fiqFunc// FIQ interrupt handler. Default is internal FIQ dispatcher = Void(*)(Void) undefined;
     Hwi.fiqStackSection// Memory section used for FIQ stack Default is null = String null;
     Hwi.fiqStackSize// FIQ stack size in MAUs. Default is 1024 bytes = SizeT 1024;
     Hwi.irqFunc// IRQ interrupt handler. Default is internal IRQ dispatcher = Void(*)(Void) undefined;
     Hwi.prefetchAbortFunc// Prefetch abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.reservedFunc// Reserved exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
     Hwi.swiFunc// SWI Handler. Default is internal SWI handler = Void(*)(Void) undefined;
     Hwi.undefinedInstFunc// Undefined instruction exception handler. Default is self loop = Void(*)(Void) undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask0// disableMask0. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.disableMask1// disableMask1. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority (0-7). Default is 7 which is the lowest priority IRQ interrupt = Int 7;
        params.restoreMask0// restoreMask0. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.restoreMask1// restoreMask1. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

The DM6446 ARM Interrupt Controller supports 64 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 64;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.AINTC
index URL

ARM Interrupt Controller

XDCscript usage meta-domain
var obj = new Hwi.AINTC;
    obj.FIQ0 = UInt32 ...
    // 0x00 Interrupt Status of INT [31:0] if mapped to FIQ
    obj.FIQ1 = UInt32 ...
    // 0x04 Interrupt Status of INT [63:32] if mapped to FIQ
    obj.IRQ0 = UInt32 ...
    // 0x08 Interrupt Status of INT [31:0] if mapped to IRQ
    obj.IRQ1 = UInt32 ...
    // 0x0C Interrupt Status of INT [63:32] if mapped to IRQ
    obj.FIQENTRY = UInt32 ...
    // 0x10 Entry Address [28:0] for valid FIQ interrupt
    obj.IRQENTRY = UInt32 ...
    // 0x14 Entry Address [28:0] for valid IRQ interrupt
    obj.EINT0 = UInt32 ...
    // 0x18 Interrupt Enable Register 0
    obj.EINT1 = UInt32 ...
    // 0x1C Interrupt Enable Register 1
    obj.INTCTL = UInt32 ...
    // 0x20 Interrupt Operation Control Register
    obj.EABASE = UInt32 ...
    // 0x24 Interrupt Entry Base Address
    obj.RES = UInt32[2] ...
    // 0x28 reserved
    obj.INTPR = UInt32[8] ...
    // 0x30 Interrupt 0-7 Priority select
C SYNOPSIS
Hwi_AINTC
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.eabaseSize // module-wide
index URL

EABASE Size Setting. Default is 4 bytes per entry. Options are 4, 8, 16, 32 bytes per entry

XDCscript usage meta-domain
Hwi.eabaseSize = Bits32 4;
C SYNOPSIS
Hwi_eabaseSize
config Hwi.fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.fiqStack = Ptr null;
C SYNOPSIS
Hwi_fiqStack
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.dataAbortFunc // module-wide
index URL

Data abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.dataAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqFunc // module-wide
index URL

FIQ interrupt handler. Default is internal FIQ dispatcher

XDCscript usage meta-domain
Hwi.fiqFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqStackSection // module-wide
index URL

Memory section used for FIQ stack Default is null

XDCscript usage meta-domain
Hwi.fiqStackSection = String null;
metaonly config Hwi.fiqStackSize // module-wide
index URL

FIQ stack size in MAUs. Default is 1024 bytes

XDCscript usage meta-domain
Hwi.fiqStackSize = SizeT 1024;
metaonly config Hwi.irqFunc // module-wide
index URL

IRQ interrupt handler. Default is internal IRQ dispatcher

XDCscript usage meta-domain
Hwi.irqFunc = Void(*)(Void) undefined;
metaonly config Hwi.prefetchAbortFunc // module-wide
index URL

Prefetch abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.prefetchAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.reservedFunc // module-wide
index URL

Reserved exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.reservedFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetFunc // module-wide
index URL

Reset Handler. Default is c_int00

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
metaonly config Hwi.swiFunc // module-wide
index URL

SWI Handler. Default is internal SWI handler

XDCscript usage meta-domain
Hwi.swiFunc = Void(*)(Void) undefined;
metaonly config Hwi.undefinedInstFunc // module-wide
index URL

Undefined instruction exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.undefinedInstFunc = Void(*)(Void) undefined;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask0 = Bits32 0;
    // disableMask0. default is derived from MaskingOption_SELF maskSetting
    params.disableMask1 = Bits32 0;
    // disableMask1. default is derived from MaskingOption_SELF maskSetting
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 7;
    // Interrupt priority (0-7). Default is 7 which is the lowest priority IRQ interrupt
    params.restoreMask0 = Bits32 0;
    // restoreMask0. default is derived from MaskingOption_SELF maskSetting
    params.restoreMask1 = Bits32 0;
    // restoreMask1. default is derived from MaskingOption_SELF maskSetting
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask0 // instance
index URL

disableMask0. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask0 = Bits32 0;
C SYNOPSIS
null
config Hwi.disableMask1 // instance
index URL

disableMask1. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask1 = Bits32 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority (0-7). Default is 7 which is the lowest priority IRQ interrupt

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 7;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask0 // instance
index URL

restoreMask0. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask0 = Bits32 0;
C SYNOPSIS
null
config Hwi.restoreMask1 // instance
index URL

restoreMask1. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask1 = Bits32 0;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:21 GMT


package ti.sysbios.family.arm.ducati
index URL

Contains specifications for the Ducati device-specific SYS/BIOS functions

The two M3 cores share a number of hardware and software resources. [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/arm/ducati/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.ducati [2, 0, 0, 0] {
    module CTM;
    // Counter Timer Module Device Definitions
    module Core;
    // Core Identification Module
    module GateDualCore;
    // A Gate for use by the two Ducati M3 cores to manage shared resources
    module Timer;
    // Ducati Cortex M3 Timer Peripherals Manager
    module TimestampProvider;
    // Ducati Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp
    module Wugen;
    // Wugen Module
}
DETAILS
The two M3 cores share a number of hardware and software resources.
The system software must carefully manage these resources when the dynamic loading of applications is required.
Below is a list of the shared resources that SYS/BIOS modules utilize and manage.
Shared resources:
AMMU
  • Must be configured before unicache is enabled.
  • Must have a page descriptor for EVERY memory address accessed by either core before unicache is enabled.
  • AMMU is configured statically, no runtime APIs to modify the AMMU configuration are provided.
  • Initialization is controlled by the AMMU.configureAmmu flag.
  • By default, this flag is true.
Unicache
  • Must be configured and enabled.
  • Runtime APIs use GateDualCore[0] to arbitrate shared unicache register usage.
  • Initialization is controlled by the Cache.configureCache flag.
  • By default this flag is false.
CTM 2,3,4,5 used for timestamping
  • These counters are initialized by the TimestampProvider module, which is used by the xdc.runtime.Timestamp module to provide timestamp services.
  • Must be configured and started.
  • Configured and started by whichever core comes up first and detects (by testing register contents) that the CTM hasn't been configured and started.
Reset Exception vector table (vectors 0-14)
  • The address of the Reset Exception vector table is shared by both cores.
  • Vectors 0 and 1 at addresses 0x0 are fetched each time a core is reset. At that time they must contain the SP and address of c_int00 for the core being reset.
  • Exception vectors 2-14 are used by each core until it has successfully configured its NVIC's Vector Table Offset Register (VTOR) to point to the vector table that will be used afterwards.
  • The Reset Exception vectors are required to be valid and unique to the core being reset in case an exception occurs prior to the VTOR being configured.
  • The Reset Exception vector table placement is controlled by the Hwi.resetVectorAddress config parameter.
  • By default, both cores place their Reset Exception vector table at 0x00000000.
  • It is left to the system software design to guarantee that only one core is climbing up at a time.
Runtime Exception and Interrupt vector table (vectors 0-79)
  • The address of the Runtime Exception and Interrupt vector table should be unique to each core.
  • The Runtime Exception and Interrupt vector table placement is controlled by the Hwi.vectorTableAddress config parameter.
  • Default behavior is that core 0 places its runtime vector table at 0x400 and core 1 places its runtime vector table at 0x800.
GateDualCore[0] is used by the unicache module. GateDualCore[1-n] can be used by applications to manage shared hardware/software resources
  • Initialization is controlled by the GateDualCore.initGates flag.
  • By default, core 0 initializes the gate objects.
generated on Fri, 17 Jun 2011 00:23:34 GMT


module ti.sysbios.family.arm.ducati.Core
index URL

Core Identification Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Core module is used to define which core within a dual core "Ducati" subsystem an application is being built for. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/Core.xdc
#include <ti/sysbios/family/arm/ducati/Core.h>
Functions
macro UInt | Core_getId// Reads M3 core ID (0 or 1)();
Functions common to all target modules
 | Core_Module_getMask// Returns the diagnostics mask for this module, Core_Module_hasMask// Test whether this module has a diagnostics mask, Core_Module_heap// The heap from which this module allocates memory, Core_Module_id// Get this module's unique id, Core_Module_setMask// Set the diagnostics mask for this module, Core_Module_startupDone// Test if this module has completed startup
Constants
extern const Error_Id | Core_E_mismatchedIds// Error raised if Core.id does not match the contents of PID0 (at 0xE00FFFE0);
extern const UInt | Core_id// Ducati Core ID, default is Core 0;
DETAILS
The Core module is used to define which core within a dual core "Ducati" subsystem an application is being built for.
At runtime, a comparison is made between the configured Core.id and the value of PID0 (at address 0xe00fffe0). If they do not agree, an Error is raised.
Use of this module has the side effect of configuring default interrupt vector table placements for Core 0 and Core 1 if they haven't already been specified by the Hwi.vectorTableAddress config parameter.
Core 0's default vector table placement is at 0x400.
Core 1's default vector table placement is at 0x800.
config Core_E_mismatchedIds // module-wide
index URL

Error raised if Core.id does not match the contents of PID0 (at 0xE00FFFE0)

C synopsis target-domain
extern const Error_Id Core_E_mismatchedIds;
config Core_id // module-wide
index URL

Ducati Core ID, default is Core 0

C synopsis target-domain
extern const UInt Core_id;
DETAILS
Used for making static decisions based on Core ID
Core_getId() // module-wide
index URL

Reads M3 core ID (0 or 1)

C synopsis target-domain
macro UInt Core_getId();
RETURNS
core ID
DETAILS
Used for making dynamic decisions based on Core ID
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Core_Module_id();
// Get this module's unique id
Bool Core_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Core_Module_heap();
// The heap from which this module allocates memory
Bool Core_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Core_Module_getMask();
// Returns the diagnostics mask for this module
Void Core_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/Core.xdc
var Core = xdc.useModule('ti.sysbios.family.arm.ducati.Core');
module-wide config parameters
     Core.E_mismatchedIds// Error raised if Core.id does not match the contents of PID0 (at 0xE00FFFE0) = Error.Desc {
        msg: "E_mismatchedIds: Core_Id: %d does not match hardware core Id: %d"
    };
     Core.id// Ducati Core ID, default is Core 0 = UInt 0;
     Core.common$// Common module configuration parameters = Types.Common$ undefined;
config Core.E_mismatchedIds // module-wide
index URL

Error raised if Core.id does not match the contents of PID0 (at 0xE00FFFE0)

XDCscript usage meta-domain
Core.E_mismatchedIds = Error.Desc {
    msg: "E_mismatchedIds: Core_Id: %d does not match hardware core Id: %d"
};
C SYNOPSIS
Core_E_mismatchedIds
config Core.id // module-wide
index URL

Ducati Core ID, default is Core 0

XDCscript usage meta-domain
Core.id = UInt 0;
DETAILS
Used for making static decisions based on Core ID
C SYNOPSIS
Core_id
metaonly config Core.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Core.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:34 GMT


module ti.sysbios.family.arm.ducati.CTM
index URL

Counter Timer Module Device Definitions

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
For Ducati SYS/BIOS applications, Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18 Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22 Counters 2/3 are assigned to core 0's TimestampProvider Counters 4/5 are assigned to core 1's TimestampProvider Counters 6,7 are for application use. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/CTM.xdc
#include <ti/sysbios/family/arm/ducati/CTM.h>
Functions common to all target modules
 | CTM_Module_getMask// Returns the diagnostics mask for this module, CTM_Module_hasMask// Test whether this module has a diagnostics mask, CTM_Module_heap// The heap from which this module allocates memory, CTM_Module_id// Get this module's unique id, CTM_Module_setMask// Set the diagnostics mask for this module, CTM_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | CTM_CTM// Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400 ...
DETAILS
For Ducati SYS/BIOS applications, Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18 Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22 Counters 2/3 are assigned to core 0's TimestampProvider Counters 4/5 are assigned to core 1's TimestampProvider Counters 6,7 are for application use.
Counters 2/3 and 4/5 are in chained mode and started simultaneously by core 0 so that both cores timestamps are in sync with each other AND both chained timers have independent SHADOW registers to guarantee 64bit counter reading coherency.
struct CTM_CTM
index URL

Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400

C synopsis target-domain
typedef struct CTM_CTM {
    UInt32 CTCNTL;
    // 0x0000
    UInt32 RES_04[7];
    // 0x0004 - 0x0020
    UInt32 CTSTMCNTL;
    // 0x0020
    UInt32 CTSTMMSTID;
    // 0x0024
    UInt32 CTSTMINTVL;
    // 0x0028
    UInt32 CTSTMSEL0;
    // 0x002C
    UInt32 CTSTMSEL1;
    // 0x0030
    UInt32 RES_34[3];
    // 0x0034 - 0x0040
    UInt32 TINTVLR[8];
    // 0x0040 - 0x0060
    UInt32 RES_60[7];
    // 0x0060 - 0x007C
    UInt32 CTNUMDBG;
    // 0x007C
    UInt32 CTDBGSGL[8];
    // 0x0080 - 0x00A0
    UInt32 RES_A0[20];
    // 0x00A0 - 0x00F0
    UInt32 CTGNBL[2];
    // 0x00F0 - 0x00F8
    UInt32 CTGRST[2];
    // 0x00F8 - 0x0100
    UInt32 CTCR[32];
    // 0x0100 - 0x0180
    UInt32 CTCNTR[32];
    // 0x0180 - 0x0200
} CTM_CTM;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId CTM_Module_id();
// Get this module's unique id
Bool CTM_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle CTM_Module_heap();
// The heap from which this module allocates memory
Bool CTM_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 CTM_Module_getMask();
// Returns the diagnostics mask for this module
Void CTM_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/CTM.xdc
var CTM = xdc.useModule('ti.sysbios.family.arm.ducati.CTM');
module-wide constants & types
    var obj = new CTM.CTM// Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400;
        obj.CTCNTL// 0x0000 = UInt32 ...
        obj.RES_04// 0x0004 - 0x0020 = UInt32[7] ...
        obj.CTSTMCNTL// 0x0020 = UInt32 ...
        obj.CTSTMMSTID// 0x0024 = UInt32 ...
        obj.CTSTMINTVL// 0x0028 = UInt32 ...
        obj.CTSTMSEL0// 0x002C = UInt32 ...
        obj.CTSTMSEL1// 0x0030 = UInt32 ...
        obj.RES_34// 0x0034 - 0x0040 = UInt32[3] ...
        obj.TINTVLR// 0x0040 - 0x0060 = UInt32[8] ...
        obj.RES_60// 0x0060 - 0x007C = UInt32[7] ...
        obj.CTNUMDBG// 0x007C = UInt32 ...
        obj.CTDBGSGL// 0x0080 - 0x00A0 = UInt32[8] ...
        obj.RES_A0// 0x00A0 - 0x00F0 = UInt32[20] ...
        obj.CTGNBL// 0x00F0 - 0x00F8 = UInt32[2] ...
        obj.CTGRST// 0x00F8 - 0x0100 = UInt32[2] ...
        obj.CTCR// 0x0100 - 0x0180 = UInt32[32] ...
        obj.CTCNTR// 0x0180 - 0x0200 = UInt32[32] ...
module-wide config parameters
     CTM.common$// Common module configuration parameters = Types.Common$ undefined;
struct CTM.CTM
index URL

Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400

XDCscript usage meta-domain
var obj = new CTM.CTM;
    obj.CTCNTL = UInt32 ...
    // 0x0000
    obj.RES_04 = UInt32[7] ...
    // 0x0004 - 0x0020
    obj.CTSTMCNTL = UInt32 ...
    // 0x0020
    obj.CTSTMMSTID = UInt32 ...
    // 0x0024
    obj.CTSTMINTVL = UInt32 ...
    // 0x0028
    obj.CTSTMSEL0 = UInt32 ...
    // 0x002C
    obj.CTSTMSEL1 = UInt32 ...
    // 0x0030
    obj.RES_34 = UInt32[3] ...
    // 0x0034 - 0x0040
    obj.TINTVLR = UInt32[8] ...
    // 0x0040 - 0x0060
    obj.RES_60 = UInt32[7] ...
    // 0x0060 - 0x007C
    obj.CTNUMDBG = UInt32 ...
    // 0x007C
    obj.CTDBGSGL = UInt32[8] ...
    // 0x0080 - 0x00A0
    obj.RES_A0 = UInt32[20] ...
    // 0x00A0 - 0x00F0
    obj.CTGNBL = UInt32[2] ...
    // 0x00F0 - 0x00F8
    obj.CTGRST = UInt32[2] ...
    // 0x00F8 - 0x0100
    obj.CTCR = UInt32[32] ...
    // 0x0100 - 0x0180
    obj.CTCNTR = UInt32[32] ...
    // 0x0180 - 0x0200
C SYNOPSIS
CTM_CTM
metaonly config CTM.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
CTM.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:33 GMT


module ti.sysbios.family.arm.ducati.GateDualCore
index URL

A Gate for use by the two Ducati M3 cores to manage shared resources

  • C synopsis
  • Individual elements
  • DETAILS
  • RESTRICTIONS
  • XDCscript usage
  • Individual elements
GateDualCore uses disabling and enabling of interrupts as well as a shared variable between the two M3 cores as the resource locking mechanism. Such a gate guarantees exclusive access to a resource shared between the cores. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/GateDualCore.xdc
#include <ti/sysbios/family/arm/ducati/GateDualCore.h>
Functions
Void | GateDualCore_construct// Initialize a new instance object inside the provided structure(GateDualCore_Struct *structP, const GateDualCore_Params *params, Error_Block *eb);
GateDualCore_Handle | GateDualCore_create// Allocate and initialize a new instance object and return its handle(const GateDualCore_Params *params, Error_Block *eb);
Void | GateDualCore_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateDualCore_Handle *handleP);
Void | GateDualCore_destruct// Finalize the instance object inside the provided structure(GateDualCore_Struct *structP);
Void | GateDualCore_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateDualCore_Params *params);
Void | GateDualCore_sync// Sync execution with the other M3 core(GateDualCore_Handle handle);
Functions common to all IGateProvider modules
Bool | GateDualCore_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateDualCore_handle// Convert this instance structure pointer into an instance handle, GateDualCore_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateDualCore_Handle_label// The label associated with this instance object, GateDualCore_Handle_name// The name of this instance object, GateDualCore_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateDualCore_Object_count// The number of statically-created instance objects, GateDualCore_Object_first// The handle of the first dynamically-created instance object, or NULL, GateDualCore_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateDualCore_Object_heap// The heap used to allocate dynamically-created instance objects, GateDualCore_Object_next// The handle of the next dynamically-created instance object, or NULL, GateDualCore_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateDualCore_Module_getMask// Returns the diagnostics mask for this module, GateDualCore_Module_hasMask// Test whether this module has a diagnostics mask, GateDualCore_Module_heap// The heap from which this module allocates memory, GateDualCore_Module_id// Get this module's unique id, GateDualCore_Module_setMask// Set the diagnostics mask for this module, GateDualCore_Module_startupDone// Test if this module has completed startup
Defines
#define | GateDualCore_Q_BLOCKING// Blocking quality (Int)1
#define | GateDualCore_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateDualCore_Object * | GateDualCore_Handle// Client reference to an instance object;
typedef struct | GateDualCore_Object// Opaque internal representation of an instance object GateDualCore_Object;
typedef struct | GateDualCore_Params// Instance config-params structure ...
typedef struct | GateDualCore_Struct// Opaque client structure large enough to hold an instance object GateDualCore_Struct;
Constants
extern const Assert_Id | GateDualCore_A_nestedEnter// Assert if nested "enter" called;
extern const Bool | GateDualCore_enableStats// Gate statistics collection flag. Default is disabled;
extern const Error_Id | GateDualCore_E_gateInUse// Error raised if a Gate is already in use;
extern const Error_Id | GateDualCore_E_invalidIndex// Error raised if an invalid Gate index is provided;
extern const Ptr | GateDualCore_gateArrayAddress// Base address of configurable Ducati Gate Array;
extern const Bool | GateDualCore_initGates// Gate initialize flag;
extern const UInt | GateDualCore_numGates// Number of Gates that can be created. Default is 4;
DETAILS
GateDualCore uses disabling and enabling of interrupts as well as a shared variable between the two M3 cores as the resource locking mechanism. Such a gate guarantees exclusive access to a resource shared between the cores.
Each gate consumes one 32 bit word of shared memory. An array of these gates is shared between the two M3 cores and therefore the address of this array must be known to both (see gateArrayAddress).
By default, the array has 4 entries (see numGates) and is placed immediately below Core 0's default interrupt vector table address. It is the responsibility of the user to configure both cores with the same array address and size.
RESTRICTIONS
In a dual core M3 (Ducati) environment, core 0 is responsible for initializing the shared gate variable, therefore core 0 must be brought up BEFORE core 1 invokes GateDualCore_enter(). This can be achieved by simply running core 0 to its main() function prior to loading and running core 1.
GateDualCore does not support nesting of enter/leave calls.
Global interrupts are disabled upon return from GateDualCore_enter(). The duration between the enter and leave should be as short as possible to minimize Hwi latency and stalls by the other M3 core.
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module and is internally configured for its use.
const GateDualCore_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateDualCore_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateDualCore_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateDualCore_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateDualCore_A_nestedEnter // module-wide
index URL

Assert if nested "enter" called

C synopsis target-domain
extern const Assert_Id GateDualCore_A_nestedEnter;
config GateDualCore_E_gateInUse // module-wide
index URL

Error raised if a Gate is already in use

C synopsis target-domain
extern const Error_Id GateDualCore_E_gateInUse;
config GateDualCore_E_invalidIndex // module-wide
index URL

Error raised if an invalid Gate index is provided

C synopsis target-domain
extern const Error_Id GateDualCore_E_invalidIndex;
config GateDualCore_enableStats // module-wide
index URL

Gate statistics collection flag. Default is disabled

C synopsis target-domain
extern const Bool GateDualCore_enableStats;
config GateDualCore_gateArrayAddress // module-wide
index URL

Base address of configurable Ducati Gate Array

C synopsis target-domain
extern const Ptr GateDualCore_gateArrayAddress;
DETAILS
Each gate consumes one 32 bit word of shared memory. The array is shared between the two M3 cores and therefore the address of this array must be the same for both.
By default, the array has 4 entries (see numGates) and is placed immediately below Core 1's default interrupt vector table address of 0x00000800 (see ti.sysbios.family.arm.m3.Hwi.vectorTableAddress).
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module.
config GateDualCore_initGates // module-wide
index URL

Gate initialize flag

C synopsis target-domain
extern const Bool GateDualCore_initGates;
DETAILS
By default, core 0 initializes all of the gates in gateArray. This behavior can be overridden by explicitly setting this flag within your config script.
config GateDualCore_numGates // module-wide
index URL

Number of Gates that can be created. Default is 4

C synopsis target-domain
extern const UInt GateDualCore_numGates;
DETAILS
Each gate consumes one 32 bit word of memory. (see gateArrayAddress).
GateDualCore_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateDualCore_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateDualCore_Module_id();
// Get this module's unique id
Bool GateDualCore_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateDualCore_Module_heap();
// The heap from which this module allocates memory
Bool GateDualCore_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateDualCore_Module_getMask();
// Returns the diagnostics mask for this module
Void GateDualCore_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateDualCore_Object GateDualCore_Object;
// Opaque internal representation of an instance object
typedef GateDualCore_Object *GateDualCore_Handle;
// Client reference to an instance object
typedef struct GateDualCore_Struct GateDualCore_Struct;
// Opaque client structure large enough to hold an instance object
GateDualCore_Handle GateDualCore_handle(GateDualCore_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateDualCore_Struct *GateDualCore_struct(GateDualCore_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateDualCore_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UInt index;
    // index of the gate variable in the shared gateArray table
} GateDualCore_Params;
Void GateDualCore_Params_init(GateDualCore_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config GateDualCore_index // instance
index URL

index of the gate variable in the shared gateArray table

C synopsis target-domain
struct GateDualCore_Params {
     ...
    UInt index;
Instance Creation
index URL

C synopsis target-domain
GateDualCore_Handle GateDualCore_create(const GateDualCore_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateDualCore_construct(GateDualCore_Struct *structP, const GateDualCore_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateDualCore_delete(GateDualCore_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateDualCore_destruct(GateDualCore_Struct *structP);
// Finalize the instance object inside the provided structure
GateDualCore_sync() // instance
index URL

Sync execution with the other M3 core

C synopsis target-domain
Void GateDualCore_sync(GateDualCore_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateDualCore instance object
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateDualCore_Handle_upCast(GateDualCore_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateDualCore_Handle GateDualCore_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateDualCore_Object_count();
// The number of statically-created instance objects
GateDualCore_Handle GateDualCore_Object_get(GateDualCore_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateDualCore_Handle GateDualCore_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateDualCore_Handle GateDualCore_Object_next(GateDualCore_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateDualCore_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateDualCore_Handle_label(GateDualCore_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateDualCore_Handle_name(GateDualCore_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/GateDualCore.xdc
var GateDualCore = xdc.useModule('ti.sysbios.family.arm.ducati.GateDualCore');
module-wide constants & types
    const GateDualCore.Q_BLOCKING// Blocking quality = 1;
    const GateDualCore.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateDualCore.A_nestedEnter// Assert if nested "enter" called = Assert.Desc {
        msg: "A_nestedEnter: Can't nest 'enter' calls."
    };
     GateDualCore.E_gateInUse// Error raised if a Gate is already in use = Error.Desc {
        msg: "E_gateInUse %d"
    };
     GateDualCore.E_invalidIndex// Error raised if an invalid Gate index is provided = Error.Desc {
        msg: "E_invalidIndex %d"
    };
     GateDualCore.enableStats// Gate statistics collection flag. Default is disabled = Bool false;
     GateDualCore.gateArrayAddress// Base address of configurable Ducati Gate Array = Ptr 0x000007f0;
     GateDualCore.initGates// Gate initialize flag = Bool undefined;
     GateDualCore.numGates// Number of Gates that can be created. Default is 4 = UInt 4;
     GateDualCore.common$// Common module configuration parameters = Types.Common$ undefined;
     GateDualCore.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
module-wide functions
     GateDualCore.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateDualCore.Params// Instance config-params object;
        params.index// index of the gate variable in the shared gateArray table = UInt 0;
per-instance creation
    var inst = GateDualCore.create// Create an instance-object(params);
const GateDualCore.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateDualCore.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateDualCore_Q_BLOCKING
const GateDualCore.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateDualCore.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateDualCore_Q_PREEMPTING
config GateDualCore.A_nestedEnter // module-wide
index URL

Assert if nested "enter" called

XDCscript usage meta-domain
GateDualCore.A_nestedEnter = Assert.Desc {
    msg: "A_nestedEnter: Can't nest 'enter' calls."
};
C SYNOPSIS
GateDualCore_A_nestedEnter
config GateDualCore.E_gateInUse // module-wide
index URL

Error raised if a Gate is already in use

XDCscript usage meta-domain
GateDualCore.E_gateInUse = Error.Desc {
    msg: "E_gateInUse %d"
};
C SYNOPSIS
GateDualCore_E_gateInUse
config GateDualCore.E_invalidIndex // module-wide
index URL

Error raised if an invalid Gate index is provided

XDCscript usage meta-domain
GateDualCore.E_invalidIndex = Error.Desc {
    msg: "E_invalidIndex %d"
};
C SYNOPSIS
GateDualCore_E_invalidIndex
config GateDualCore.enableStats // module-wide
index URL

Gate statistics collection flag. Default is disabled

XDCscript usage meta-domain
GateDualCore.enableStats = Bool false;
C SYNOPSIS
GateDualCore_enableStats
config GateDualCore.gateArrayAddress // module-wide
index URL

Base address of configurable Ducati Gate Array

XDCscript usage meta-domain
GateDualCore.gateArrayAddress = Ptr 0x000007f0;
DETAILS
Each gate consumes one 32 bit word of shared memory. The array is shared between the two M3 cores and therefore the address of this array must be the same for both.
By default, the array has 4 entries (see numGates) and is placed immediately below Core 1's default interrupt vector table address of 0x00000800 (see ti.sysbios.family.arm.m3.Hwi.vectorTableAddress).
Gate zero (0) is reserved for the ti.sysbios.hal.unicache.Cache module.
C SYNOPSIS
GateDualCore_gateArrayAddress
config GateDualCore.initGates // module-wide
index URL

Gate initialize flag

XDCscript usage meta-domain
GateDualCore.initGates = Bool undefined;
DETAILS
By default, core 0 initializes all of the gates in gateArray. This behavior can be overridden by explicitly setting this flag within your config script.
C SYNOPSIS
GateDualCore_initGates
config GateDualCore.numGates // module-wide
index URL

Number of Gates that can be created. Default is 4

XDCscript usage meta-domain
GateDualCore.numGates = UInt 4;
DETAILS
Each gate consumes one 32 bit word of memory. (see gateArrayAddress).
C SYNOPSIS
GateDualCore_numGates
metaonly config GateDualCore.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateDualCore.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config GateDualCore.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
GateDualCore.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly GateDualCore.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateDualCore.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateDualCore.Params;
// Instance config-params object
    params.index = UInt 0;
    // index of the gate variable in the shared gateArray table
config GateDualCore.index // instance
index URL

index of the gate variable in the shared gateArray table

XDCscript usage meta-domain
var params = new GateDualCore.Params;
...
params.index = UInt 0;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateDualCore.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateDualCore.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:34 GMT


module ti.sysbios.family.arm.ducati.Timer
index URL

Ducati Cortex M3 Timer Peripherals Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The timers used in Ducati are the NVIC SysTick timer and the two CTM timers (0 and 1) that support interrupts. The CTM timers are shared between the two M3 cores. Core 0 uses CTM timer 0 and Core 1 uses timer 1. Each core then supports 2 timers. Timer 0 is the core's SysTick timer and Timer 1 is the core's CTM timer. Both timers are clocked at the CPU clock rate, nominally 200MHz. Timer 0 (the SysTick timer) has only 24 bits of period resolution (up to 83ms). Timer 1 (the CTM timer) supports a full 32 bit period (up to 21 seconds). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/Timer.xdc
#include <ti/sysbios/family/arm/ducati/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Timer_Handle | Timer_getHandle// Get Handle associated with a timer id(UInt id);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)2
#define | Timer_TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock (Int)1
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
DETAILS
The timers used in Ducati are the NVIC SysTick timer and the two CTM timers (0 and 1) that support interrupts. The CTM timers are shared between the two M3 cores. Core 0 uses CTM timer 0 and Core 1 uses timer 1. Each core then supports 2 timers. Timer 0 is the core's SysTick timer and Timer 1 is the core's CTM timer. Both timers are clocked at the CPU clock rate, nominally 200MHz. Timer 0 (the SysTick timer) has only 24 bits of period resolution (up to 83ms). Timer 1 (the CTM timer) supports a full 32 bit period (up to 21 seconds).

Calling Context

Function Hwi Swi Task Main Startup
getNumTimers - - - - -
getStatus - - - - -
Params_init - - - - -
construct - - - - -
create - - - - -
delete - - - - -
destruct - - - - -
getCount - - - - -
getFreq - - - - -
getPeriod - - - - -
reconfig - - - - -
setPeriod - - - - -
setPeriodMicroSecs - - - - -
start - - - - -
stop - - - - -
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)2
DETAILS
Only 2 are available to each core.
const Timer_TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

C synopsis target-domain
#define Timer_TIMER_CLOCK_DIVIDER (Int)1
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getHandle() // module-wide
index URL

Get Handle associated with a timer id

C synopsis target-domain
Timer_Handle Timer_getHandle(UInt id);
ARGUMENTS
id — timer Id.
RETURNS
timer Handle
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — function that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.arm.ducati.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 2;
    const Timer.TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock = 1;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 2;
DETAILS
Only 2 are available to each core.
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
const Timer.TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

XDCscript usage meta-domain
const Timer.TIMER_CLOCK_DIVIDER = 1;
C SYNOPSIS
Timer_TIMER_CLOCK_DIVIDER
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:34 GMT


module ti.sysbios.family.arm.ducati.TimestampProvider
index URL

Ducati Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The timestamp counters used in Ducati are CTM counters 2,3,4,5. Each core uses two counters in chained mode to achieve 64 bits. Core 0 uses counters 2,3. Core 1 uses counters 4,5. Which ever core is started first will start both sets of counters synchronously so that both cores effectively share a common timestamp. By default, the CTM counters are clocked at 2 times the CPU clock. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/TimestampProvider.xdc
#include <ti/sysbios/family/arm/ducati/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt8 | TimestampProvider_inpsel// Counter Input Select. The default value of 0 selects the 2x CPU clock as the clock source for the timestamp counters;
DETAILS
The timestamp counters used in Ducati are CTM counters 2,3,4,5. Each core uses two counters in chained mode to achieve 64 bits. Core 0 uses counters 2,3. Core 1 uses counters 4,5. Which ever core is started first will start both sets of counters synchronously so that both cores effectively share a common timestamp. By default, the CTM counters are clocked at 2 times the CPU clock.

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
config TimestampProvider_inpsel // module-wide
index URL

Counter Input Select. The default value of 0 selects the 2x CPU clock as the clock source for the timestamp counters

C synopsis target-domain
extern const UInt8 TimestampProvider_inpsel;
DETAILS
See Table 28-22 of the OMAP4430 TRM for details of the various events that can be counted.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.ducati.TimestampProvider');
module-wide config parameters
     TimestampProvider.inpsel// Counter Input Select. The default value of 0 selects the 2x CPU clock as the clock source for the timestamp counters = UInt8 0;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
     TimestampProvider.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
config TimestampProvider.inpsel // module-wide
index URL

Counter Input Select. The default value of 0 selects the 2x CPU clock as the clock source for the timestamp counters

XDCscript usage meta-domain
TimestampProvider.inpsel = UInt8 0;
DETAILS
See Table 28-22 of the OMAP4430 TRM for details of the various events that can be counted.
C SYNOPSIS
TimestampProvider_inpsel
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config TimestampProvider.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
TimestampProvider.rovViewInfo = ViewInfo.Instance ViewInfo.create;
generated on Fri, 17 Jun 2011 00:23:34 GMT


module ti.sysbios.family.arm.ducati.Wugen
index URL

Wugen Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Unconstrained Functions All functions [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/Wugen.xdc
#include <ti/sysbios/family/arm/ducati/Wugen.h>
Functions
Void | Wugen_disableInterrupt// Disables the specified interrupt in the WUGEN(UInt intNum);
Void | Wugen_enableInterrupt// Enables the specified interrupt in the WUGEN(UInt intNum);
Functions common to all target modules
 | Wugen_Module_getMask// Returns the diagnostics mask for this module, Wugen_Module_hasMask// Test whether this module has a diagnostics mask, Wugen_Module_heap// The heap from which this module allocates memory, Wugen_Module_id// Get this module's unique id, Wugen_Module_setMask// Set the diagnostics mask for this module, Wugen_Module_startupDone// Test if this module has completed startup
DETAILS
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disableInterrupt | Y | Y | Y | Y | Y
enableInterrupt | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
Wugen_disableInterrupt() // module-wide
index URL

Disables the specified interrupt in the WUGEN

C synopsis target-domain
Void Wugen_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — the interrupt number
Wugen_enableInterrupt() // module-wide
index URL

Enables the specified interrupt in the WUGEN

C synopsis target-domain
Void Wugen_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — the interrupt number
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Wugen_Module_id();
// Get this module's unique id
Bool Wugen_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Wugen_Module_heap();
// The heap from which this module allocates memory
Bool Wugen_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Wugen_Module_getMask();
// Returns the diagnostics mask for this module
Void Wugen_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/Wugen.xdc
var Wugen = xdc.useModule('ti.sysbios.family.arm.ducati.Wugen');
module-wide config parameters
     Wugen.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config Wugen.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Wugen.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:34 GMT


package ti.sysbios.family.arm.ducati.dm8148
index URL

Contains dm8148 Hwi helper module

XDCspec declarations sourced in ti/sysbios/family/arm/ducati/dm8148/package.xdc
package ti.sysbios.family.arm.ducati.dm8148 [2, 0, 0, 0] {
    module IntMux;
    // IntMux Module
}
generated on Fri, 17 Jun 2011 00:23:35 GMT


module ti.sysbios.family.arm.ducati.dm8148.IntMux
index URL

IntMux Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Below is an example of how to override the default mapping of interrupt 42 so that it is sourced by I2CINT2 rather than its default mapping to I2CINT1: [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/dm8148/IntMux.xdc
#include <ti/sysbios/family/arm/ducati/dm8148/IntMux.h>
Functions
Void | IntMux_setEvent// Set the event number associated with an interrupt(UInt intMuxNum, UInt eventNum);
Functions common to all target modules
 | IntMux_Module_getMask// Returns the diagnostics mask for this module, IntMux_Module_hasMask// Test whether this module has a diagnostics mask, IntMux_Module_heap// The heap from which this module allocates memory, IntMux_Module_id// Get this module's unique id, IntMux_Module_setMask// Set the diagnostics mask for this module, IntMux_Module_startupDone// Test if this module has completed startup
Constants
extern const Assert_Id | IntMux_A_badEventNum// Assert if event number > 47;
extern const Assert_Id | IntMux_A_badIntNum// Assert if interrupt number > 56;
extern const Ptr | IntMux_intMuxBaseAddr// Address of "DUCATI_INTMUX_0_3" register;
DETAILS
Below is an example of how to override the default mapping of interrupt 42 so that it is sourced by I2CINT2 rather than its default mapping to I2CINT1:
  #include <ti/sysbios/family/arm/m3/Hwi.h>
  #include <ti/sysbios/family/arm/ducati/dm8148/IntMux.h>

  Void myI2CINT2Handler(UArg arg)
  {
      System_printf("I2CINT2 arg = %d\n", (UInt)arg);
  }

  Int main(Int argc, Char* argv[])
  {
      Hwi_Params params;

      Hwi_Params_init(&params);

      // set IntMux 19 to event number 4 (I2CINT2)
      IntMux_setEvent(19, 4);

      // create a corresponding interrupt handler
      // notice that Ducati interrupt number 42 corresponds to IntMux 19

      params.arg = 42; // pass the Int number to the handler for demo

      Hwi_create(42, myI2CINT2Handler, &params, NULL);

      BIOS_start();

      return (0);
  }
Here is how you would define the same interrupt handler statically in a configuration script:
  var Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
  var IntMux = xdc.useModule('ti.sysbios.family.arm.ducati.dm8148.IntMux');

  IntMux.setEventMeta(19, 4);

  var hwiParams = new Hwi.Params();
  hwiParams.arg = 42;
  Program.global.staticHwi = Hwi.create(42, '&myI2CINT2Handler', hwiParams);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
setEvent | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
config IntMux_A_badEventNum // module-wide
index URL

Assert if event number > 47

C synopsis target-domain
extern const Assert_Id IntMux_A_badEventNum;
config IntMux_A_badIntNum // module-wide
index URL

Assert if interrupt number > 56

C synopsis target-domain
extern const Assert_Id IntMux_A_badIntNum;
config IntMux_intMuxBaseAddr // module-wide
index URL

Address of "DUCATI_INTMUX_0_3" register

C synopsis target-domain
extern const Ptr IntMux_intMuxBaseAddr;
IntMux_setEvent() // module-wide
index URL

Set the event number associated with an interrupt

C synopsis target-domain
Void IntMux_setEvent(UInt intMuxNum, UInt eventNum);
ARGUMENTS
intNum — The intMux number (0-56)
eventNum — The event number (0-47)
DETAILS
Dynamically sets the event number associated with an interrupt in the Ducati Interrupt Mux as described in section 5.9.2 of the Centaurus Architecture Spec.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId IntMux_Module_id();
// Get this module's unique id
Bool IntMux_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle IntMux_Module_heap();
// The heap from which this module allocates memory
Bool IntMux_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 IntMux_Module_getMask();
// Returns the diagnostics mask for this module
Void IntMux_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/dm8148/IntMux.xdc
var IntMux = xdc.useModule('ti.sysbios.family.arm.ducati.dm8148.IntMux');
module-wide config parameters
     IntMux.A_badEventNum// Assert if event number > 47 = Assert.Desc {
        msg: "A_badIntNum: eventNum must be <= 47"
    };
     IntMux.A_badIntNum// Assert if interrupt number > 56 = Assert.Desc {
        msg: "A_badIntNum: intNum must be <= 56"
    };
     IntMux.intMuxBaseAddr// Address of "DUCATI_INTMUX_0_3" register = Ptr 0x48140F54;
     IntMux.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     IntMux.setEventMeta// Set the event number associated with an interrupt(UInt intMuxNum, UInt eventNum) returns Void
config IntMux.A_badEventNum // module-wide
index URL

Assert if event number > 47

XDCscript usage meta-domain
IntMux.A_badEventNum = Assert.Desc {
    msg: "A_badIntNum: eventNum must be <= 47"
};
C SYNOPSIS
IntMux_A_badEventNum
config IntMux.A_badIntNum // module-wide
index URL

Assert if interrupt number > 56

XDCscript usage meta-domain
IntMux.A_badIntNum = Assert.Desc {
    msg: "A_badIntNum: intNum must be <= 56"
};
C SYNOPSIS
IntMux_A_badIntNum
config IntMux.intMuxBaseAddr // module-wide
index URL

Address of "DUCATI_INTMUX_0_3" register

XDCscript usage meta-domain
IntMux.intMuxBaseAddr = Ptr 0x48140F54;
C SYNOPSIS
IntMux_intMuxBaseAddr
metaonly config IntMux.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
IntMux.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly IntMux.setEventMeta() // module-wide
index URL

Set the event number associated with an interrupt

XDCscript usage meta-domain
IntMux.setEventMeta(UInt intMuxNum, UInt eventNum) returns Void
ARGUMENTS
intNum — The intMux number (0-56)
eventNum — The event number (0-47)
DETAILS
Statically sets the event number associated with an interrupt in the Ducati Interrupt Mux as described in section 5.9.2 of the Centaurus Architecture Spec.
generated on Fri, 17 Jun 2011 00:23:35 GMT


package ti.sysbios.family.arm.ducati.omap4430
index URL

Contains specifications for the Ducati, on OMAP4430

XDCspec declarations sourced in ti/sysbios/family/arm/ducati/omap4430/package.xdc
package ti.sysbios.family.arm.ducati.omap4430 [1, 0, 0, 0] {
    module Power;
    // Power support for Ducati on OMAP4430
}
generated on Fri, 17 Jun 2011 00:23:35 GMT


module ti.sysbios.family.arm.ducati.omap4430.Power
index URL

Power support for Ducati on OMAP4430

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/arm/ducati/omap4430/Power.xdc
#include <ti/sysbios/family/arm/ducati/omap4430/Power.h>
Functions
Void | Power_idleCPU// Function used to automatically idle the CPU in the Idle loop();
UInt | Power_suspend// Function used for suspend/resume of the M3 cores(Power_SuspendArgs *args);
Functions common to all target modules
 | Power_Module_getMask// Returns the diagnostics mask for this module, Power_Module_hasMask// Test whether this module has a diagnostics mask, Power_Module_heap// The heap from which this module allocates memory, Power_Module_id// Get this module's unique id, Power_Module_setMask// Set the diagnostics mask for this module, Power_Module_startupDone// Test if this module has completed startup
Defines
#define | Power_L2RAM// Physical address of L2 RAM (Ptr)0x55020000
Typedefs
typedef struct | Power_SuspendArgs// Suspend arguments structure ...
Constants
extern const Bool | Power_idle// Idle the CPU when threads blocked waiting for an interrupt?;
extern const UInt | Power_rendezvousGateIndex// Rendezvous Gate index;
extern const Ptr | Power_sdmaRegs// Base address of SDMA registers;
const Power_L2RAM
index URL

Physical address of L2 RAM

C synopsis target-domain
#define Power_L2RAM (Ptr)0x55020000
struct Power_SuspendArgs
index URL

Suspend arguments structure

C synopsis target-domain
typedef struct Power_SuspendArgs {
    Bool pmMasterCore;
    // Master core for suspend/resume?
    Bool rendezvousResume;
    // Rendezvous before resume?
    Int dmaChannel;
    // SDMA channel for L2 RAM save; -1=CPU copy
    UInt intMask31_0;
    // Mask of interrupts (31-0) able to wake WFI
    UInt intMask63_32;
    // Mask of interrupts (63-32) able to wake WFI
    UInt intMask79_64;
    // Mask of interrupts (79-64) able to wake WFI
} Power_SuspendArgs;
config Power_idle // module-wide
index URL

Idle the CPU when threads blocked waiting for an interrupt?

C synopsis target-domain
extern const Bool Power_idle;
config Power_rendezvousGateIndex // module-wide
index URL

Rendezvous Gate index

C synopsis target-domain
extern const UInt Power_rendezvousGateIndex;
config Power_sdmaRegs // module-wide
index URL

Base address of SDMA registers

C synopsis target-domain
extern const Ptr Power_sdmaRegs;
Power_idleCPU() // module-wide
index URL

Function used to automatically idle the CPU in the Idle loop

C synopsis target-domain
Void Power_idleCPU();
DETAILS
When the 'idle' configuration parameter is set, this function will be added to the list of Idle loop functions. When called from the Idle loop, it will invoke the wait for interrupt (WFI) instruction, to idle the CPU until the next interrupt occurs.
Power_suspend() // module-wide
index URL

Function used for suspend/resume of the M3 cores

C synopsis target-domain
UInt Power_suspend(Power_SuspendArgs *args);
DETAILS
Precondition and usage constraints:
1) Before this function is called the application must disable all interrupts that are not desired to wake the CPU from WFI while waiting for the core domain to go off.
2) For those interrupts that are desired to wake the CPU from WFI (for example, the mailbox interrupt), these interrupts cannot be generated until the Power_suspend API has reached the point of executing WFI. If the interrupts happen early, while this API is saving context, the resulting context may be stale, and the application may not resume correctly. Two global flags (one for each M3 core) are assert immediately before invoking WFI; the wakeup interrupts should not be asserted until these flags are asserted (non-zero): ti_sysbios_family_arm_ducati_omap4430_readyIdleCore0 ti_sysbios_family_arm_ducati_omap4430_readyIdleCore1
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Power_Module_id();
// Get this module's unique id
Bool Power_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Power_Module_heap();
// The heap from which this module allocates memory
Bool Power_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Power_Module_getMask();
// Returns the diagnostics mask for this module
Void Power_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/ducati/omap4430/Power.xdc
var Power = xdc.useModule('ti.sysbios.family.arm.ducati.omap4430.Power');
module-wide constants & types
    const Power.L2RAM// Physical address of L2 RAM = 0x55020000;
    var obj = new Power.SuspendArgs// Suspend arguments structure;
        obj.pmMasterCore// Master core for suspend/resume? = Bool ...
        obj.rendezvousResume// Rendezvous before resume? = Bool ...
        obj.dmaChannel// SDMA channel for L2 RAM save; -1=CPU copy = Int ...
        obj.intMask31_0// Mask of interrupts (31-0) able to wake WFI = UInt ...
        obj.intMask63_32// Mask of interrupts (63-32) able to wake WFI = UInt ...
        obj.intMask79_64// Mask of interrupts (79-64) able to wake WFI = UInt ...
module-wide config parameters
     Power.idle// Idle the CPU when threads blocked waiting for an interrupt? = Bool false;
     Power.rendezvousGateIndex// Rendezvous Gate index = UInt 1;
     Power.sdmaRegs// Base address of SDMA registers = Ptr 0x4A056000;
     Power.common$// Common module configuration parameters = Types.Common$ undefined;
     Power.loadSegment// Segment to load Power's shared reset code and data = String "EXT_SHARED_RAM";
const Power.L2RAM
index URL

Physical address of L2 RAM

XDCscript usage meta-domain
const Power.L2RAM = 0x55020000;
C SYNOPSIS
Power_L2RAM
struct Power.SuspendArgs
index URL

Suspend arguments structure

XDCscript usage meta-domain
var obj = new Power.SuspendArgs;
    obj.pmMasterCore = Bool ...
    // Master core for suspend/resume?
    obj.rendezvousResume = Bool ...
    // Rendezvous before resume?
    obj.dmaChannel = Int ...
    // SDMA channel for L2 RAM save; -1=CPU copy
    obj.intMask31_0 = UInt ...
    // Mask of interrupts (31-0) able to wake WFI
    obj.intMask63_32 = UInt ...
    // Mask of interrupts (63-32) able to wake WFI
    obj.intMask79_64 = UInt ...
    // Mask of interrupts (79-64) able to wake WFI
C SYNOPSIS
Power_SuspendArgs
config Power.idle // module-wide
index URL

Idle the CPU when threads blocked waiting for an interrupt?

XDCscript usage meta-domain
Power.idle = Bool false;
C SYNOPSIS
Power_idle
config Power.rendezvousGateIndex // module-wide
index URL

Rendezvous Gate index

XDCscript usage meta-domain
Power.rendezvousGateIndex = UInt 1;
C SYNOPSIS
Power_rendezvousGateIndex
config Power.sdmaRegs // module-wide
index URL

Base address of SDMA registers

XDCscript usage meta-domain
Power.sdmaRegs = Ptr 0x4A056000;
C SYNOPSIS
Power_sdmaRegs
metaonly config Power.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Power.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Power.loadSegment // module-wide
index URL

Segment to load Power's shared reset code and data

XDCscript usage meta-domain
Power.loadSegment = String "EXT_SHARED_RAM";
generated on Fri, 17 Jun 2011 00:23:35 GMT


package ti.sysbios.family.arm.exc
index URL

Contains the ARM Exception handler used by all non-M3 ARM targets

XDCspec declarations sourced in ti/sysbios/family/arm/exc/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.exc [2, 0, 0, 0] {
    module Exception;
    // Exception Module
}
generated on Fri, 17 Jun 2011 00:23:36 GMT


module ti.sysbios.family.arm.exc.Exception
index URL

Exception Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Exception module is a basic ARM exception handler. No attempt is made to return from an exception as these are generally fatal in nature. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/exc/Exception.xdc
#include <ti/sysbios/family/arm/exc/Exception.h>
Functions common to all target modules
 | Exception_Module_getMask// Returns the diagnostics mask for this module, Exception_Module_hasMask// Test whether this module has a diagnostics mask, Exception_Module_heap// The heap from which this module allocates memory, Exception_Module_id// Get this module's unique id, Exception_Module_setMask// Set the diagnostics mask for this module, Exception_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | Exception_ExcContext// Exception Context - Register contents at the time of an exception ...
typedef Void | (*Exception_ExceptionHookFuncPtr// Exception hook function type definition)(Exception_ExcContext*);
typedef enum | Exception_Type// ...
Constants
extern const Bool | Exception_enableDecode// Enable full exception decoding, default is true;
extern const Exception_ExceptionHookFuncPtr | Exception_excHookFunc// User Exception hook function;
extern const Ptr | Exception_excStack// Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Error_Id | Exception_E_dataAbort// Error raised when an data abort exception occurs;
extern const Error_Id | Exception_E_prefetchAbort// Error raised when an prefetch abort exception occurs;
extern const Error_Id | Exception_E_swi// Error raised when a SWI exception occurs;
extern const Error_Id | Exception_E_undefinedInstruction// Error raised when an undefined instruction exception occurs;
DETAILS
The Exception module is a basic ARM exception handler. No attempt is made to return from an exception as these are generally fatal in nature.
When used, the Exception module will override the default exception handlers provided by the current Hwi module.
enum Exception_Type
index URL
C synopsis target-domain
typedef enum Exception_Type {
    Exception_Type_Supervisor,
    // Supervisor (SWI)
    Exception_Type_PreAbort,
    // Abort exception
    Exception_Type_DataAbort,
    // Abort exception
    Exception_Type_UndefInst
    // Undefined instruction exception
} Exception_Type;
typedef Exception_ExceptionHookFuncPtr
index URL

Exception hook function type definition

C synopsis target-domain
typedef Void (*Exception_ExceptionHookFuncPtr)(Exception_ExcContext*);
struct Exception_ExcContext
index URL

Exception Context - Register contents at the time of an exception

C synopsis target-domain
typedef struct Exception_ExcContext {
     BIOS_ThreadType threadType;
    Ptr threadHandle;
    Ptr threadStack;
    SizeT threadStackSize;
     Exception_Type type;
    Ptr r0;
    Ptr r1;
    Ptr r2;
    Ptr r3;
    Ptr r4;
    Ptr r5;
    Ptr r6;
    Ptr r7;
    Ptr r8;
    Ptr r9;
    Ptr r10;
    Ptr r11;
    Ptr r12;
    Ptr sp;
    Ptr lr;
    Ptr pc;
    Ptr psr;
} Exception_ExcContext;
config Exception_E_dataAbort // module-wide
index URL

Error raised when an data abort exception occurs

C synopsis target-domain
extern const Error_Id Exception_E_dataAbort;
config Exception_E_prefetchAbort // module-wide
index URL

Error raised when an prefetch abort exception occurs

C synopsis target-domain
extern const Error_Id Exception_E_prefetchAbort;
config Exception_E_swi // module-wide
index URL

Error raised when a SWI exception occurs

C synopsis target-domain
extern const Error_Id Exception_E_swi;
config Exception_E_undefinedInstruction // module-wide
index URL

Error raised when an undefined instruction exception occurs

C synopsis target-domain
extern const Error_Id Exception_E_undefinedInstruction;
config Exception_enableDecode // module-wide
index URL

Enable full exception decoding, default is true

C synopsis target-domain
extern const Bool Exception_enableDecode;
DETAILS
When enabled, the exception handler will fully decode an exception and dump the registers to the system console.
When set to false, only an Error is printed on the console.
In either case, the full exception context is always saved and visible with ROV.
config Exception_excHookFunc // module-wide
index URL

User Exception hook function

C synopsis target-domain
extern const Exception_ExceptionHookFuncPtr Exception_excHookFunc;
DETAILS
Called just after exception context has been initialized.
config Exception_excStack // module-wide
index URL

Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Exception_excStack;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Exception_Module_id();
// Get this module's unique id
Bool Exception_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Exception_Module_heap();
// The heap from which this module allocates memory
Bool Exception_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Exception_Module_getMask();
// Returns the diagnostics mask for this module
Void Exception_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/exc/Exception.xdc
var Exception = xdc.useModule('ti.sysbios.family.arm.exc.Exception');
module-wide constants & types
    values of type Exception.Type//
        const Exception.Type_Supervisor// Supervisor (SWI);
        const Exception.Type_PreAbort// Abort exception;
        const Exception.Type_DataAbort// Abort exception;
        const Exception.Type_UndefInst// Undefined instruction exception;
    var obj = new Exception.ExcContext// Exception Context - Register contents at the time of an exception;
        obj.threadType = BIOS.ThreadType ...
        obj.threadHandle = Ptr ...
        obj.threadStack = Ptr ...
        obj.threadStackSize = SizeT ...
        obj.type = Exception.Type ...
        obj.r0 = Ptr ...
        obj.r1 = Ptr ...
        obj.r2 = Ptr ...
        obj.r3 = Ptr ...
        obj.r4 = Ptr ...
        obj.r5 = Ptr ...
        obj.r6 = Ptr ...
        obj.r7 = Ptr ...
        obj.r8 = Ptr ...
        obj.r9 = Ptr ...
        obj.r10 = Ptr ...
        obj.r11 = Ptr ...
        obj.r12 = Ptr ...
        obj.sp = Ptr ...
        obj.lr = Ptr ...
        obj.pc = Ptr ...
        obj.psr = Ptr ...
module-wide config parameters
     Exception.E_dataAbort// Error raised when an data abort exception occurs = Error.Desc {
        msg: "E_dataAbort: pc = 0x%08x, lr = 0x%08x."
    };
     Exception.E_prefetchAbort// Error raised when an prefetch abort exception occurs = Error.Desc {
        msg: "E_prefetchAbort: pc = 0x%08x, lr = 0x%08x."
    };
     Exception.E_swi// Error raised when a SWI exception occurs = Error.Desc {
        msg: "E_swi: pc = 0x%08x, lr = 0x%08x."
    };
     Exception.E_undefinedInstruction// Error raised when an undefined instruction exception occurs = Error.Desc {
        msg: "E_undefinedInstruction: pc = 0x%08x, lr = 0x%08x."
    };
     Exception.enableDecode// Enable full exception decoding, default is true = Bool true;
     Exception.excHookFunc// User Exception hook function = Void(*)(Exception.ExcContext*) null;
     Exception.excStack// Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Exception.common$// Common module configuration parameters = Types.Common$ undefined;
     Exception.excContextBuffer// User Exception Context Buffer Address = Ptr undefined;
     Exception.excStackBuffer// User Exception Stack Buffer Address = Ptr undefined;
     Exception.excStackSection// Memory section used for Exception stack Default is null = String null;
     Exception.excStackSize// Exception stack size in MAUs. Default is 128 bytes = SizeT 128;
     Exception.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
enum Exception.Type
index URL
XDCscript usage meta-domain
values of type Exception.Type
    const Exception.Type_Supervisor;
    // Supervisor (SWI)
    const Exception.Type_PreAbort;
    // Abort exception
    const Exception.Type_DataAbort;
    // Abort exception
    const Exception.Type_UndefInst;
    // Undefined instruction exception
C SYNOPSIS
Exception_Type
struct Exception.ExcContext
index URL

Exception Context - Register contents at the time of an exception

XDCscript usage meta-domain
var obj = new Exception.ExcContext;
    obj.threadType = BIOS.ThreadType ...
    obj.threadHandle = Ptr ...
    obj.threadStack = Ptr ...
    obj.threadStackSize = SizeT ...
    obj.type = Exception.Type ...
    obj.r0 = Ptr ...
    obj.r1 = Ptr ...
    obj.r2 = Ptr ...
    obj.r3 = Ptr ...
    obj.r4 = Ptr ...
    obj.r5 = Ptr ...
    obj.r6 = Ptr ...
    obj.r7 = Ptr ...
    obj.r8 = Ptr ...
    obj.r9 = Ptr ...
    obj.r10 = Ptr ...
    obj.r11 = Ptr ...
    obj.r12 = Ptr ...
    obj.sp = Ptr ...
    obj.lr = Ptr ...
    obj.pc = Ptr ...
    obj.psr = Ptr ...
C SYNOPSIS
Exception_ExcContext
config Exception.E_dataAbort // module-wide
index URL

Error raised when an data abort exception occurs

XDCscript usage meta-domain
Exception.E_dataAbort = Error.Desc {
    msg: "E_dataAbort: pc = 0x%08x, lr = 0x%08x."
};
C SYNOPSIS
Exception_E_dataAbort
config Exception.E_prefetchAbort // module-wide
index URL

Error raised when an prefetch abort exception occurs

XDCscript usage meta-domain
Exception.E_prefetchAbort = Error.Desc {
    msg: "E_prefetchAbort: pc = 0x%08x, lr = 0x%08x."
};
C SYNOPSIS
Exception_E_prefetchAbort
config Exception.E_swi // module-wide
index URL

Error raised when a SWI exception occurs

XDCscript usage meta-domain
Exception.E_swi = Error.Desc {
    msg: "E_swi: pc = 0x%08x, lr = 0x%08x."
};
C SYNOPSIS
Exception_E_swi
config Exception.E_undefinedInstruction // module-wide
index URL

Error raised when an undefined instruction exception occurs

XDCscript usage meta-domain
Exception.E_undefinedInstruction = Error.Desc {
    msg: "E_undefinedInstruction: pc = 0x%08x, lr = 0x%08x."
};
C SYNOPSIS
Exception_E_undefinedInstruction
config Exception.enableDecode // module-wide
index URL

Enable full exception decoding, default is true

XDCscript usage meta-domain
Exception.enableDecode = Bool true;
DETAILS
When enabled, the exception handler will fully decode an exception and dump the registers to the system console.
When set to false, only an Error is printed on the console.
In either case, the full exception context is always saved and visible with ROV.
C SYNOPSIS
Exception_enableDecode
config Exception.excHookFunc // module-wide
index URL

User Exception hook function

XDCscript usage meta-domain
Exception.excHookFunc = Void(*)(Exception.ExcContext*) null;
DETAILS
Called just after exception context has been initialized.
C SYNOPSIS
Exception_excHookFunc
config Exception.excStack // module-wide
index URL

Exception stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Exception.excStack = Ptr null;
C SYNOPSIS
Exception_excStack
metaonly config Exception.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Exception.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Exception.excContextBuffer // module-wide
index URL

User Exception Context Buffer Address

XDCscript usage meta-domain
Exception.excContextBuffer = Ptr undefined;
DETAILS
By default, when an exception occurs, an ExcContext structure is allocated on the ISR stack and filled in within the exception handler.
If excContextBuffer is initialized by the user, the ExcContext structure will be placed at that address instead.
The buffer must be large enough to contain an ExcContext structure.
metaonly config Exception.excStackBuffer // module-wide
index URL

User Exception Stack Buffer Address

XDCscript usage meta-domain
Exception.excStackBuffer = Ptr undefined;
DETAILS
By default, when an exception occurs, a pointer to the base address of the stack being used by the thread causing the exception is placed
If excStackBuffer is initialized by the user, the stack contents of the thread causing the exception will be copied to that address instead.
The buffer must be large enough to contain the largest task stack or ISR stack defined in the application.
metaonly config Exception.excStackSection // module-wide
index URL

Memory section used for Exception stack Default is null

XDCscript usage meta-domain
Exception.excStackSection = String null;
metaonly config Exception.excStackSize // module-wide
index URL

Exception stack size in MAUs. Default is 128 bytes

XDCscript usage meta-domain
Exception.excStackSize = SizeT 128;
metaonly config Exception.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
Exception.rovViewInfo = ViewInfo.Instance ViewInfo.create;
generated on Fri, 17 Jun 2011 00:23:36 GMT


package ti.sysbios.family.arm.f28m35x
index URL

Contains specifications for the C28 specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/f28m35x/package.xdc
package ti.sysbios.family.arm.f28m35x [2, 0, 0, 0] {
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:23:24 GMT


module ti.sysbios.family.arm.f28m35x.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/arm/f28m35x/TimestampProvider.xdc
#include <ti/sysbios/family/arm/f28m35x/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/f28m35x/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.f28m35x.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:24 GMT


package ti.sysbios.family.arm.lm3
index URL

Contains specifications for the Stellaris LM3S family of device-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/lm3/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.lm3 [2, 0, 0, 0] {
    module Timer;
    // Luminary Micro LM3 Timer Peripheral Driver
    module TimestampProvider;
    // Implements ITimestampProvider
}
generated on Fri, 17 Jun 2011 00:23:31 GMT


module ti.sysbios.family.arm.lm3.Timer
index URL

Luminary Micro LM3 Timer Peripheral Driver

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function Hwi Swi Task Main Startup
getNumTimers - - - - -
getStatus - - - - -
Params_init - - - - -
construct - - - - -
create - - - - -
delete - - - - -
destruct - - - - -
getCount - - - - -
getFreq - - - - -
getPeriod - - - - -
reconfig - - - - -
setPeriod - - - - -
setPeriodMicroSecs - - - - -
start - - - - -
stop - - - - -
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/arm/lm3/Timer.xdc
#include <ti/sysbios/family/arm/lm3/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Timer_Handle | Timer_getHandle// Get Handle associated with a timer id(UInt id);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock (Int)1
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

C synopsis target-domain
#define Timer_TIMER_CLOCK_DIVIDER (Int)1
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getHandle() // module-wide
index URL

Get Handle associated with a timer id

C synopsis target-domain
Timer_Handle Timer_getHandle(UInt id);
ARGUMENTS
id — timer Id.
RETURNS
timer Handle
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — function that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/lm3/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.arm.lm3.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock = 1;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

XDCscript usage meta-domain
const Timer.TIMER_CLOCK_DIVIDER = 1;
C SYNOPSIS
Timer_TIMER_CLOCK_DIVIDER
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:31 GMT


module ti.sysbios.family.arm.lm3.TimestampProvider
index URL

Implements ITimestampProvider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/lm3/TimestampProvider.xdc
#include <ti/sysbios/family/arm/lm3/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id;
extern const Bool | TimestampProvider_useClockTimer// Set this parameter when you want TimestampProvider to use the same timer as the Clock module;
DETAILS
Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp.
The SysTick timer is used as the timestamp source.

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
DETAILS
When not using the Clock timer, TimestampProvider will create an Timer using this timer id.
config TimestampProvider_useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider to use the same timer as the Clock module

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
This parameter overrides the timerId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/lm3/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.lm3.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Set this parameter when you want TimestampProvider to use the same timer as the Clock module = Bool false;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
DETAILS
When not using the Clock timer, TimestampProvider will create an Timer using this timer id.
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider to use the same timer as the Clock module

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool false;
DETAILS
This parameter overrides the timerId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:31 GMT


package ti.sysbios.family.arm.m3
index URL

Contains specifications for the m3 family/device-specific SYS/BIOS functions

The link below provides SYS/BIOS M3 register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/arm/m3/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.m3 [2, 0, 0, 0] {
    module Exception;
    // (Deprecated!) Exception Module
    module Hwi;
    // Cortex M3 Hardware Interrupt Manager
    module TaskSupport;
    // M3 Task Support Module
    module Timer;
    // Cortex M3 Timer Peripherals Manager
    module TimestampProvider;
    // Implements ITimestampProvider
}
DETAILS
The link below provides SYS/BIOS M3 register usage information:
SYS/BIOS M3 Register Usage
generated on Fri, 17 Jun 2011 00:23:30 GMT


module ti.sysbios.family.arm.m3.Exception

metaonly module ti.sysbios.family.arm.m3.Exception
index URL

(Deprecated!) Exception Module

  • XDCscript usage
  • Individual elements
Do not use this module! [ more ... ]
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/m3/Exception.xdc
var Exception = xdc.useModule('ti.sysbios.family.arm.m3.Exception');
module-wide config parameters
     Exception.doPrint// If true, use System_printf() to dump exception context = Bool false;
DETAILS
Do not use this module!
The functionality of the Exception module has been fully integrated into the Hwi module.
The Exception module is a basic Cortex M3 exception handler. No attempt is made to return from an exception as these are generally fatal in nature.
When used, the Exception module will override the default exception handlers provided by the Hwi module. This can be done by adding the following to your configuration script:
  Exception = xdc.useModule('ti.sysbios.family.m3.Exception');
config Exception.doPrint // module-wide
index URL

If true, use System_printf() to dump exception context

XDCscript usage meta-domain
Exception.doPrint = Bool false;
generated on Fri, 17 Jun 2011 00:23:29 GMT


module ti.sysbios.family.arm.m3.Hwi
index URL

Cortex M3 Hardware Interrupt Manager

  • C synopsis
  • Individual elements
  • DETAILS
  • INTERRUPT MASKING OPTIONS
  • INTERRUPT PRIORITIES
  • INTERRUPT VECTOR TABLES
  • RESTRICTIONS
  • XDCscript usage
  • Individual elements
The Cortex M3's Nested Vectored Interrupt Controller (NVIC) supports up to 256 interrupts/exceptions. In practice, most devices support much fewer (ie the Stellaris family of devices have only 80 total interrupts defined). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/m3/Hwi.xdc
#include <ti/sysbios/family/arm/m3/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Void | Hwi_excSetBuffers// Set the exception context and stack buffer pointers(Ptr excContextBuffer, Ptr excStackBuffer);
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with intNum(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Void | Hwi_setPriority// Set an interrupt's relative priority(UInt intNum, UInt priority);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | Hwi_CCR// NVIC Configuration Control Register (CCR) ...
typedef struct | Hwi_ExcContext// Exception Context - Register contents at the time of an exception ...
typedef Void | (*Hwi_ExceptionHookFuncPtr// Exception hook function type definition)(Hwi_ExcContext*);
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Assert_Id | Hwi_A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided;
extern const UInt | Hwi_disablePriority// The priority that BASEPRI is set to by Hwi_disable();
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Hwi_ExceptionHookFuncPtr | Hwi_excHookFunc// User Exception hook function;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id | Hwi_E_busFault// Error raised when bus fault exception occurs;
extern const Error_Id | Hwi_E_debugMon// Error raised when debugMon exception occurs;
extern const Error_Id | Hwi_E_exception// Error raised when an exception occurs;
extern const Error_Id | Hwi_E_hardFault// Error raised when hard fault exception occurs;
extern const Error_Id | Hwi_E_memFault// Error raised when memory fault exception occurs;
extern const Error_Id | Hwi_E_NMI// Error raised when NMI exception occurs;
extern const Error_Id | Hwi_E_noIsr// Error raised when an uninitialized interrupt occurs;
extern const Error_Id | Hwi_E_reserved// Error raised when reserved exception occurs;
extern const Error_Id | Hwi_E_svCall// Error raised when svCall exception occurs;
extern const Error_Id | Hwi_E_usageFault// Error raised when usage fault exception occurs;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const Int | Hwi_NUM_INTERRUPTS// The Cortex M3 NVIC supports up to 256 interrupts/exceptions;
extern const Int | Hwi_NUM_PRIORITIES// The Cortex M3 NVIC supports up to 256 interrupt priorities;
extern const UInt | Hwi_priGroup// The PRIGROUP setting. Default is 0;
DETAILS
The Cortex M3's Nested Vectored Interrupt Controller (NVIC) supports up to 256 interrupts/exceptions. In practice, most devices support much fewer (ie the Stellaris family of devices have only 80 total interrupts defined).
SYS/BIOS Interrupt IDs or interrupt numbers correspond to an interrupt's position in the interrupt vector table.
ID 0 corresponds to vector 0 which is used by the NVIC to hold the initial (reset) stack pointer value.
ID 1 corresponds to vector 1 which is the reset vector (ie _c_int00)
IDs 2-14 are hardwired to exceptions.
ID 15 is the SysTick timer interrupt.
ID's 16-255 are mapped to the NVIC's user interrupts 0-239 which are tied to platform specific interrupt sources.
The M3 Hwi module supports "zero latency" interrupts. Interrupts configured with priority greater (in priority, lower in number) than disablePriority are NOT disabled by disable.
Zero latency interrupts are not handled by the SYS/BIOS interrupt dispatcher. Instead, they are vectored to directly. As such, and because they are not masked by disable, these interrupt handlers are severely restricted in terms of the SYS/BIOS APIs they can invoke and THREAD SAFETY MUST BE CAREFULLY CONSIDERED!
Due to the M3's native automatic stacking of saved-by-caller C context on the way to an ISR, zero latency interrupt handlers are implemented using regular C functions (ie no 'interrupt' keyword is required).
Zero latency interrupts are distinguished from regular dispatched interrupts at create time by their priority being greater than disablePriority.
Note that since zero latency interrupts don't use the dispatcher, the arg parameter is not functional.
INTERRUPT MASKING OPTIONS
The NVIC interrupt controller is designed for priority based interrupts.
No support is provided for anything but MaskingOption_LOWER.
INTERRUPT PRIORITIES
In general, the NVIC supports priority values of 0 thru 255.
In practice valid priorities values are device dependent and their nesting behaviors depend on the priGroup setting.
Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see disablePriority).
See the Cortex M3 architecture reference manual for details on the behavior of interrupt priorities and their relationship to the priGroup setting.
INTERRUPT VECTOR TABLES
Stellaris devices:
By default, two vector tables are created for Stellaris devices:
A 16 entry boot vector table is placed at address 0x00000000 in FLASH.
An 80 entry vector table is placed at address 0x20000000 in RAM.
The FLASH boot vector table contains the reset vector and exception handler vectors used until the RAM based vector table is initialized.
The RAM vector table contains the 16 exception vectors as well as all the 64 user interrupt vectors.
During system startup, the NVIC Vector Table Offset Registor is intialized to point to this vector table after the table has been initialized.
Dual M3 Core ('Ducati') devices:
By default, Ducati core 0 places its runtime vector table at address 0x00000400 and core 1 places its runtime vector table at address 0x00000800.
Additionally, a boot vector table is placed at address 0x00000000 which is shared by both cores.
The boot reset vector function determines which core it is being executed on and jumps to the reset vector contained in its corresponding runtime vector table.
The generation and placement of these vector tables is made automatically when the ti.sysbios.family.arm.ducati.Core module is used.
Although STRONGLY discouraged, this default behavior can be overridden by explicitly setting the Hwi.resetVectorAddress and Hwi.vectorTableAddress config parameters.
RESTRICTIONS
When used within a dual M3 core (Ducati) arrangement, care must be taken when initializing this shared resource. The "Shared Resources" note provided in the ducati package discusses the management of the various hardware and software resources shared by the two M3 cores.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_ExceptionHookFuncPtr
index URL

Exception hook function type definition

C synopsis target-domain
typedef Void (*Hwi_ExceptionHookFuncPtr)(Hwi_ExcContext*);
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_CCR
index URL

NVIC Configuration Control Register (CCR)

C synopsis target-domain
typedef struct Hwi_CCR {
    Bits8 STKALIGN;
    // Auto stack alignment in exception
    Bits8 BFHFNMIGN;
    // All faults ignore BUS Faults
    Bits8 DIV_0_TRP;
    // Trap on divide be zero
    Bits8 UNALIGN_TRP;
    // Trap on all unaligned accesses
    Bits8 USERSETMPEND;
    // Allow user to trigger interrupts
    Bits8 NONEBASETHRDENA;
    // Allow entering thread mode anytime
} Hwi_CCR;
struct Hwi_ExcContext
index URL

Exception Context - Register contents at the time of an exception

C synopsis target-domain
typedef struct Hwi_ExcContext {
     BIOS_ThreadType threadType;
    Ptr threadHandle;
    Ptr threadStack;
    SizeT threadStackSize;
    Ptr r0;
    Ptr r1;
    Ptr r2;
    Ptr r3;
    Ptr r4;
    Ptr r5;
    Ptr r6;
    Ptr r7;
    Ptr r8;
    Ptr r9;
    Ptr r10;
    Ptr r11;
    Ptr r12;
    Ptr sp;
    Ptr lr;
    Ptr pc;
    Ptr psr;
    Ptr ICSR;
    Ptr MMFSR;
    Ptr BFSR;
    Ptr UFSR;
    Ptr HFSR;
    Ptr DFSR;
    Ptr MMAR;
    Ptr BFAR;
    Ptr AFSR;
} Hwi_ExcContext;
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_NUM_INTERRUPTS // module-wide
index URL

The Cortex M3 NVIC supports up to 256 interrupts/exceptions

C synopsis target-domain
extern const Int Hwi_NUM_INTERRUPTS;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
config Hwi_NUM_PRIORITIES // module-wide
index URL

The Cortex M3 NVIC supports up to 256 interrupt priorities

C synopsis target-domain
extern const Int Hwi_NUM_PRIORITIES;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
config Hwi_A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

C synopsis target-domain
extern const Assert_Id Hwi_A_unsupportedMaskingOption;
config Hwi_E_NMI // module-wide
index URL

Error raised when NMI exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_NMI;
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_busFault // module-wide
index URL

Error raised when bus fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_busFault;
config Hwi_E_debugMon // module-wide
index URL

Error raised when debugMon exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_debugMon;
config Hwi_E_exception // module-wide
index URL

Error raised when an exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_exception;
config Hwi_E_hardFault // module-wide
index URL

Error raised when hard fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_hardFault;
config Hwi_E_memFault // module-wide
index URL

Error raised when memory fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_memFault;
config Hwi_E_noIsr // module-wide
index URL

Error raised when an uninitialized interrupt occurs

C synopsis target-domain
extern const Error_Id Hwi_E_noIsr;
config Hwi_E_reserved // module-wide
index URL

Error raised when reserved exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_reserved;
config Hwi_E_svCall // module-wide
index URL

Error raised when svCall exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_svCall;
config Hwi_E_usageFault // module-wide
index URL

Error raised when usage fault exception occurs

C synopsis target-domain
extern const Error_Id Hwi_E_usageFault;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_disablePriority // module-wide
index URL

The priority that BASEPRI is set to by Hwi_disable()

C synopsis target-domain
extern const UInt Hwi_disablePriority;
DETAILS
All interrupts configured with equal or less priority (equal or higher number) than disablePriority are disabled by Hwi_disable. Interrupts configured with higher priority (smaller number) than disablePriority are non-maskable (ie zero-latency).
The default setting is the second highest interrupt priority defined for the device. This results in priority 0 (and all other values in the same priority group) being the non-maskable interrupt priority. All other priorities are disabled with Hwi_disable().
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_excHookFunc // module-wide
index URL

User Exception hook function

C synopsis target-domain
extern const Hwi_ExceptionHookFuncPtr Hwi_excHookFunc;
DETAILS
Called just after the exception context has been initialized.
This function will be run on the ISR stack.
This function must run to completion.
It is called without any Task or Swi scheduling protection and therefore can not call any functions that may cause a Swi or Task scheduling operation (Swi_post(), Semaphore_post(), Event_post(), etc).
config Hwi_priGroup // module-wide
index URL

The PRIGROUP setting. Default is 0

C synopsis target-domain
extern const UInt Hwi_priGroup;
DETAILS
This value will be written to the PRIGROUP field within the NVIC's Application Interrupt and Reset Control Register (Hwi_nvic.AIRCR). It defines how the 8 bit priority values are interpreted by the hardware.
Valid settings are 0-7.
The default setting of 0 causes bits 7-1 of an interrupt's priority value to be used to as a pre-emption priority, and bit 0 is used to determine which of two simultaneous interrupts with the same pre-emption priority will be serviced first.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_excSetBuffers() // module-wide
index URL

Set the exception context and stack buffer pointers

C synopsis target-domain
Void Hwi_excSetBuffers(Ptr excContextBuffer, Ptr excStackBuffer);
ARGUMENTS
excContextBuffer — Address to place ExcContext
excStackBuffer — Address to place ExcStack
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_setPriority() // module-wide
index URL

Set an interrupt's relative priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
ARGUMENTS
intNum — ID of interrupt
priority — priority
DETAILS
Valid priorities are 0 - 255. 0 is highest priority.
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // Interrupt Masking Option. Only MaskingOption_LOWER is supported
    Int priority;
    // Interrupt priority. The default is 255 which is the lowest priority
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

Interrupt Masking Option. Only MaskingOption_LOWER is supported

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
DETAILS
The NVIC interrupt controller is designed for priority based interrupts. No support is provided for anything but Hwi.MaskingOption_LOWER.
config Hwi_priority // instance
index URL

Interrupt priority. The default is 255 which is the lowest priority

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see disablePriority).
Valid priorities values are device dependent and their nesting behaviors depend on the priGroup setting.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/m3/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
module-wide constants & types
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.CCR// NVIC Configuration Control Register (CCR);
        obj.STKALIGN// Auto stack alignment in exception = Bits8 ...
        obj.BFHFNMIGN// All faults ignore BUS Faults = Bits8 ...
        obj.DIV_0_TRP// Trap on divide be zero = Bits8 ...
        obj.UNALIGN_TRP// Trap on all unaligned accesses = Bits8 ...
        obj.USERSETMPEND// Allow user to trigger interrupts = Bits8 ...
        obj.NONEBASETHRDENA// Allow entering thread mode anytime = Bits8 ...
    var obj = new Hwi.ExcContext// Exception Context - Register contents at the time of an exception;
        obj.threadType = BIOS.ThreadType ...
        obj.threadHandle = Ptr ...
        obj.threadStack = Ptr ...
        obj.threadStackSize = SizeT ...
        obj.r0 = Ptr ...
        obj.r1 = Ptr ...
        obj.r2 = Ptr ...
        obj.r3 = Ptr ...
        obj.r4 = Ptr ...
        obj.r5 = Ptr ...
        obj.r6 = Ptr ...
        obj.r7 = Ptr ...
        obj.r8 = Ptr ...
        obj.r9 = Ptr ...
        obj.r10 = Ptr ...
        obj.r11 = Ptr ...
        obj.r12 = Ptr ...
        obj.sp = Ptr ...
        obj.lr = Ptr ...
        obj.pc = Ptr ...
        obj.psr = Ptr ...
        obj.ICSR = Ptr ...
        obj.MMFSR = Ptr ...
        obj.BFSR = Ptr ...
        obj.UFSR = Ptr ...
        obj.HFSR = Ptr ...
        obj.DFSR = Ptr ...
        obj.MMAR = Ptr ...
        obj.BFAR = Ptr ...
        obj.AFSR = Ptr ...
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.vfxn = Void(*)(Void) ...
        obj.priority = UInt ...
        obj.enableInt = Bool ...
module-wide config parameters
    const Hwi.NUM_INTERRUPTS// The Cortex M3 NVIC supports up to 256 interrupts/exceptions = Int computed value;
    const Hwi.NUM_PRIORITIES// The Cortex M3 NVIC supports up to 256 interrupt priorities = Int computed value;
     Hwi.A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided = Assert.Desc {
        msg: "A_unsupportedMaskingOption: unsupported maskSetting."
    };
     Hwi.E_NMI// Error raised when NMI exception occurs = Error.Desc {
        msg: "E_NMI: %s"
    };
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.E_busFault// Error raised when bus fault exception occurs = Error.Desc {
        msg: "E_busFault: %s"
    };
     Hwi.E_debugMon// Error raised when debugMon exception occurs = Error.Desc {
        msg: "E_debugMon: %s"
    };
     Hwi.E_exception// Error raised when an exception occurs = Error.Desc {
        msg: "E_exception: id = %d, pc = %08x.\nTo see more exception detail, set ti.sysbios.family.arm.m3.Hwi.enableException = true or,\nexamine the Exception view for the ti.sysbios.family.arm.m3.Hwi module using ROV."
    };
     Hwi.E_hardFault// Error raised when hard fault exception occurs = Error.Desc {
        msg: "E_hardFault: %s"
    };
     Hwi.E_memFault// Error raised when memory fault exception occurs = Error.Desc {
        msg: "E_memFault: %s"
    };
     Hwi.E_noIsr// Error raised when an uninitialized interrupt occurs = Error.Desc {
        msg: "E_noIsr: id = %d, pc = %08x"
    };
     Hwi.E_reserved// Error raised when reserved exception occurs = Error.Desc {
        msg: "E_reserved: %s %d"
    };
     Hwi.E_svCall// Error raised when svCall exception occurs = Error.Desc {
        msg: "E_svCall: svNum = %d"
    };
     Hwi.E_usageFault// Error raised when usage fault exception occurs = Error.Desc {
        msg: "E_usageFault: %s"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.disablePriority// The priority that BASEPRI is set to by Hwi_disable() = UInt undefined;
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.excHookFunc// User Exception hook function = Void(*)(Hwi.ExcContext*) null;
     Hwi.priGroup// The PRIGROUP setting. Default is 0 = UInt 0;
     Hwi.busFaultFunc// Bus Fault Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.debugMonFunc// Debug Mon Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.enableException// Enable full exception decoding = Bool true;
     Hwi.excContextBuffer// User Exception Context Buffer Address = Ptr undefined;
     Hwi.excStackBuffer// User Exception Stack Buffer Address = Ptr undefined;
     Hwi.hardFaultFunc// Hard Fault Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.memFaultFunc// Hard Mem Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.nmiFunc// NMI Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.nullIsrFunc// Uninitialized ISR Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.nvicCCR// NVIC CCR register settings = Hwi.CCR {
        STKALIGN: 1,
        BFHFNMIGN: 0,
        DIV_0_TRP: 0,
        UNALIGN_TRP: 0,
        USERSETMPEND: 0,
        NONEBASETHRDENA: 0
    };
     Hwi.reservedFunc// Reserved Exception Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
     Hwi.resetVectorAddress// Alternate reset vector address. Default is 0x00000000 = Ptr 0x00000000;
     Hwi.svCallFunc// SVCall Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.usageFaultFunc// Usage Fault Handler. Default is set to an internal exception handler = Void(*)(Void) undefined;
     Hwi.vectorTableAddress// Location of the Interrupt Vector Table = Ptr 0x00000000;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// Interrupt Masking Option. Only MaskingOption_LOWER is supported = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
        params.priority// Interrupt priority. The default is 255 which is the lowest priority = Int 255;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.CCR
index URL

NVIC Configuration Control Register (CCR)

XDCscript usage meta-domain
var obj = new Hwi.CCR;
    obj.STKALIGN = Bits8 ...
    // Auto stack alignment in exception
    obj.BFHFNMIGN = Bits8 ...
    // All faults ignore BUS Faults
    obj.DIV_0_TRP = Bits8 ...
    // Trap on divide be zero
    obj.UNALIGN_TRP = Bits8 ...
    // Trap on all unaligned accesses
    obj.USERSETMPEND = Bits8 ...
    // Allow user to trigger interrupts
    obj.NONEBASETHRDENA = Bits8 ...
    // Allow entering thread mode anytime
C SYNOPSIS
Hwi_CCR
struct Hwi.ExcContext
index URL

Exception Context - Register contents at the time of an exception

XDCscript usage meta-domain
var obj = new Hwi.ExcContext;
    obj.threadType = BIOS.ThreadType ...
    obj.threadHandle = Ptr ...
    obj.threadStack = Ptr ...
    obj.threadStackSize = SizeT ...
    obj.r0 = Ptr ...
    obj.r1 = Ptr ...
    obj.r2 = Ptr ...
    obj.r3 = Ptr ...
    obj.r4 = Ptr ...
    obj.r5 = Ptr ...
    obj.r6 = Ptr ...
    obj.r7 = Ptr ...
    obj.r8 = Ptr ...
    obj.r9 = Ptr ...
    obj.r10 = Ptr ...
    obj.r11 = Ptr ...
    obj.r12 = Ptr ...
    obj.sp = Ptr ...
    obj.lr = Ptr ...
    obj.pc = Ptr ...
    obj.psr = Ptr ...
    obj.ICSR = Ptr ...
    obj.MMFSR = Ptr ...
    obj.BFSR = Ptr ...
    obj.UFSR = Ptr ...
    obj.HFSR = Ptr ...
    obj.DFSR = Ptr ...
    obj.MMAR = Ptr ...
    obj.BFAR = Ptr ...
    obj.AFSR = Ptr ...
C SYNOPSIS
Hwi_ExcContext
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.vfxn = Void(*)(Void) ...
    obj.priority = UInt ...
    obj.enableInt = Bool ...
config Hwi.NUM_INTERRUPTS // module-wide
index URL

The Cortex M3 NVIC supports up to 256 interrupts/exceptions

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = Int computed value;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
C SYNOPSIS
Hwi_NUM_INTERRUPTS
config Hwi.NUM_PRIORITIES // module-wide
index URL

The Cortex M3 NVIC supports up to 256 interrupt priorities

XDCscript usage meta-domain
const Hwi.NUM_PRIORITIES = Int computed value;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
C SYNOPSIS
Hwi_NUM_PRIORITIES
config Hwi.A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

XDCscript usage meta-domain
Hwi.A_unsupportedMaskingOption = Assert.Desc {
    msg: "A_unsupportedMaskingOption: unsupported maskSetting."
};
C SYNOPSIS
Hwi_A_unsupportedMaskingOption
config Hwi.E_NMI // module-wide
index URL

Error raised when NMI exception occurs

XDCscript usage meta-domain
Hwi.E_NMI = Error.Desc {
    msg: "E_NMI: %s"
};
C SYNOPSIS
Hwi_E_NMI
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_busFault // module-wide
index URL

Error raised when bus fault exception occurs

XDCscript usage meta-domain
Hwi.E_busFault = Error.Desc {
    msg: "E_busFault: %s"
};
C SYNOPSIS
Hwi_E_busFault
config Hwi.E_debugMon // module-wide
index URL

Error raised when debugMon exception occurs

XDCscript usage meta-domain
Hwi.E_debugMon = Error.Desc {
    msg: "E_debugMon: %s"
};
C SYNOPSIS
Hwi_E_debugMon
config Hwi.E_exception // module-wide
index URL

Error raised when an exception occurs

XDCscript usage meta-domain
Hwi.E_exception = Error.Desc {
    msg: "E_exception: id = %d, pc = %08x.\nTo see more exception detail, set ti.sysbios.family.arm.m3.Hwi.enableException = true or,\nexamine the Exception view for the ti.sysbios.family.arm.m3.Hwi module using ROV."
};
C SYNOPSIS
Hwi_E_exception
config Hwi.E_hardFault // module-wide
index URL

Error raised when hard fault exception occurs

XDCscript usage meta-domain
Hwi.E_hardFault = Error.Desc {
    msg: "E_hardFault: %s"
};
C SYNOPSIS
Hwi_E_hardFault
config Hwi.E_memFault // module-wide
index URL

Error raised when memory fault exception occurs

XDCscript usage meta-domain
Hwi.E_memFault = Error.Desc {
    msg: "E_memFault: %s"
};
C SYNOPSIS
Hwi_E_memFault
config Hwi.E_noIsr // module-wide
index URL

Error raised when an uninitialized interrupt occurs

XDCscript usage meta-domain
Hwi.E_noIsr = Error.Desc {
    msg: "E_noIsr: id = %d, pc = %08x"
};
C SYNOPSIS
Hwi_E_noIsr
config Hwi.E_reserved // module-wide
index URL

Error raised when reserved exception occurs

XDCscript usage meta-domain
Hwi.E_reserved = Error.Desc {
    msg: "E_reserved: %s %d"
};
C SYNOPSIS
Hwi_E_reserved
config Hwi.E_svCall // module-wide
index URL

Error raised when svCall exception occurs

XDCscript usage meta-domain
Hwi.E_svCall = Error.Desc {
    msg: "E_svCall: svNum = %d"
};
C SYNOPSIS
Hwi_E_svCall
config Hwi.E_usageFault // module-wide
index URL

Error raised when usage fault exception occurs

XDCscript usage meta-domain
Hwi.E_usageFault = Error.Desc {
    msg: "E_usageFault: %s"
};
C SYNOPSIS
Hwi_E_usageFault
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.disablePriority // module-wide
index URL

The priority that BASEPRI is set to by Hwi_disable()

XDCscript usage meta-domain
Hwi.disablePriority = UInt undefined;
DETAILS
All interrupts configured with equal or less priority (equal or higher number) than disablePriority are disabled by Hwi_disable. Interrupts configured with higher priority (smaller number) than disablePriority are non-maskable (ie zero-latency).
The default setting is the second highest interrupt priority defined for the device. This results in priority 0 (and all other values in the same priority group) being the non-maskable interrupt priority. All other priorities are disabled with Hwi_disable().
C SYNOPSIS
Hwi_disablePriority
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.excHookFunc // module-wide
index URL

User Exception hook function

XDCscript usage meta-domain
Hwi.excHookFunc = Void(*)(Hwi.ExcContext*) null;
DETAILS
Called just after the exception context has been initialized.
This function will be run on the ISR stack.
This function must run to completion.
It is called without any Task or Swi scheduling protection and therefore can not call any functions that may cause a Swi or Task scheduling operation (Swi_post(), Semaphore_post(), Event_post(), etc).
C SYNOPSIS
Hwi_excHookFunc
config Hwi.priGroup // module-wide
index URL

The PRIGROUP setting. Default is 0

XDCscript usage meta-domain
Hwi.priGroup = UInt 0;
DETAILS
This value will be written to the PRIGROUP field within the NVIC's Application Interrupt and Reset Control Register (Hwi_nvic.AIRCR). It defines how the 8 bit priority values are interpreted by the hardware.
Valid settings are 0-7.
The default setting of 0 causes bits 7-1 of an interrupt's priority value to be used to as a pre-emption priority, and bit 0 is used to determine which of two simultaneous interrupts with the same pre-emption priority will be serviced first.
C SYNOPSIS
Hwi_priGroup
metaonly config Hwi.busFaultFunc // module-wide
index URL

Bus Fault Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.busFaultFunc = Void(*)(Void) undefined;
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.debugMonFunc // module-wide
index URL

Debug Mon Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.debugMonFunc = Void(*)(Void) undefined;
metaonly config Hwi.enableException // module-wide
index URL

Enable full exception decoding

XDCscript usage meta-domain
Hwi.enableException = Bool true;
DETAILS
When this is enabled, the exception handler will fully decode an exception and dump the registers to the system console.
metaonly config Hwi.excContextBuffer // module-wide
index URL

User Exception Context Buffer Address

XDCscript usage meta-domain
Hwi.excContextBuffer = Ptr undefined;
DETAILS
By default, when an exception occurs, an ExcContext structure is allocated on the ISR stack and filled in within the exception handler.
If excContextBuffer is initialized by the user, the ExcContext structure will be placed at that address instead.
The buffer must be large enough to contain an ExcContext structure.
metaonly config Hwi.excStackBuffer // module-wide
index URL

User Exception Stack Buffer Address

XDCscript usage meta-domain
Hwi.excStackBuffer = Ptr undefined;
DETAILS
By default, when an exception occurs, a pointer to the base address of the stack being used by the thread causing the exception is placed
If excStackBuffer is initialized by the user, the stack contents of the thread causing the exception will be copied to that address instead.
The buffer must be large enough to contain the largest task stack or ISR stack defined in the application.
metaonly config Hwi.hardFaultFunc // module-wide
index URL

Hard Fault Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.hardFaultFunc = Void(*)(Void) undefined;
metaonly config Hwi.memFaultFunc // module-wide
index URL

Hard Mem Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.memFaultFunc = Void(*)(Void) undefined;
metaonly config Hwi.nmiFunc // module-wide
index URL

NMI Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.nmiFunc = Void(*)(Void) undefined;
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.nullIsrFunc // module-wide
index URL

Uninitialized ISR Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.nullIsrFunc = Void(*)(Void) undefined;
metaonly config Hwi.nvicCCR // module-wide
index URL

NVIC CCR register settings

XDCscript usage meta-domain
Hwi.nvicCCR = Hwi.CCR {
    STKALIGN: 1,
    BFHFNMIGN: 0,
    DIV_0_TRP: 0,
    UNALIGN_TRP: 0,
    USERSETMPEND: 0,
    NONEBASETHRDENA: 0
};
DETAILS
These setting are written to Hwi_nvic.CCR at startup time.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
metaonly config Hwi.reservedFunc // module-wide
index URL

Reserved Exception Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.reservedFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetFunc // module-wide
index URL

Reset Handler. Default is c_int00

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetVectorAddress // module-wide
index URL

Alternate reset vector address. Default is 0x00000000

XDCscript usage meta-domain
Hwi.resetVectorAddress = Ptr 0x00000000;
DETAILS
if initialized by the user then an additional reset vector is created and placed in the ".resetVecs" section. To place the .resetVecs section into a specific memory section, add the following command to your config script:
  Program.sectMap[".resetVecs"] = YourMemorySection;
metaonly config Hwi.svCallFunc // module-wide
index URL

SVCall Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.svCallFunc = Void(*)(Void) undefined;
metaonly config Hwi.usageFaultFunc // module-wide
index URL

Usage Fault Handler. Default is set to an internal exception handler

XDCscript usage meta-domain
Hwi.usageFaultFunc = Void(*)(Void) undefined;
metaonly config Hwi.vectorTableAddress // module-wide
index URL

Location of the Interrupt Vector Table

XDCscript usage meta-domain
Hwi.vectorTableAddress = Ptr 0x00000000;
DETAILS
This parameter allows the user to override the default placement of the interrupt vector table. The NVIC's Vector Table Offset Register (VTOR) is also programmed to this value.
By default, the interrupt vector table will be placed at address 0x00000000.
Some systems require the vector table to be placed at an address other than 0 but still need a copy of the two M3 boot vectors (SP and reset PC), located there. To achieve this, a separate parameter resetVectorAdress is provided. If the resetVectorAddress has a different value then the vectorTableAddress then a separate 2 vector table is generated and placed at that address.
The vector table must be placed at an address at or lower than 0x3FFFFC00 and must be aligned on an even 64 word boundary.
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
    // Interrupt Masking Option. Only MaskingOption_LOWER is supported
    params.priority = Int 255;
    // Interrupt priority. The default is 255 which is the lowest priority
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

Interrupt Masking Option. Only MaskingOption_LOWER is supported

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_LOWER;
DETAILS
The NVIC interrupt controller is designed for priority based interrupts. No support is provided for anything but Hwi.MaskingOption_LOWER.
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. The default is 255 which is the lowest priority

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 255;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Priority 0 is the highest priority and by default is reserved for zero latency interrupts (see disablePriority).
Valid priorities values are device dependent and their nesting behaviors depend on the priGroup setting.
See the Cortex M3 architecture reference manual for details on the meanings of these parameters.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:29 GMT


module ti.sysbios.family.arm.m3.TaskSupport
index URL

M3 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/arm/m3/TaskSupport.xdc
#include <ti/sysbios/family/arm/m3/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/m3/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.arm.m3.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 2048;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 8;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 2048;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 8;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:30 GMT


module ti.sysbios.family.arm.m3.Timer
index URL

Cortex M3 Timer Peripherals Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Cortex M3 Timer Manager utilizes the M3's internal NVIC SysTick Timer. The SysTick timer is clocked at the CPU clock rate, nominally 200MHz. The SysTick timer has only 24 bits of period resolution and is therefore limited to a maximum period of 83ms. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/m3/Timer.xdc
#include <ti/sysbios/family/arm/m3/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0x00ffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)1
#define | Timer_TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock (Int)1
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
DETAILS
The Cortex M3 Timer Manager utilizes the M3's internal NVIC SysTick Timer. The SysTick timer is clocked at the CPU clock rate, nominally 200MHz. The SysTick timer has only 24 bits of period resolution and is therefore limited to a maximum period of 83ms.

Calling Context

Function Hwi Swi Task Main Startup
getNumTimers - - - - -
getStatus - - - - -
Params_init - - - - -
construct - - - - -
create - - - - -
delete - - - - -
destruct - - - - -
getCount - - - - -
getFreq - - - - -
getPeriod - - - - -
reconfig - - - - -
setPeriod - - - - -
setPeriodMicroSecs - - - - -
start - - - - -
stop - - - - -
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0x00ffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)1
const Timer_TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

C synopsis target-domain
#define Timer_TIMER_CLOCK_DIVIDER (Int)1
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — function that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/m3/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.arm.m3.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0x00ffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 1;
    const Timer.TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock = 1;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x1;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0x00ffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 1;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
const Timer.TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

XDCscript usage meta-domain
const Timer.TIMER_CLOCK_DIVIDER = 1;
C SYNOPSIS
Timer_TIMER_CLOCK_DIVIDER
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x1;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:30 GMT


module ti.sysbios.family.arm.m3.TimestampProvider
index URL

Implements ITimestampProvider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/m3/TimestampProvider.xdc
#include <ti/sysbios/family/arm/m3/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const Bool | TimestampProvider_configTimer// ;
DETAILS
Cortex M3 TimestampProvider delegate for use with xdc.runtime.Timestamp.
The SysTick timer is used as the timestamp source.

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
config TimestampProvider_configTimer // module-wide
index URL
C synopsis target-domain
extern const Bool TimestampProvider_configTimer;
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/m3/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.m3.TimestampProvider');
module-wide config parameters
     TimestampProvider.configTimer// = Bool false;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.configTimer // module-wide
index URL
XDCscript usage meta-domain
TimestampProvider.configTimer = Bool false;
C SYNOPSIS
TimestampProvider_configTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:30 GMT


package ti.sysbios.family.arm.tms570
index URL

Contains specifications for the tms570 family of device-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/arm/tms570/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.arm.tms570 [2, 0, 0, 0] {
    module Hwi;
    // Hardware Interrupt Support Module
    module Timer;
    // Timer Peripherals Manager for arm_tms570 family
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:23:26 GMT


module ti.sysbios.family.arm.tms570.Hwi
index URL

Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides TMS570 (VIM) specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arm/tms570/Hwi.xdc
#include <ti/sysbios/family/arm/tms570/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
UInt | Hwi_disableFIQ// Disable FIQ interrupts();
UInt | Hwi_disableIRQ// Disable IRQ interrupts();
UInt | Hwi_enableFIQ// Enable FIQ interrupts();
UInt | Hwi_enableIRQ// Enable IRQ interrupts();
Hwi_Object * | Hwi_getHandle// Returns pointer to Hwi instance object(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Void | Hwi_restoreFIQ// Restore FIQ interrupts(UInt key);
Void | Hwi_restoreIRQ// Restore IRQ interrupts(UInt key);
Void | Hwi_setPriority// Set an interrupt's relative priority(UInt intNum, UInt priority);
Void | Hwi_setType// Set an interrupt's type (FIQ/IRQ)(UInt intNum, Hwi_Type type);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// The TMS570 ARM Interrupt Controller supports 64 interrupts (Int)64
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef enum | Hwi_Type// Interrupt type. IRQ or FIQ ...
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
typedef struct | Hwi_VIM// ARM Interrupt Controller ...
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Ptr | Hwi_fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace();
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides TMS570 (VIM) specific implementations of the APIs defined in IHwi.
Additional ARM device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableREQMASKSET0 | Y | Y | Y | Y | N
disableREQMASKSET1 | Y | Y | Y | Y | N
disableFIQ | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
disableIRQ | Y | Y | Y | Y | Y
enable | Y | Y | Y | N | N
enableREQMASKSET0 | Y | Y | Y | Y | N
enableREQMASKSET1 | Y | Y | Y | Y | N
enableFIQ | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
enableIRQ | Y | Y | Y | N | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreREQMASKSET0 | Y | Y | Y | Y | N
restoreREQMASKSET1 | Y | Y | Y | Y | N
restoreFIQ | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
restoreIRQ | Y | Y | Y | Y | Y
setPriority | Y | Y | Y | Y | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

The TMS570 ARM Interrupt Controller supports 64 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)64
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
enum Hwi_Type
index URL

Interrupt type. IRQ or FIQ

C synopsis target-domain
typedef enum Hwi_Type {
    Hwi_Type_IRQ,
    // IRQ interrupt
    Hwi_Type_FIQ
    // FIQ interrupt
} Hwi_Type;
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
struct Hwi_VIM
index URL

ARM Interrupt Controller

C synopsis target-domain
typedef struct Hwi_VIM {
    UInt32 PARFLG;
    // 0xFDEC VIM RAM Parity Flag Register
    UInt32 PARCTL;
    // 0xFDF0 VIM RAM Parity Control Register
    UInt32 ADDERR;
    // 0xFDF4 Address Parity Error Register
    UInt32 FBPARERR;
    // 0xFDF8 Fallback Parity Error Register
    UInt32 RESFC;
    // 0xFDFC reserved
    UInt32 IRQINDEX;
    // 0x0000 current IRQ id
    UInt32 FIQINDEX;
    // 0x0004 current FIQ id
    UInt32 RES08[2];
    // 0x0008 reserved
    UInt32 FIRQPR[4];
    // 0x0010-0x001C FIQ/IRQ Program Control Registers
    UInt32 INTREQ[4];
    // 0x0020-0x002C Pending Interrupt Request Registers
    UInt32 REQENASET[4];
    // 0x0030-0x003C Interrupt (Enable) Mask Set Registers
    UInt32 REQENACLR[4];
    // 0x0040-0x004C Interrupt (Enable) Mask Clear Registers
    UInt32 WAKEENASET[4];
    // 0x0050-0x005C Wake Mask Set Registers
    UInt32 WAKEENACLR[4];
    // 0x0060-0x006C Wake Mask Clear Registers
    UInt32 IRQVECREG;
    // 0x0070 IRQ vector
    UInt32 FIQVECREG;
    // 0x0074 FIQ vector
    UInt32 CAPEVT;
    // 0x0078 Capture Event Register
    UInt32 RES7C[1];
    // 0x007C reserved
    UInt8 CHANMAP[128];
    // 0x0080-0x00FF Channel Map (Priority) Registers
} Hwi_VIM;
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

C synopsis target-domain
extern const Ptr Hwi_fiqStack;
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableFIQ() // module-wide
index URL

Disable FIQ interrupts

C synopsis target-domain
UInt Hwi_disableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_disableIRQ() // module-wide
index URL

Disable IRQ interrupts

C synopsis target-domain
UInt Hwi_disableIRQ();
RETURNS
previous IRQ interrupt enable/disable state
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableFIQ() // module-wide
index URL

Enable FIQ interrupts

C synopsis target-domain
UInt Hwi_enableFIQ();
RETURNS
previous FIQ interrupt enable/disable state
Hwi_enableIRQ() // module-wide
index URL

Enable IRQ interrupts

C synopsis target-domain
UInt Hwi_enableIRQ();
ARGUMENTS
key — enable/disable state to restore
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_getHandle() // module-wide
index URL

Returns pointer to Hwi instance object

C synopsis target-domain
Hwi_Object *Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreFIQ() // module-wide
index URL

Restore FIQ interrupts

C synopsis target-domain
Void Hwi_restoreFIQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreIRQ() // module-wide
index URL

Restore IRQ interrupts

C synopsis target-domain
Void Hwi_restoreIRQ(UInt key);
ARGUMENTS
key — enable/disable state to restore
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_setPriority() // module-wide
index URL

Set an interrupt's relative priority

C synopsis target-domain
Void Hwi_setPriority(UInt intNum, UInt priority);
ARGUMENTS
intNum — ID of interrupt
priority — priority (0-63)
Hwi_setType() // module-wide
index URL

Set an interrupt's type (FIQ/IRQ)

C synopsis target-domain
Void Hwi_setType(UInt intNum, Hwi_Type type);
ARGUMENTS
intNum — ID of interrupt
type — type = FIQ/IRQ
DETAILS
Not an instance function so that it can be used with non-dispatched interrupts.
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits32 disableMask0;
    // disableMask0. default is derived from MaskingOption_SELF maskSetting
    Bits32 disableMask1;
    // disableMask1. default is derived from MaskingOption_SELF maskSetting
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority
    Bits32 restoreMask0;
    // restoreMask0. default is derived from MaskingOption_SELF maskSetting
    Bits32 restoreMask1;
    // restoreMask1. default is derived from MaskingOption_SELF maskSetting
     Hwi_Type type;
    // Interrupt type (IRQ/FIQ. Default is IRQ
    Bool wakeEnable;
    // wakeEnable. default is true
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask0 // instance
index URL

disableMask0. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 disableMask0;
config Hwi_disableMask1 // instance
index URL

disableMask1. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 disableMask1;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask0 // instance
index URL

restoreMask0. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 restoreMask0;
config Hwi_restoreMask1 // instance
index URL

restoreMask1. default is derived from MaskingOption_SELF maskSetting

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits32 restoreMask1;
config Hwi_type // instance
index URL

Interrupt type (IRQ/FIQ. Default is IRQ

C synopsis target-domain
struct Hwi_Params {
     ...
     Hwi_Type type;
config Hwi_wakeEnable // instance
index URL

wakeEnable. default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool wakeEnable;
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/tms570/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arm.tms570.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// The TMS570 ARM Interrupt Controller supports 64 interrupts = 64;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    values of type Hwi.Type// Interrupt type. IRQ or FIQ
        const Hwi.Type_IRQ// IRQ interrupt;
        const Hwi.Type_FIQ// FIQ interrupt;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.VIM// ARM Interrupt Controller;
        obj.PARFLG// 0xFDEC VIM RAM Parity Flag Register = UInt32 ...
        obj.PARCTL// 0xFDF0 VIM RAM Parity Control Register = UInt32 ...
        obj.ADDERR// 0xFDF4 Address Parity Error Register = UInt32 ...
        obj.FBPARERR// 0xFDF8 Fallback Parity Error Register = UInt32 ...
        obj.RESFC// 0xFDFC reserved = UInt32 ...
        obj.IRQINDEX// 0x0000 current IRQ id = UInt32 ...
        obj.FIQINDEX// 0x0004 current FIQ id = UInt32 ...
        obj.RES08// 0x0008 reserved = UInt32[2] ...
        obj.FIRQPR// 0x0010-0x001C FIQ/IRQ Program Control Registers = UInt32[4] ...
        obj.INTREQ// 0x0020-0x002C Pending Interrupt Request Registers = UInt32[4] ...
        obj.REQENASET// 0x0030-0x003C Interrupt (Enable) Mask Set Registers = UInt32[4] ...
        obj.REQENACLR// 0x0040-0x004C Interrupt (Enable) Mask Clear Registers = UInt32[4] ...
        obj.WAKEENASET// 0x0050-0x005C Wake Mask Set Registers = UInt32[4] ...
        obj.WAKEENACLR// 0x0060-0x006C Wake Mask Clear Registers = UInt32[4] ...
        obj.IRQVECREG// 0x0070 IRQ vector = UInt32 ...
        obj.FIQVECREG// 0x0074 FIQ vector = UInt32 ...
        obj.CAPEVT// 0x0078 Capture Event Register = UInt32 ...
        obj.RES7C// 0x007C reserved = UInt32[1] ...
        obj.CHANMAP// 0x0080-0x00FF Channel Map (Priority) Registers = UInt8[128] ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.fiqStack// FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace() = Ptr null;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.dataAbortFunc// Data abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.fiqFunc// FIQ interrupt handler. Default is internal FIQ dispatcher = Void(*)(Void) undefined;
     Hwi.fiqStackSection// Memory section used for FIQ stack Default is null = String null;
     Hwi.fiqStackSize// FIQ stack size in MAUs. Default is 1024 bytes = SizeT 1024;
     Hwi.irqFunc// IRQ interrupt handler. Default is internal IRQ dispatcher = Void(*)(Void) undefined;
     Hwi.prefetchAbortFunc// Prefetch abort exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.reservedFunc// Reserved exception handler. Default is self loop = Void(*)(Void) undefined;
     Hwi.resetFunc// Reset Handler. Default is c_int00 = Void(*)(Void) undefined;
     Hwi.swiFunc// SWI Handler. Default is internal SWI handler = Void(*)(Void) undefined;
     Hwi.undefinedInstFunc// Undefined instruction exception handler. Default is self loop = Void(*)(Void) undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask0// disableMask0. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.disableMask1// disableMask1. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority = Int -1;
        params.restoreMask0// restoreMask0. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.restoreMask1// restoreMask1. default is derived from MaskingOption_SELF maskSetting = Bits32 0;
        params.type// Interrupt type (IRQ/FIQ. Default is IRQ = Hwi.Type Hwi.Type_IRQ;
        params.wakeEnable// wakeEnable. default is true = Bool true;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

The TMS570 ARM Interrupt Controller supports 64 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 64;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
enum Hwi.Type
index URL

Interrupt type. IRQ or FIQ

XDCscript usage meta-domain
values of type Hwi.Type
    const Hwi.Type_IRQ;
    // IRQ interrupt
    const Hwi.Type_FIQ;
    // FIQ interrupt
C SYNOPSIS
Hwi_Type
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
struct Hwi.VIM
index URL

ARM Interrupt Controller

XDCscript usage meta-domain
var obj = new Hwi.VIM;
    obj.PARFLG = UInt32 ...
    // 0xFDEC VIM RAM Parity Flag Register
    obj.PARCTL = UInt32 ...
    // 0xFDF0 VIM RAM Parity Control Register
    obj.ADDERR = UInt32 ...
    // 0xFDF4 Address Parity Error Register
    obj.FBPARERR = UInt32 ...
    // 0xFDF8 Fallback Parity Error Register
    obj.RESFC = UInt32 ...
    // 0xFDFC reserved
    obj.IRQINDEX = UInt32 ...
    // 0x0000 current IRQ id
    obj.FIQINDEX = UInt32 ...
    // 0x0004 current FIQ id
    obj.RES08 = UInt32[2] ...
    // 0x0008 reserved
    obj.FIRQPR = UInt32[4] ...
    // 0x0010-0x001C FIQ/IRQ Program Control Registers
    obj.INTREQ = UInt32[4] ...
    // 0x0020-0x002C Pending Interrupt Request Registers
    obj.REQENASET = UInt32[4] ...
    // 0x0030-0x003C Interrupt (Enable) Mask Set Registers
    obj.REQENACLR = UInt32[4] ...
    // 0x0040-0x004C Interrupt (Enable) Mask Clear Registers
    obj.WAKEENASET = UInt32[4] ...
    // 0x0050-0x005C Wake Mask Set Registers
    obj.WAKEENACLR = UInt32[4] ...
    // 0x0060-0x006C Wake Mask Clear Registers
    obj.IRQVECREG = UInt32 ...
    // 0x0070 IRQ vector
    obj.FIQVECREG = UInt32 ...
    // 0x0074 FIQ vector
    obj.CAPEVT = UInt32 ...
    // 0x0078 Capture Event Register
    obj.RES7C = UInt32[1] ...
    // 0x007C reserved
    obj.CHANMAP = UInt8[128] ...
    // 0x0080-0x00FF Channel Map (Priority) Registers
C SYNOPSIS
Hwi_VIM
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.fiqStack // module-wide
index URL

FIQ stack pointer. Default = null. (Indicates that stack is to be created using staticPlace()

XDCscript usage meta-domain
Hwi.fiqStack = Ptr null;
C SYNOPSIS
Hwi_fiqStack
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.dataAbortFunc // module-wide
index URL

Data abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.dataAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqFunc // module-wide
index URL

FIQ interrupt handler. Default is internal FIQ dispatcher

XDCscript usage meta-domain
Hwi.fiqFunc = Void(*)(Void) undefined;
metaonly config Hwi.fiqStackSection // module-wide
index URL

Memory section used for FIQ stack Default is null

XDCscript usage meta-domain
Hwi.fiqStackSection = String null;
metaonly config Hwi.fiqStackSize // module-wide
index URL

FIQ stack size in MAUs. Default is 1024 bytes

XDCscript usage meta-domain
Hwi.fiqStackSize = SizeT 1024;
metaonly config Hwi.irqFunc // module-wide
index URL

IRQ interrupt handler. Default is internal IRQ dispatcher

XDCscript usage meta-domain
Hwi.irqFunc = Void(*)(Void) undefined;
metaonly config Hwi.prefetchAbortFunc // module-wide
index URL

Prefetch abort exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.prefetchAbortFunc = Void(*)(Void) undefined;
metaonly config Hwi.reservedFunc // module-wide
index URL

Reserved exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.reservedFunc = Void(*)(Void) undefined;
metaonly config Hwi.resetFunc // module-wide
index URL

Reset Handler. Default is c_int00

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
metaonly config Hwi.swiFunc // module-wide
index URL

SWI Handler. Default is internal SWI handler

XDCscript usage meta-domain
Hwi.swiFunc = Void(*)(Void) undefined;
metaonly config Hwi.undefinedInstFunc // module-wide
index URL

Undefined instruction exception handler. Default is self loop

XDCscript usage meta-domain
Hwi.undefinedInstFunc = Void(*)(Void) undefined;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask0 = Bits32 0;
    // disableMask0. default is derived from MaskingOption_SELF maskSetting
    params.disableMask1 = Bits32 0;
    // disableMask1. default is derived from MaskingOption_SELF maskSetting
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int -1;
    // Interrupt priority
    params.restoreMask0 = Bits32 0;
    // restoreMask0. default is derived from MaskingOption_SELF maskSetting
    params.restoreMask1 = Bits32 0;
    // restoreMask1. default is derived from MaskingOption_SELF maskSetting
    params.type = Hwi.Type Hwi.Type_IRQ;
    // Interrupt type (IRQ/FIQ. Default is IRQ
    params.wakeEnable = Bool true;
    // wakeEnable. default is true
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask0 // instance
index URL

disableMask0. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask0 = Bits32 0;
C SYNOPSIS
null
config Hwi.disableMask1 // instance
index URL

disableMask1. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask1 = Bits32 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask0 // instance
index URL

restoreMask0. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask0 = Bits32 0;
C SYNOPSIS
null
config Hwi.restoreMask1 // instance
index URL

restoreMask1. default is derived from MaskingOption_SELF maskSetting

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask1 = Bits32 0;
C SYNOPSIS
null
config Hwi.type // instance
index URL

Interrupt type (IRQ/FIQ. Default is IRQ

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.type = Hwi.Type Hwi.Type_IRQ;
C SYNOPSIS
null
config Hwi.wakeEnable // instance
index URL

wakeEnable. default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.wakeEnable = Bool true;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:26 GMT


module ti.sysbios.family.arm.tms570.Timer
index URL

Timer Peripherals Manager for arm_tms570 family

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/arm/tms570/Timer.xdc
#include <ti/sysbios/family/arm/tms570/Timer.h>
Functions
Void | Timer_ackInterrupt// clear the current timer interrupt flag(Timer_Handle handle);
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)2
Typedefs
typedef struct | Timer_Control// Timer Configuration struct ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)2
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Control
index URL

Timer Configuration struct

C synopsis target-domain
typedef struct Timer_Control {
    Bool cos;
    // 0=stop in debug mode; 1=continue in debug mode
} Timer_Control;
FIELDS
cos — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

C synopsis target-domain
extern const Error_Id Timer_E_invalidHwiMask;
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_Control controlRegInit;
    // Control register configuration. Default cos=0
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    Int intNum;
    // Hwi intNum to be used by Timer
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_controlRegInit // instance
index URL

Control register configuration. Default cos=0

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Control controlRegInit;
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_intNum // instance
index URL

Hwi intNum to be used by Timer

C synopsis target-domain
struct Timer_Params {
     ...
    Int intNum;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_ackInterrupt() // instance
index URL

clear the current timer interrupt flag

C synopsis target-domain
Void Timer_ackInterrupt(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires.
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/tms570/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.arm.tms570.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 2;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Control// Timer Configuration struct;
        obj.cos// 0=stop in debug mode; 1=continue in debug mode = Bool ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on = Error.Desc {
        msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.controlRegInit// Control register configuration. Default cos=0 = Timer.Control {
            cos: 0
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.intNum// Hwi intNum to be used by Timer = Int -1;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 2;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Control
index URL

Timer Configuration struct

XDCscript usage meta-domain
var obj = new Timer.Control;
    obj.cos = Bool ...
    // 0=stop in debug mode; 1=continue in debug mode
FIELDS
cos — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
C SYNOPSIS
Timer_Control
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

XDCscript usage meta-domain
Timer.E_invalidHwiMask = Error.Desc {
    msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
};
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
C SYNOPSIS
Timer_E_invalidHwiMask
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.controlRegInit = Timer.Control {
    // Control register configuration. Default cos=0
        cos: 0
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.intNum = Int -1;
    // Hwi intNum to be used by Timer
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.controlRegInit // instance
index URL

Control register configuration. Default cos=0

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.controlRegInit = Timer.Control {
    cos: 0
};
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.intNum // instance
index URL

Hwi intNum to be used by Timer

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.intNum = Int -1;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:26 GMT


module ti.sysbios.family.arm.tms570.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/arm/tms570/TimestampProvider.xdc
#include <ti/sysbios/family/arm/tms570/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arm/tms570/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.tms570.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:26 GMT


package ti.sysbios.family.arp32
index URL

Contains specifications for the unit tests of the SYS/BIOS kernel

XDCspec declarations sourced in ti/sysbios/family/arp32/package.xdc
package ti.sysbios.family.arp32 [2, 0, 0, 0] {
    module CTM;
    // Counter Timer Module Device Definitions
    module Hwi;
    // ARP32 Hardware Interrupt Support Module
    module Settings;
    // Device/Family-specific delegate assignment module for C64 target devices
    module TaskSupport;
    // ARP32 Task Support Module
    module Timer;
    // Timer Peripherals Manager
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.CTM
index URL

Counter Timer Module Device Definitions

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
For Ducati SYS/BIOS applications, Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18 Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22 Counters 2/3 are assigned to core 0's TimestampProvider Counters 4/5 are assigned to core 1's TimestampProvider Counters 6,7 are for application use. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arp32/CTM.xdc
#include <ti/sysbios/family/arp32/CTM.h>
Functions common to all target modules
 | CTM_Module_getMask// Returns the diagnostics mask for this module, CTM_Module_hasMask// Test whether this module has a diagnostics mask, CTM_Module_heap// The heap from which this module allocates memory, CTM_Module_id// Get this module's unique id, CTM_Module_setMask// Set the diagnostics mask for this module, CTM_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | CTM_CTM// Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400 ...
DETAILS
For Ducati SYS/BIOS applications, Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18 Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22 Counters 2/3 are assigned to core 0's TimestampProvider Counters 4/5 are assigned to core 1's TimestampProvider Counters 6,7 are for application use.
Counters 2/3 and 4/5 are in chained mode and started simultaneously by core 0 so that both cores timestamps are in sync with each other AND both chained timers have independent SHADOW registers to guarantee 64bit counter reading coherency.
struct CTM_CTM
index URL

Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400

C synopsis target-domain
typedef struct CTM_CTM {
    UInt32 CTCNTL;
    // 0x0000
    UInt32 RES_04[7];
    // 0x0004 - 0x0020
    UInt32 CTSTMCNTL;
    // 0x0020
    UInt32 CTSTMMSTID;
    // 0x0024
    UInt32 CTSTMINTVL;
    // 0x0028
    UInt32 CTSTMSEL0;
    // 0x002C
    UInt32 CTSTMSEL1;
    // 0x0030
    UInt32 RES_34[3];
    // 0x0034 - 0x0040
    UInt32 TINTVLR[8];
    // 0x0040 - 0x0060
    UInt32 RES_60[7];
    // 0x0060 - 0x007C
    UInt32 CTNUMDBG;
    // 0x007C
    UInt32 CTDBGSGL[8];
    // 0x0080 - 0x00A0
    UInt32 RES_A0[20];
    // 0x00A0 - 0x00F0
    UInt32 CTGNBL[2];
    // 0x00F0 - 0x00F8
    UInt32 CTGRST[2];
    // 0x00F8 - 0x0100
    UInt32 CTCR[32];
    // 0x0100 - 0x0180
    UInt32 CTCNTR[32];
    // 0x0180 - 0x0200
} CTM_CTM;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId CTM_Module_id();
// Get this module's unique id
Bool CTM_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle CTM_Module_heap();
// The heap from which this module allocates memory
Bool CTM_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 CTM_Module_getMask();
// Returns the diagnostics mask for this module
Void CTM_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/CTM.xdc
var CTM = xdc.useModule('ti.sysbios.family.arp32.CTM');
module-wide constants & types
    var obj = new CTM.CTM// Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400;
        obj.CTCNTL// 0x0000 = UInt32 ...
        obj.RES_04// 0x0004 - 0x0020 = UInt32[7] ...
        obj.CTSTMCNTL// 0x0020 = UInt32 ...
        obj.CTSTMMSTID// 0x0024 = UInt32 ...
        obj.CTSTMINTVL// 0x0028 = UInt32 ...
        obj.CTSTMSEL0// 0x002C = UInt32 ...
        obj.CTSTMSEL1// 0x0030 = UInt32 ...
        obj.RES_34// 0x0034 - 0x0040 = UInt32[3] ...
        obj.TINTVLR// 0x0040 - 0x0060 = UInt32[8] ...
        obj.RES_60// 0x0060 - 0x007C = UInt32[7] ...
        obj.CTNUMDBG// 0x007C = UInt32 ...
        obj.CTDBGSGL// 0x0080 - 0x00A0 = UInt32[8] ...
        obj.RES_A0// 0x00A0 - 0x00F0 = UInt32[20] ...
        obj.CTGNBL// 0x00F0 - 0x00F8 = UInt32[2] ...
        obj.CTGRST// 0x00F8 - 0x0100 = UInt32[2] ...
        obj.CTCR// 0x0100 - 0x0180 = UInt32[32] ...
        obj.CTCNTR// 0x0180 - 0x0200 = UInt32[32] ...
module-wide config parameters
     CTM.common$// Common module configuration parameters = Types.Common$ undefined;
struct CTM.CTM
index URL

Counter Timer Module Physical Base address is 0x55080400 Auto-configured virtual Base address is 0x40000400

XDCscript usage meta-domain
var obj = new CTM.CTM;
    obj.CTCNTL = UInt32 ...
    // 0x0000
    obj.RES_04 = UInt32[7] ...
    // 0x0004 - 0x0020
    obj.CTSTMCNTL = UInt32 ...
    // 0x0020
    obj.CTSTMMSTID = UInt32 ...
    // 0x0024
    obj.CTSTMINTVL = UInt32 ...
    // 0x0028
    obj.CTSTMSEL0 = UInt32 ...
    // 0x002C
    obj.CTSTMSEL1 = UInt32 ...
    // 0x0030
    obj.RES_34 = UInt32[3] ...
    // 0x0034 - 0x0040
    obj.TINTVLR = UInt32[8] ...
    // 0x0040 - 0x0060
    obj.RES_60 = UInt32[7] ...
    // 0x0060 - 0x007C
    obj.CTNUMDBG = UInt32 ...
    // 0x007C
    obj.CTDBGSGL = UInt32[8] ...
    // 0x0080 - 0x00A0
    obj.RES_A0 = UInt32[20] ...
    // 0x00A0 - 0x00F0
    obj.CTGNBL = UInt32[2] ...
    // 0x00F0 - 0x00F8
    obj.CTGRST = UInt32[2] ...
    // 0x00F8 - 0x0100
    obj.CTCR = UInt32[32] ...
    // 0x0100 - 0x0180
    obj.CTCNTR = UInt32[32] ...
    // 0x0180 - 0x0200
C SYNOPSIS
CTM_CTM
metaonly config CTM.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
CTM.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.Hwi
index URL

ARP32 Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides ARP32 family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arp32/Hwi.xdc
#include <ti/sysbios/family/arp32/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with interrupt number(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigures a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called(Bits16 mask);
Void | Hwi_selfLoop// Stub to be plugged for dsp-eve interrupts(UArg arg);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// ARP32 supports 8 interrupts (Int)8
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id | Hwi_E_notImplemented// Error raised when a Hwi function that has not been implemented for the arp32 has been called;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides ARP32 family-specific implementations of the APIs defined in IHwi.
Additional ARP32 device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | N
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableIER | Y | Y | Y | Y | N
enableInterrupt | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | N
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

ARP32 supports 8 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)8
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_notImplemented // module-wide
index URL

Error raised when a Hwi function that has not been implemented for the arp32 has been called

C synopsis target-domain
extern const Error_Id Hwi_E_notImplemented;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to enable
RETURNS
previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with interrupt number

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
RETURNS
handle associated with intNum
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous IER settings bitmask
DETAILS
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_selfLoop() // module-wide
index URL

Stub to be plugged for dsp-eve interrupts

C synopsis target-domain
Void Hwi_selfLoop(UArg arg);
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigures a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
params — pointer to Hwi parameter structure
DETAILS
This function reconfigures the dispatched interrupt so the specified function is called with the specified parameters.
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.arp32.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// ARP32 supports 8 interrupts = 8;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.fxn// "Hwi_plug'd" ISR function = Void(*)(Void) ...
        obj.enableInt = Bool ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.E_notImplemented// Error raised when a Hwi function that has not been implemented for the arp32 has been called = Error.Desc {
        msg: "E_notImplemented: Function not implemented: %s"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.resetVectorAddress// Alternate reset vector address. Default is undefined = Ptr undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

ARP32 supports 8 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 8;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    // "Hwi_plug'd" ISR function
    obj.enableInt = Bool ...
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_notImplemented // module-wide
index URL

Error raised when a Hwi function that has not been implemented for the arp32 has been called

XDCscript usage meta-domain
Hwi.E_notImplemented = Error.Desc {
    msg: "E_notImplemented: Function not implemented: %s"
};
C SYNOPSIS
Hwi_E_notImplemented
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.resetVectorAddress // module-wide
index URL

Alternate reset vector address. Default is undefined

XDCscript usage meta-domain
Hwi.resetVectorAddress = Ptr undefined;
DETAILS
if initialized by the user then an additional reset vector is created and placed in the ".resetVector" section. To place the .resetVector section into a specific memory section, add the following command to your config script:
  Program.sectMap[".resetVector"] = YourMemorySection;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.Settings

metaonly module ti.sysbios.family.arp32.Settings
index URL

Device/Family-specific delegate assignment module for C64 target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.arp32.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.TaskSupport
index URL

ARP32 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/arp32/TaskSupport.xdc
#include <ti/sysbios/family/arp32/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.arp32.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 1024;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 8;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 1024;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 8;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.Timer
index URL

Timer Peripherals Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The timers used are the two CTM timers (0 and 1) that support interrupts. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/arp32/Timer.xdc
#include <ti/sysbios/family/arp32/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Timer_Handle | Timer_getHandle// Get Handle associated with a timer id(UInt id);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)2
#define | Timer_TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock (Int)1
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
DETAILS
The timers used are the two CTM timers (0 and 1) that support interrupts.

Calling Context

Function Hwi Swi Task Main Startup
getNumTimers - - - - -
getStatus - - - - -
Params_init - - - - -
construct - - - - -
create - - - - -
delete - - - - -
destruct - - - - -
getCount - - - - -
getFreq - - - - -
getPeriod - - - - -
reconfig - - - - -
setPeriod - - - - -
setPeriodMicroSecs - - - - -
start - - - - -
stop - - - - -
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)2
DETAILS
Only 2 are available to each core.
const Timer_TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

C synopsis target-domain
#define Timer_TIMER_CLOCK_DIVIDER (Int)1
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getHandle() // module-wide
index URL

Get Handle associated with a timer id

C synopsis target-domain
Timer_Handle Timer_getHandle(UInt id);
ARGUMENTS
id — timer Id.
RETURNS
timer Handle
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — function that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.arp32.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 2;
    const Timer.TIMER_CLOCK_DIVIDER// Timer clock divider wrt cpu clock = 1;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 2;
DETAILS
Only 2 are available to each core.
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
const Timer.TIMER_CLOCK_DIVIDER
index URL

Timer clock divider wrt cpu clock

XDCscript usage meta-domain
const Timer.TIMER_CLOCK_DIVIDER = 1;
C SYNOPSIS
Timer_TIMER_CLOCK_DIVIDER
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:09 GMT


module ti.sysbios.family.arp32.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
C synopsis target-domain sourced in ti/sysbios/family/arp32/TimestampProvider.xdc
#include <ti/sysbios/family/arp32/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/arp32/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.arp32.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:09 GMT


package ti.sysbios.family.c28
index URL

Contains specifications for the C28 specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c28/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c28 [2, 0, 0, 0] {
    module Hwi;
    // C28x Hardware Interrupt Manager
    module Settings;
    // Device/Family-specific delegate assignment module for C28xx target devices
    module TaskSupport;
    // 28 Task Support Module
    module Timer;
    // Timer peripherals manager for the c28 family
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:23:03 GMT


module ti.sysbios.family.c28.Hwi
index URL

C28x Hardware Interrupt Manager

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides C28 family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c28/Hwi.xdc
#include <ti/sysbios/family/c28/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_disablePIEIER// Disable interrupts in a PIE group(UInt groupNum, Bits16 pieMask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enablePIEIER// Enable interrupts in a PIE group(UInt groupNum, Bits16 pieMask);
Hwi_Handle | Hwi_getHandle// Returns Hwi handle associated with intNum(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_plug// Plug an interrupt vector with an ISR address(UInt intNum, Hwi_PlugFuncPtr fxn);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts(Bits16 mask);
Bits16 | Hwi_restorePIEIER// Restores interrupts in a PIE group(UInt groupNum, Bits16 pieMask);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// C28 supports 32 interrupts (Int)32
#define | Hwi_NUM_INTERRUPTS_ALL// (Int)Hwi.NUM_INTERRUPTS Hwi.NUM_INTERRUPTS_PIE
#define | Hwi_NUM_INTERRUPTS_PIE// C28 supports 96 PIE interrupts (Int)96
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef Void | (*Hwi_PlugFuncPtr// Hwi plug function type definition, which doesn't take an arg)(Void);
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Assert_Id | Hwi_A_badIntNum// Assert raised when an invalid interrupt number is passed to a Hwi call;
extern const Assert_Id | Hwi_A_invalidArg// Assert raised when an invalid argument has been passed to a function;
extern const Assert_Id | Hwi_A_zeroLatencyConflict// Assert raised when there is a conflict with the zero latency IER mask;
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id | Hwi_E_unpluggedInterrupt// Error raised when an unplugged interrupt is flagged;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const Bits16 | Hwi_zeroLatencyIERMask// Zero Latency IER Mask;
DETAILS
This Hwi module provides C28 family-specific implementations of the APIs defined in IHwi.
Additional C28 device-specific APIs are also provided.
ISRs specified with Hwi_plug will not go through the dispatcher; the ISR function will be directly plugged into the vector table. Hwi_plug can be used for any ISR which does not call any SYS/BIOS APIs.
ISRs can be plugged or created statically in the configuration script or dynamically at runtime.

PIE interrupts

The peripheral interrupt expansion (PIE) block multiplexes 96 interrupts into 12 CPU interrupts. The PIE vector table includes entries for each of these 96 interrupts. The relationship between the numbers corresponding to PIE interrupts and their groups (CPU interrupt) is as follows: PIEGROUPNUM = [(PIENUM - 32) / 8] + 1

PIE MUXed Peripheral Interrupt Vector Table

The table below shows a mapping between the PIENUM (interrupt id) and the various PIE groups. INTX.Y represents the interrupt number for the PIE interrupt belonging to group X and group-specific id Y.

 | INTX.1 | INTX.2 | INTX.3 | INTX.4 | INTX.5 | INTX.6 | INTX.7 | INTX.8
INT1.Y | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39
INT2.Y | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47
INT3.Y | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55
INT4.Y | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63
INT5.Y | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71
INT6.Y | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79
INT7.Y | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87
INT8.Y | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95
INT9.Y | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103
INT10.Y | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111
INT11.Y | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119
INT12.Y | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127

PIE interrupts must clear the CPU acknowledge bit for their respective PIE block before further interrupts from that block can occur. The SYS/BIOS 6 dispatcher (used by interrupts created using create) takes care of this, however this differs from DSP/BIOS 5, in which the application is expected to acknowledge the interrupt. PIE interrupt ISRs plugged with plug(which do not use the dispatcher), as well as legacy created PIE HWI instances, must acknowledge the interrupt manually before returning from the ISR. The Hwi module supports zero latency operation. CPU interrupts classified as zero latency are not disabled by the disable call and are generally left enabled except when explicitly disabled using disableIER or disablePIEIER. Refer to zeroLatencyIERMask for using information. The following configuration code can be used to plug the function 'myHwi' into the vector table for PIE group 5, interrupt 1. Using the above table, one can see that this corresponds to interrupt ID 64:
      Program.global.hwi5 = Hwi.create(64, '&myHwi');
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
disablePIEIER | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableIER | Y | Y | Y | Y | Y
enableInterrupt | Y | Y | Y | Y | N
enablePIEIER | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
getIFR | Y | Y | Y | Y | Y
getIntrReturnAddr | Y | Y | Y | Y | Y
Params_init | Y | Y | Y | Y | N
pieEnabled | Y | Y | Y | Y | Y
plug | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
ack | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

C28 supports 32 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)32
const Hwi_NUM_INTERRUPTS_ALL
index URL
C synopsis target-domain
#define Hwi_NUM_INTERRUPTS_ALL (Int)Hwi.NUM_INTERRUPTS + Hwi.NUM_INTERRUPTS_PIE
const Hwi_NUM_INTERRUPTS_PIE
index URL

C28 supports 96 PIE interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS_PIE (Int)96
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_PlugFuncPtr
index URL

Hwi plug function type definition, which doesn't take an arg

C synopsis target-domain
typedef Void (*Hwi_PlugFuncPtr)(Void);
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_A_badIntNum // module-wide
index URL

Assert raised when an invalid interrupt number is passed to a Hwi call

C synopsis target-domain
extern const Assert_Id Hwi_A_badIntNum;
config Hwi_A_invalidArg // module-wide
index URL

Assert raised when an invalid argument has been passed to a function

C synopsis target-domain
extern const Assert_Id Hwi_A_invalidArg;
config Hwi_A_zeroLatencyConflict // module-wide
index URL

Assert raised when there is a conflict with the zero latency IER mask

C synopsis target-domain
extern const Assert_Id Hwi_A_zeroLatencyConflict;
DETAILS
This assert is raised when trying to create a Hwi with an intNum that conflicts with the supplied zero latency IER mask.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_unpluggedInterrupt // module-wide
index URL

Error raised when an unplugged interrupt is flagged

C synopsis target-domain
extern const Error_Id Hwi_E_unpluggedInterrupt;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_zeroLatencyIERMask // module-wide
index URL

Zero Latency IER Mask

C synopsis target-domain
extern const Bits16 Hwi_zeroLatencyIERMask;
DETAILS
CPU interrupts specified in this mask (which corresponds to the 16-bit IER register) will never be disabled. This means that the disable, enable, and restore calls leave the zero latency CPU interrupts enabled after being called. Zero latency operation may be used to ensure minimal interrupt-to-ISR time for non-BIOS interrupt handlers in applications that demand low latency.
It is important to note that zero latency and non-zero latency PIE interrupts may not share a common PIE group. The entire PIE group whose bit is set in the zeroLatencyIERMask will be treated as zero latency.
Enabling zero latency mode (specifying a non-zero zeroLatencyIERMask) generates alternate (and slower) code used to disable, enable and restore interrupts. This alternate code will maintain a shadow copy of interrupt state (IER register and global interrupt state). disableIER, enableIER and restoreIER will update both the IER register and its shadow. The disable call will copy the zero latency IER mask (supplied here) into the IER register. The enable call will copy the contents of the shadow IER register into the actual register. The restore call may either disable or enable the non-zero-latency interrupts.
It is important to be aware of the performance penalty associated with using zero latency interrupts before using this feature.
Example:
  var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
  Hwi.zeroLatencyIERMask = 0x0010;

  // PIE group 5 classified as zero latency
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
HWI
The behavior of clearInterrupt depends on whether the intNum is a PIE interrupt number. If so, the corresponding PIEIFR bit is cleared. If not (1 <= intNum <= 14), the corresponding IFR bit is cleared.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
HWI
The behavior of Hwi_disableInterrupt depends on whether the intNum is a PIE interrupt number. If so, the appropriate bit in its group's PIEIER register is cleared. Note that, unlike enableInterrupt, disableInterrupt does not touch IER bits when operating upon a PIE interrupt number. If intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is cleared.
The return value is a key whose value reflects the previous state of the PIEIER bit.
Hwi_disablePIEIER() // module-wide
index URL

Disable interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_disablePIEIER(UInt groupNum, Bits16 pieMask);
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER disable mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically disable PIE interrupts in a single PIE group according to supplied PIEIER bitmask
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — Bitmask of interrupts to enable
RETURNS
Previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
HWI
The behavior of enableInterrupt depends on whether the intNum is a PIE interrupt number. If so, two operations are performed. The IER bit for intNum's PIE group is set and the appropriate bit in its group's PIEIER register is also set. However, if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is set.
The return value is a key whose value reflects the previous state of the PIEIER bit. Note that the key does not reflect the IER register's previous state even if its state is modified by this call.
Hwi_enablePIEIER() // module-wide
index URL

Enable interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_enablePIEIER(UInt groupNum, Bits16 pieMask);
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER enable mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically enable PIE interrupts in a single PIE group according to supplied PIEIER bitmask
Hwi_getHandle() // module-wide
index URL

Returns Hwi handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — Interrupt number
RETURNS
Hwi handle associated with intNum
Hwi_plug() // module-wide
index URL

Plug an interrupt vector with an ISR address

C synopsis target-domain
Void Hwi_plug(UInt intNum, Hwi_PlugFuncPtr fxn);
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
DETAILS
plug hooks up the specified function as the branch target for a hardware interrupt (fielded by the CPU) at the vector address corresponding to intNum. plug does not enable the interrupt. Use Hwi_enableIER to enable specific interrupts.
This API can plug the full set of vectors supported by the PIE (0-127).
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — Bitmask of interrupts to restore
RETURNS
Previous IER settings bitmask
DETAILS
Restores maskable interrupts to the state they were in when either disableIER() or enableIER() was called.
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
HWI
The behavior of restoreInterrupt depends on whether the intNum is a PIE interrupt number. If so, the supplied key returned by an earlier call to disableInterrupt and enableInterrupt is used to restore the corresponding PIEIER bit to its state before the earlier call. However, if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the corresponding bit in the IER register is restored using the key.
Hwi_restorePIEIER() // module-wide
index URL

Restores interrupts in a PIE group

C synopsis target-domain
Bits16 Hwi_restorePIEIER(UInt groupNum, Bits16 pieMask);
ARGUMENTS
groupNum — PIE group number
pieMask — PIEIER restore mask for group
RETURNS
Previous PIEIER settings bitmask
DETAILS
Atomically restore PIE interrupts in a single PIE group according to supplied PIEIER bitmask
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableAck;
    // Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableAck // instance
index URL

Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableAck;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// C28 supports 32 interrupts = 32;
    const Hwi.NUM_INTERRUPTS_ALL// = Hwi.NUM_INTERRUPTS + Hwi.NUM_INTERRUPTS_PIE;
    const Hwi.NUM_INTERRUPTS_PIE// C28 supports 96 PIE interrupts = 96;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// Non-dispatched interrupt object;
        obj.intNum = Int ...
        obj.fxn = Void(*)(Void) ...
        obj.enableInt = Bool ...
module-wide config parameters
     Hwi.A_badIntNum// Assert raised when an invalid interrupt number is passed to a Hwi call = Assert.Desc {
        msg: "A_badIntNum: Invalid interrupt number"
    };
     Hwi.A_invalidArg// Assert raised when an invalid argument has been passed to a function = Assert.Desc {
        msg: "A_invalidArg: Invalid argument"
    };
     Hwi.A_zeroLatencyConflict// Assert raised when there is a conflict with the zero latency IER mask = Assert.Desc {
        msg: "A_zeroLatencyConflict: Conflict with zero latency IER mask"
    };
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.E_unpluggedInterrupt// Error raised when an unplugged interrupt is flagged = Error.Desc {
        msg: "E_unpluggedInterrupt: Unplugged interrupt flagged: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.zeroLatencyIERMask// Zero Latency IER Mask = Bits16 0x0;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// Non-dispatched interrupt array = Hwi.NonDispatchedInterrupt[string] undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableAck// Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher = Bool true;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

C28 supports 32 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 32;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
const Hwi.NUM_INTERRUPTS_ALL
index URL
XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS_ALL = Hwi.NUM_INTERRUPTS + Hwi.NUM_INTERRUPTS_PIE;
C SYNOPSIS
Hwi_NUM_INTERRUPTS_ALL
const Hwi.NUM_INTERRUPTS_PIE
index URL

C28 supports 96 PIE interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS_PIE = 96;
C SYNOPSIS
Hwi_NUM_INTERRUPTS_PIE
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

Non-dispatched interrupt object

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    obj.enableInt = Bool ...
FIELDS
intNum — Interrupt number
fxn — Non-dispatched interrupt service routine (ISR)
enableInt — Enable the interrupt after plugging the vector
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts
config Hwi.A_badIntNum // module-wide
index URL

Assert raised when an invalid interrupt number is passed to a Hwi call

XDCscript usage meta-domain
Hwi.A_badIntNum = Assert.Desc {
    msg: "A_badIntNum: Invalid interrupt number"
};
C SYNOPSIS
Hwi_A_badIntNum
config Hwi.A_invalidArg // module-wide
index URL

Assert raised when an invalid argument has been passed to a function

XDCscript usage meta-domain
Hwi.A_invalidArg = Assert.Desc {
    msg: "A_invalidArg: Invalid argument"
};
C SYNOPSIS
Hwi_A_invalidArg
config Hwi.A_zeroLatencyConflict // module-wide
index URL

Assert raised when there is a conflict with the zero latency IER mask

XDCscript usage meta-domain
Hwi.A_zeroLatencyConflict = Assert.Desc {
    msg: "A_zeroLatencyConflict: Conflict with zero latency IER mask"
};
DETAILS
This assert is raised when trying to create a Hwi with an intNum that conflicts with the supplied zero latency IER mask.
C SYNOPSIS
Hwi_A_zeroLatencyConflict
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_unpluggedInterrupt // module-wide
index URL

Error raised when an unplugged interrupt is flagged

XDCscript usage meta-domain
Hwi.E_unpluggedInterrupt = Error.Desc {
    msg: "E_unpluggedInterrupt: Unplugged interrupt flagged: intr# %d"
};
C SYNOPSIS
Hwi_E_unpluggedInterrupt
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.zeroLatencyIERMask // module-wide
index URL

Zero Latency IER Mask

XDCscript usage meta-domain
Hwi.zeroLatencyIERMask = Bits16 0x0;
DETAILS
CPU interrupts specified in this mask (which corresponds to the 16-bit IER register) will never be disabled. This means that the disable, enable, and restore calls leave the zero latency CPU interrupts enabled after being called. Zero latency operation may be used to ensure minimal interrupt-to-ISR time for non-BIOS interrupt handlers in applications that demand low latency.
It is important to note that zero latency and non-zero latency PIE interrupts may not share a common PIE group. The entire PIE group whose bit is set in the zeroLatencyIERMask will be treated as zero latency.
Enabling zero latency mode (specifying a non-zero zeroLatencyIERMask) generates alternate (and slower) code used to disable, enable and restore interrupts. This alternate code will maintain a shadow copy of interrupt state (IER register and global interrupt state). disableIER, enableIER and restoreIER will update both the IER register and its shadow. The disable call will copy the zero latency IER mask (supplied here) into the IER register. The enable call will copy the contents of the shadow IER register into the actual register. The restore call may either disable or enable the non-zero-latency interrupts.
It is important to be aware of the performance penalty associated with using zero latency interrupts before using this feature.
Example:
  var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
  Hwi.zeroLatencyIERMask = 0x0010;

  // PIE group 5 classified as zero latency
C SYNOPSIS
Hwi_zeroLatencyIERMask
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

Non-dispatched interrupt array

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — Interrupt number
fxn — Pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableAck = Bool true;
    // Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableAck // instance
index URL

Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt dispatcher

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableAck = Bool true;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:02 GMT


module ti.sysbios.family.c28.Settings

metaonly module ti.sysbios.family.c28.Settings
index URL

Device/Family-specific delegate assignment module for C28xx target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.c28.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:23:02 GMT


module ti.sysbios.family.c28.TaskSupport
index URL

28 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/c28/TaskSupport.xdc
#include <ti/sysbios/family/c28/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// Default Task stack size (in MAUs);
extern const Error_Id | TaskSupport_E_invalidStack// Error raised when stack is not located on PAGE 0;
extern const UInt | TaskSupport_stackAlignment// Required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

Default Task stack size (in MAUs)

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

Required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
config TaskSupport_E_invalidStack // module-wide
index URL

Error raised when stack is not located on PAGE 0

C synopsis target-domain
extern const Error_Id TaskSupport_E_invalidStack;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.c28.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// Default Task stack size (in MAUs) = SizeT 256;
    const TaskSupport.stackAlignment// Required stack alignment (in MAUs) = UInt 0;
     TaskSupport.E_invalidStack// Error raised when stack is not located on PAGE 0 = Error.Desc {
        msg: "Stack (%d) not located on PAGE 0 (stack must be located entirely below 0x10000)"
    };
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

Default Task stack size (in MAUs)

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 256;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

Required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 0;
C SYNOPSIS
TaskSupport_stackAlignment
config TaskSupport.E_invalidStack // module-wide
index URL

Error raised when stack is not located on PAGE 0

XDCscript usage meta-domain
TaskSupport.E_invalidStack = Error.Desc {
    msg: "Stack (%d) not located on PAGE 0 (stack must be located entirely below 0x10000)"
};
C SYNOPSIS
TaskSupport_E_invalidStack
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:02 GMT


module ti.sysbios.family.c28.Timer
index URL

Timer peripherals manager for the c28 family

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

28x Timers

[ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c28/Timer.xdc
#include <ti/sysbios/family/c28/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
UInt16 | Timer_getPrescale// Get timer prescale value(Timer_Handle handle);
UInt16 | Timer_getPrescaleCount// Reads timer prescale counter(Timer_Handle handle);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_setPrescale// Set timer prescale value(Timer_Handle handle, UInt16 preScalar);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Returns the number of counts that have passed(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)3
Typedefs
typedef struct | Timer_EmulationMode// Timer Emulation Mode ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Assert_Id | Timer_A_invalidHwiMask// Assert raised in Timer_create when Hwi Params does not mask 'self';
extern const Assert_Id | Timer_A_invalidRunMode// Assert raised in Timer_create if an invalid RunMode is requested;
extern const Assert_Id | Timer_A_invalidTimer// Assert raised in Timer_create when timer id specified is not supported;
extern const Assert_Id | Timer_E_cannotSupport// Assert raised when period requested is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised in Timer_create when timer requested is in use;
DETAILS

28x Timers

  • The 28x has three 32-bit timers.
  • The 28x timer counts downward from 'period' to 0; however, Timer_getCount will count upward.
  • The 28x timer supports an optional 16-bit prescalar. The prescalar effectively sets the period of the timer tick; the prescalar counts down from the prescale factor to 0, then a timer tick occurs. So, with a prescale set, the actual timer period is (prescale * period).

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
getPrescale | Y | Y | Y | Y | N
getPrescaleCount | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
setPrescale | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)3
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_EmulationMode
index URL

Timer Emulation Mode

C synopsis target-domain
typedef struct Timer_EmulationMode {
    UInt free;
    // At sw breakpoint, stop or free-run the timer
    UInt soft;
    // At sw breakpoint, hard stop or run down timer
} Timer_EmulationMode;
config Timer_A_invalidHwiMask // module-wide
index URL

Assert raised in Timer_create when Hwi Params does not mask 'self'

C synopsis target-domain
extern const Assert_Id Timer_A_invalidHwiMask;
DETAILS
This is not allowed because the timers on this platform do not inherently support one-shot mode. Instead, a stub is used to stop the timer, so it is important that the timer interrupt not occur again before the stub has stopped the timer.
config Timer_A_invalidRunMode // module-wide
index URL

Assert raised in Timer_create if an invalid RunMode is requested

C synopsis target-domain
extern const Assert_Id Timer_A_invalidRunMode;
config Timer_A_invalidTimer // module-wide
index URL

Assert raised in Timer_create when timer id specified is not supported

C synopsis target-domain
extern const Assert_Id Timer_A_invalidTimer;
config Timer_E_cannotSupport // module-wide
index URL

Assert raised when period requested is not supported

C synopsis target-domain
extern const Assert_Id Timer_E_cannotSupport;
config Timer_E_notAvailable // module-wide
index URL

Error raised in Timer_create when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_EmulationMode emulationModeInit;
    // Initial timer emulation mode. Default hard stop
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Parameters for the Hwi object created for the Timer ISR
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
    UInt16 prescale;
    // Prescale factor
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_emulationModeInit // instance
index URL

Initial timer emulation mode. Default hard stop

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_EmulationMode emulationModeInit;
DETAILS
Determines timer state at a software breakpoint. If 'free' is 1, the timer will continue to run, and the value of 'soft' doesn't matter. When 'free' is 0 and 'soft' is 1, the timer runs down to 0 then stops. When 'free' is 0 and 'soft' is 0, the timer halts.
  FREE   SOFT
  0      0      Stop after next timer decrement. (Hard stop)
  0      1      Stop after timer runs down to 0. (Soft stop)
  1      x      Continue running the timer.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Parameters for the Hwi object created for the Timer ISR

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
DETAILS
The mask setting for the Hwi object should include SELF to prevent nested timer interrupts.
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_prescale // instance
index URL

Prescale factor

C synopsis target-domain
struct Timer_Params {
     ...
    UInt16 prescale;
DETAILS
The prescale factor determines the length of a timer tick. If a prescale of 10 is specified, a timer tick will occur every 11 cycles.
If the timer is used as a counter, the prescale factor determines the period between counts. Otherwise, the prescale factor can be used to achieve longer timer periods: with a prescale specified, the actual period is (period * prescale+1).
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Returns the number of counts that have passed

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
timer counts, counting upward from 0
DETAILS
The 28x timer counts downward from the period to 0, but getCount subtracts the timer counter value from the period so that getCount counts upward instead of downward.
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_getPrescale() // instance
index URL

Get timer prescale value

C synopsis target-domain
UInt16 Timer_getPrescale(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
prescale value
DETAILS
This is not the prescale count, but the period of the prescalar.
Timer_getPrescaleCount() // instance
index URL

Reads timer prescale counter

C synopsis target-domain
UInt16 Timer_getPrescaleCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
prescale counter, counting upward from 0
DETAILS
The prescale counter counts down from prescale to 0, but getPrescaleCount subtracts the counter value from the period so that this function counts upward instead of downward.
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_setPrescale() // instance
index URL

Set timer prescale value

C synopsis target-domain
Void Timer_setPrescale(Timer_Handle handle, UInt16 preScalar);
ARGUMENTS
handle — handle of a previously-created Timer instance object
preScalar — The value to set the prescale period to.
DETAILS
This function sets the value of the prescalar, and will also reload the timer counter and prescale registers.
The prescalar decrements with each timer clock source cycle until it reaches zero, then the timer's count is decremented by one. The prescalar has the effect of setting the rate of the timer tick.
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.c28.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 3;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.EmulationMode// Timer Emulation Mode;
        obj.free// At sw breakpoint, stop or free-run the timer = UInt ...
        obj.soft// At sw breakpoint, hard stop or run down timer = UInt ...
module-wide config parameters
     Timer.A_invalidHwiMask// Assert raised in Timer_create when Hwi Params does not mask 'self' = Assert.Desc {
        msg: "A_InvalidMask: Mask in hwiParams cannot enable self"
    };
     Timer.A_invalidRunMode// Assert raised in Timer_create if an invalid RunMode is requested = Assert.Desc {
        msg: "A_invalidRunMode: Invalid RunMode"
    };
     Timer.A_invalidTimer// Assert raised in Timer_create when timer id specified is not supported = Assert.Desc {
        msg: "A_invalidTimer: Timer id must be 0-2"
    };
     Timer.E_cannotSupport// Assert raised when period requested is not supported = Assert.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period"
    };
     Timer.E_notAvailable// Error raised in Timer_create when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x7;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.emulationModeInit// Initial timer emulation mode. Default hard stop = Timer.EmulationMode {
            free: 0,
            soft: 0
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Parameters for the Hwi object created for the Timer ISR = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.prescale// Prescale factor = UInt16 0;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 3;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.EmulationMode
index URL

Timer Emulation Mode

XDCscript usage meta-domain
var obj = new Timer.EmulationMode;
    obj.free = UInt ...
    // At sw breakpoint, stop or free-run the timer
    obj.soft = UInt ...
    // At sw breakpoint, hard stop or run down timer
C SYNOPSIS
Timer_EmulationMode
config Timer.A_invalidHwiMask // module-wide
index URL

Assert raised in Timer_create when Hwi Params does not mask 'self'

XDCscript usage meta-domain
Timer.A_invalidHwiMask = Assert.Desc {
    msg: "A_InvalidMask: Mask in hwiParams cannot enable self"
};
DETAILS
This is not allowed because the timers on this platform do not inherently support one-shot mode. Instead, a stub is used to stop the timer, so it is important that the timer interrupt not occur again before the stub has stopped the timer.
C SYNOPSIS
Timer_A_invalidHwiMask
config Timer.A_invalidRunMode // module-wide
index URL

Assert raised in Timer_create if an invalid RunMode is requested

XDCscript usage meta-domain
Timer.A_invalidRunMode = Assert.Desc {
    msg: "A_invalidRunMode: Invalid RunMode"
};
C SYNOPSIS
Timer_A_invalidRunMode
config Timer.A_invalidTimer // module-wide
index URL

Assert raised in Timer_create when timer id specified is not supported

XDCscript usage meta-domain
Timer.A_invalidTimer = Assert.Desc {
    msg: "A_invalidTimer: Timer id must be 0-2"
};
C SYNOPSIS
Timer_A_invalidTimer
config Timer.E_cannotSupport // module-wide
index URL

Assert raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Assert.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_notAvailable // module-wide
index URL

Error raised in Timer_create when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x7;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.emulationModeInit = Timer.EmulationMode {
    // Initial timer emulation mode. Default hard stop
        free: 0,
        soft: 0
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Parameters for the Hwi object created for the Timer ISR
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.prescale = UInt16 0;
    // Prescale factor
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.emulationModeInit // instance
index URL

Initial timer emulation mode. Default hard stop

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.emulationModeInit = Timer.EmulationMode {
    free: 0,
    soft: 0
};
DETAILS
Determines timer state at a software breakpoint. If 'free' is 1, the timer will continue to run, and the value of 'soft' doesn't matter. When 'free' is 0 and 'soft' is 1, the timer runs down to 0 then stops. When 'free' is 0 and 'soft' is 0, the timer halts.
  FREE   SOFT
  0      0      Stop after next timer decrement. (Hard stop)
  0      1      Stop after timer runs down to 0. (Soft stop)
  1      x      Continue running the timer.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Parameters for the Hwi object created for the Timer ISR

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
DETAILS
The mask setting for the Hwi object should include SELF to prevent nested timer interrupts.
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.prescale // instance
index URL

Prescale factor

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.prescale = UInt16 0;
DETAILS
The prescale factor determines the length of a timer tick. If a prescale of 10 is specified, a timer tick will occur every 11 cycles.
If the timer is used as a counter, the prescale factor determines the period between counts. Otherwise, the prescale factor can be used to achieve longer timer periods: with a prescale specified, the actual period is (period * prescale+1).
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:03 GMT


module ti.sysbios.family.c28.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c28/TimestampProvider.xdc
#include <ti/sysbios/family/c28/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id: 0, 1, or 2;
extern const Bool | TimestampProvider_useClockTimer// Whether the TimestampProvider should share the Clock's timer;
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id: 0, 1, or 2

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
DETAILS
This parameter is ignored if useClockTimer is true.
config TimestampProvider_useClockTimer // module-wide
index URL

Whether the TimestampProvider should share the Clock's timer

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
This parameter overrides the timeId setting.
Sharing the Clock timer leaves more timers available for other uses, but makes the Timestamp APIs less efficient. If the Clock timer is used, the timestamp is calculated as: (Clock ticks) x (tick period) + (current timer count) This also limits the maximum value of the timestamp: max timestamp = 2^32 x (Clock tick period)
Using a dedicated timer allows for a full 64-bit timestamp and does not require any multiplication to retrieve the value.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.c28.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id: 0, 1, or 2 = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Whether the TimestampProvider should share the Clock's timer = Bool false;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id: 0, 1, or 2

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
DETAILS
This parameter is ignored if useClockTimer is true.
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Whether the TimestampProvider should share the Clock's timer

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool false;
DETAILS
This parameter overrides the timeId setting.
Sharing the Clock timer leaves more timers available for other uses, but makes the Timestamp APIs less efficient. If the Clock timer is used, the timestamp is calculated as: (Clock ticks) x (tick period) + (current timer count) This also limits the maximum value of the timestamp: max timestamp = 2^32 x (Clock tick period)
Using a dedicated timer allows for a full 64-bit timestamp and does not require any multiplication to retrieve the value.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:03 GMT


package ti.sysbios.family.c28.f28m35x
index URL

Contains specifications for the C28 specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c28/f28m35x/package.xdc
package ti.sysbios.family.c28.f28m35x [2, 0, 0, 0] {
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:23:03 GMT


module ti.sysbios.family.c28.f28m35x.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c28/f28m35x/TimestampProvider.xdc
#include <ti/sysbios/family/c28/f28m35x/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c28/f28m35x/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.c28.f28m35x.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:03 GMT


package ti.sysbios.family.c62
index URL

Contains specifications for C6x specific SYS/BIOS functions

The link below provides SYS/BIOS C6x register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/c62/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c62 [2, 0, 0, 0] {
    module TaskSupport;
    // C64 Task Support Module
}
DETAILS
The link below provides SYS/BIOS C6x register usage information:
SYS/BIOS C6x Register Usage
generated on Fri, 17 Jun 2011 00:22:42 GMT


module ti.sysbios.family.c62.TaskSupport
index URL

C64 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/c62/TaskSupport.xdc
#include <ti/sysbios/family/c62/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c62/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.c62.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 2048;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 8;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 2048;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 8;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:42 GMT


package ti.sysbios.family.c64
index URL

Contains specifications for the C64 specific SYS/BIOS functions

The link below provides SYS/BIOS C6x register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/c64/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64 [2, 0, 0, 0] {
    module Hwi;
    // C64x Hardware Interrupt Support Module
    module Settings;
    // Device/Family-specific delegate assignment module for C64 target devices
    module Timer;
    // Timer Peripherals Manager for c64 family
    module TimestampProvider;
}
DETAILS
The link below provides SYS/BIOS C6x register usage information:
SYS/BIOS C6x Register Usage
generated on Fri, 17 Jun 2011 00:22:45 GMT


module ti.sysbios.family.c64.Hwi
index URL

C64x Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides C64 family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64/Hwi.xdc
#include <ti/sysbios/family/c64/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Void | Hwi_eventMap// Map Event to Interrupt(Int intNum, Int eventId);
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with interrupt number(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigures a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called(Bits16 mask);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// C64 supports 16 interrupts (Int)16
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides C64 family-specific implementations of the APIs defined in IHwi.
Additional C64 device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | N
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableIER | Y | Y | Y | Y | N
enableInterrupt | Y | Y | Y | Y | N
eventMap | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | N
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

C64 supports 16 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)16
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to enable
RETURNS
previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_eventMap() // module-wide
index URL

Map Event to Interrupt

C synopsis target-domain
Void Hwi_eventMap(Int intNum, Int eventId);
ARGUMENTS
intNum — interrupt number
eventId — event ID
DETAILS
Function maps a GEM event to an interrupt number so that the event is the interrupt source of the vector.
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with interrupt number

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
RETURNS
handle associated with intNum
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous IER settings bitmask
DETAILS
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigures a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
params — pointer to Hwi parameter structure
DETAILS
This function reconfigures the dispatched interrupt so the specified function is called with the specified parameters.
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c64/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.c64.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// C64 supports 16 interrupts = 16;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.fxn// "Hwi_plug'd" ISR function = Void(*)(Void) ...
        obj.enableInt = Bool ...
        obj.eventId = Int ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.resetVectorAddress// Alternate reset vector address. Default is undefined = Ptr undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.eventMapMeta// Maps GEM Event to interrupt number statically(Int intNum, Int eventId) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

C64 supports 16 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 16;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    // "Hwi_plug'd" ISR function
    obj.enableInt = Bool ...
    obj.eventId = Int ...
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.resetVectorAddress // module-wide
index URL

Alternate reset vector address. Default is undefined

XDCscript usage meta-domain
Hwi.resetVectorAddress = Ptr undefined;
DETAILS
if initialized by the user then an additional reset vector is created and placed in the ".resetVector" section. To place the .resetVector section into a specific memory section, add the following command to your config script:
  Program.sectMap[".resetVector"] = YourMemorySection;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.eventMapMeta() // module-wide
index URL

Maps GEM Event to interrupt number statically

XDCscript usage meta-domain
Hwi.eventMapMeta(Int intNum, Int eventId) returns Void
ARGUMENTS
intNum — interrupt number
eventId — event Id
DETAILS
Function maps an event to an interrupt number so that the event is the interrupt source of the vector.
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:22:44 GMT


module ti.sysbios.family.c64.Settings

metaonly module ti.sysbios.family.c64.Settings
index URL

Device/Family-specific delegate assignment module for C64 target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/c64/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.c64.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:22:44 GMT


module ti.sysbios.family.c64.Timer
index URL

Timer Peripherals Manager for c64 family

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c64/Timer.xdc
#include <ti/sysbios/family/c64/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)3
Typedefs
typedef struct | Timer_Control// Timer Configuration struct ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)3
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Control
index URL

Timer Configuration struct

C synopsis target-domain
typedef struct Timer_Control {
    UInt func;
    // 0=TOUT is GPIO; 1=TOUT is timer output
    UInt invout;
    // 0=TOUT is TSTAT TOUT; 1=TOUT is ~TSTAT
    UInt datout;
    // 0=DATOUT drives TOUT; 1=TSTAT drives TOUT
    UInt pwid;
    // 0=width is ONE; 1=width is TWO
    UInt cp;
    // 0=pulse mode; 1=clock mode
    UInt spnd;
    // 0=timer continues; 1=timer stops;
} Timer_Control;
FIELDS
func — When true TOUT is timer output. When false TOUT pin is a general-purpose output pin.
invout — When true inverted TSTAT drives TOUT. When false non inverted TSTAT drives TOUT.
dataout — When true TSTAT is driven on TOUT after inversion by INVOUT. When false DATOUT is driven on TOUT.
pwid — When true TSTAT goes inactive two clock cycles after timer counter equald timer period value. When false TSTAT goes inactive one clock cycle after the timer counter value equals the timer period value.
cp — When true TSTAT has a 50% duty cycle. When false TSTAT is active for one CPU cycle after timer reaches the timer period. PWID determines the width.
spnd — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

C synopsis target-domain
extern const Error_Id Timer_E_invalidHwiMask;
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_Control controlRegInit;
    // Control register configuration. Default spnd=1
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    Int intNum;
    // Hwi intNum to be used by Timer
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_controlRegInit // instance
index URL

Control register configuration. Default spnd=1

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Control controlRegInit;
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_intNum // instance
index URL

Hwi intNum to be used by Timer

C synopsis target-domain
struct Timer_Params {
     ...
    Int intNum;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires.
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c64/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.c64.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 3;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Control// Timer Configuration struct;
        obj.func// 0=TOUT is GPIO; 1=TOUT is timer output = UInt ...
        obj.invout// 0=TOUT is TSTAT TOUT; 1=TOUT is ~TSTAT = UInt ...
        obj.datout// 0=DATOUT drives TOUT; 1=TSTAT drives TOUT = UInt ...
        obj.pwid// 0=width is ONE; 1=width is TWO = UInt ...
        obj.cp// 0=pulse mode; 1=clock mode = UInt ...
        obj.spnd// 0=timer continues; 1=timer stops; = UInt ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on = Error.Desc {
        msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x7;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.controlRegInit// Control register configuration. Default spnd=1 = Timer.Control {
            func: 0,
            invout: 0,
            datout: 0,
            pwid: 0,
            cp: 0,
            spnd: 1
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.intNum// Hwi intNum to be used by Timer = Int -1;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 3;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Control
index URL

Timer Configuration struct

XDCscript usage meta-domain
var obj = new Timer.Control;
    obj.func = UInt ...
    // 0=TOUT is GPIO; 1=TOUT is timer output
    obj.invout = UInt ...
    // 0=TOUT is TSTAT TOUT; 1=TOUT is ~TSTAT
    obj.datout = UInt ...
    // 0=DATOUT drives TOUT; 1=TSTAT drives TOUT
    obj.pwid = UInt ...
    // 0=width is ONE; 1=width is TWO
    obj.cp = UInt ...
    // 0=pulse mode; 1=clock mode
    obj.spnd = UInt ...
    // 0=timer continues; 1=timer stops;
FIELDS
func — When true TOUT is timer output. When false TOUT pin is a general-purpose output pin.
invout — When true inverted TSTAT drives TOUT. When false non inverted TSTAT drives TOUT.
dataout — When true TSTAT is driven on TOUT after inversion by INVOUT. When false DATOUT is driven on TOUT.
pwid — When true TSTAT goes inactive two clock cycles after timer counter equald timer period value. When false TSTAT goes inactive one clock cycle after the timer counter value equals the timer period value.
cp — When true TSTAT has a 50% duty cycle. When false TSTAT is active for one CPU cycle after timer reaches the timer period. PWID determines the width.
spnd — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
C SYNOPSIS
Timer_Control
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

XDCscript usage meta-domain
Timer.E_invalidHwiMask = Error.Desc {
    msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
};
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
C SYNOPSIS
Timer_E_invalidHwiMask
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x7;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.controlRegInit = Timer.Control {
    // Control register configuration. Default spnd=1
        func: 0,
        invout: 0,
        datout: 0,
        pwid: 0,
        cp: 0,
        spnd: 1
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.intNum = Int -1;
    // Hwi intNum to be used by Timer
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.controlRegInit // instance
index URL

Control register configuration. Default spnd=1

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.controlRegInit = Timer.Control {
    func: 0,
    invout: 0,
    datout: 0,
    pwid: 0,
    cp: 0,
    spnd: 1
};
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.intNum // instance
index URL

Hwi intNum to be used by Timer

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.intNum = Int -1;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:45 GMT


module ti.sysbios.family.c64.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c64/TimestampProvider.xdc
#include <ti/sysbios/family/c64/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id. Max id value is 2;
extern const Bool | TimestampProvider_useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module;
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
config TimestampProvider_useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
This parameter overrides the timeId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.c64.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id. Max id value is 2 = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module = Bool false;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool false;
DETAILS
This parameter overrides the timeId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:45 GMT


package ti.sysbios.family.c64p
index URL

Contains specifications for the C64P specific SYS/BIOS functions

The link below provides SYS/BIOS C6x register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/c64p/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p [2, 0, 0, 0] {
    module Cache;
    // Cache Module
    module EventCombiner;
    // Event Combiner Manager module
    module Exception;
    // Exception Module
    module Hwi;
    // C64+ Hardware Interrupt Support Module
    module MemoryProtect;
    // MemoryProtect Module
    module Settings;
    // Device/Family-specific delegate assignment module for C64P and C674 target devices
    module TimestampProvider;
}
DETAILS
The link below provides SYS/BIOS C6x register usage information:
SYS/BIOS C6x Register Usage
generated on Fri, 17 Jun 2011 00:22:49 GMT


module ti.sysbios.family.c64p.Cache
index URL

Cache Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Cache module provides C64+ family-specific implementations of the APIs defined in ICache. It also provides additional C64+ specific cache functions. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/Cache.xdc
#include <ti/sysbios/family/c64p/Cache.h>
Functions
Cache_Mar | Cache_getMar// Get the value of the MAR register defined for the specified base address(Ptr baseAddr);
Cache_Mode | Cache_getMode// Get mode of a cache(Bits16 type);
Void | Cache_getSize// Get sizes of all caches(Cache_Size *size);
Void | Cache_invL1pAll// Invalidate all of L1 Program cache();
Void | Cache_setMar// Set the MAR register(s) that corresponds to the specified address range(Ptr baseAddr, SizeT byteSize, Cache_Mar value);
Cache_Mode | Cache_setMode// Set mode of a cache(Bits16 type, Cache_Mode mode);
Void | Cache_setSize// Set sizes of all caches(Cache_Size *size);
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Cache_L1Size// Level 1 cache size type definition. Can be used for both L1D & L1P ...
typedef enum | Cache_L2Size// Level 2 cache size type definition ...
typedef enum | Cache_Mar// MAR register setting type definition ...
typedef enum | Cache_Mode// Lists of cache modes for L1/L2 caches ...
typedef struct | Cache_Size// Structure for specifying all cache sizes ...
typedef enum | Cache_Type// Lists of bitmask cache types ...
Constants
extern const UInt | Cache_EMIFA_BASE// EMIF A base register address;
extern const UInt * | Cache_EMIFA_CFG// EMIF A configuration address;
extern const UInt | Cache_EMIFA_LENGTH// EMIF A address space length;
extern const UInt | Cache_EMIFB_BASE// EMIF B base register address;
extern const UInt * | Cache_EMIFB_CFG// EMIF B configuration address;
extern const UInt | Cache_EMIFB_LENGTH// EMIF B address space length;
extern const UInt | Cache_EMIFC_BASE// EMIF C base register address;
extern const UInt * | Cache_EMIFC_CFG// EMIF C configuration address;
extern const UInt | Cache_EMIFC_LENGTH// EMIF C address space length;
extern const Cache_Size | Cache_initSize// Cache sizes;
extern const UInt32 | Cache_MAR0_31// MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF);
extern const UInt32 | Cache_MAR128_159// MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF);
extern const UInt32 | Cache_MAR160_191// MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF);
extern const UInt32 | Cache_MAR192_223// MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF);
extern const UInt32 | Cache_MAR224_255// MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF);
extern const UInt32 | Cache_MAR32_63// MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF);
extern const UInt32 | Cache_MAR64_95// MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF);
extern const UInt32 | Cache_MAR96_127// MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF);
DETAILS
This Cache module provides C64+ family-specific implementations of the APIs defined in ICache. It also provides additional C64+ specific cache functions.
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
getMar* | Y | Y | Y | Y | Y
getMode* | Y | Y | Y | Y | Y
getSize* | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
invL1pAll* | Y | Y | Y | Y | Y
setMar* | Y | Y | Y | Y | Y
setMode* | Y | Y | Y | Y | Y
setSize* | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbAll* | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
wbInvAll | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
  • *: These APIs are intended to be made at initialization time, but are not restricted to this.
enum Cache_L1Size
index URL

Level 1 cache size type definition. Can be used for both L1D & L1P

C synopsis target-domain
typedef enum Cache_L1Size {
    Cache_L1Size_0K,
    // Amount of cache is 0K, Amount of SRAM is 32K
    Cache_L1Size_4K,
    // Amount of cache is 4K, Amount of SRAM is 28K
    Cache_L1Size_8K,
    // Amount of cache is 8K, Amount of SRAM is 24K
    Cache_L1Size_16K,
    // Amount of cache is 16K, Amount of SRAM is 16K
    Cache_L1Size_32K
    // Amount of cache is 32K, Amount of SRAM is 0K
} Cache_L1Size;
enum Cache_L2Size
index URL

Level 2 cache size type definition

C synopsis target-domain
typedef enum Cache_L2Size {
    Cache_L2Size_0K,
    // L2 is all SRAM
    Cache_L2Size_32K,
    // Amount of cache is 32K
    Cache_L2Size_64K,
    // Amount of cache is 64K
    Cache_L2Size_128K,
    // Amount of cache is 128K
    Cache_L2Size_256K,
    // Amount of cache is 256K
    Cache_L2Size_512K,
    // Amount of cache is 512K
    Cache_L2Size_1024K
    // Amount of cache is 1024K
} Cache_L2Size;
enum Cache_Mar
index URL

MAR register setting type definition

C synopsis target-domain
typedef enum Cache_Mar {
    Cache_Mar_DISABLE,
    // The Permit Copy bit of MAR register is disabled
    Cache_Mar_ENABLE
    // The Permit Copy bit of MAR register is enabled
} Cache_Mar;
enum Cache_Mode
index URL

Lists of cache modes for L1/L2 caches

C synopsis target-domain
typedef enum Cache_Mode {
    Cache_Mode_FREEZE,
    // No new cache lines are allocated
    Cache_Mode_BYPASS,
    // All access result in long-distance access
    Cache_Mode_NORMAL
    // Normal operation of cache
} Cache_Mode;
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
struct Cache_Size
index URL

Structure for specifying all cache sizes

C synopsis target-domain
typedef struct Cache_Size {
     Cache_L1Size l1pSize;
    // L1 Program cache size
     Cache_L1Size l1dSize;
    // L1 Data data size
     Cache_L2Size l2Size;
    // L2 cache size
} Cache_Size;
config Cache_EMIFA_BASE // module-wide
index URL

EMIF A base register address

C synopsis target-domain
extern const UInt Cache_EMIFA_BASE;
DETAILS
By default, this is set to the emif A base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFA_CFG // module-wide
index URL

EMIF A configuration address

C synopsis target-domain
extern const UInt *Cache_EMIFA_CFG;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFA_LENGTH // module-wide
index URL

EMIF A address space length

C synopsis target-domain
extern const UInt Cache_EMIFA_LENGTH;
config Cache_EMIFB_BASE // module-wide
index URL

EMIF B base register address

C synopsis target-domain
extern const UInt Cache_EMIFB_BASE;
DETAILS
By default, this is set to the emif B base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFB_CFG // module-wide
index URL

EMIF B configuration address

C synopsis target-domain
extern const UInt *Cache_EMIFB_CFG;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFB_LENGTH // module-wide
index URL

EMIF B address space length

C synopsis target-domain
extern const UInt Cache_EMIFB_LENGTH;
config Cache_EMIFC_BASE // module-wide
index URL

EMIF C base register address

C synopsis target-domain
extern const UInt Cache_EMIFC_BASE;
DETAILS
By default, this is set to the emif C base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFC_CFG // module-wide
index URL

EMIF C configuration address

C synopsis target-domain
extern const UInt *Cache_EMIFC_CFG;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
config Cache_EMIFC_LENGTH // module-wide
index URL

EMIF C address space length

C synopsis target-domain
extern const UInt Cache_EMIFC_LENGTH;
config Cache_MAR0_31 // module-wide
index URL

MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR0_31;
DETAILS
If undefined by the user, this parameter is configured to match the memory map of the platform. Each memory region defined in the platform will have all of its corresponding MAR bits set.
To override the default behavior you must initialize this parameter in your configuration script:
  // disable MAR bits for addresses 0x00000000 to 0x1FFFFFFF
  Cache.MAR0_31 = 0x00000000;
config Cache_MAR128_159 // module-wide
index URL

MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR128_159;
DETAILS
see MAR0_31 for more info
config Cache_MAR160_191 // module-wide
index URL

MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR160_191;
DETAILS
see MAR0_31 for more info
config Cache_MAR192_223 // module-wide
index URL

MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR192_223;
DETAILS
see MAR0_31 for more info
config Cache_MAR224_255 // module-wide
index URL

MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR224_255;
DETAILS
see MAR0_31 for more info
config Cache_MAR32_63 // module-wide
index URL

MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR32_63;
DETAILS
see MAR0_31 for more info
config Cache_MAR64_95 // module-wide
index URL

MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR64_95;
DETAILS
see MAR0_31 for more info
config Cache_MAR96_127 // module-wide
index URL

MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF)

C synopsis target-domain
extern const UInt32 Cache_MAR96_127;
DETAILS
see MAR0_31 for more info
config Cache_initSize // module-wide
index URL

Cache sizes

C synopsis target-domain
extern const Cache_Size Cache_initSize;
DETAILS
When this parameter is set in user's cfg script, user set cache sizes override those specified by the Cache module or the platform.
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
DETAILS
Disabling of L2 cache is currently not supported.
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_getMar() // module-wide
index URL

Get the value of the MAR register defined for the specified base address

C synopsis target-domain
Cache_Mar Cache_getMar(Ptr baseAddr);
ARGUMENTS
baseAddr — address for which MAR is requested
RETURNS
value of MAR register associated with specified address
Cache_getMode() // module-wide
index URL

Get mode of a cache

C synopsis target-domain
Cache_Mode Cache_getMode(Bits16 type);
ARGUMENTS
type — bit mask of cache type
RETURNS
mode of specified level of cache
Cache_getSize() // module-wide
index URL

Get sizes of all caches

C synopsis target-domain
Void Cache_getSize(Cache_Size *size);
ARGUMENTS
size — pointer to structure of type Cache_Size
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_invL1pAll() // module-wide
index URL

Invalidate all of L1 Program cache

C synopsis target-domain
Void Cache_invL1pAll();
DETAILS
Performs a global invalidate of L1P cache. Polls the L1P invalidate register until done.
Cache_setMar() // module-wide
index URL

Set the MAR register(s) that corresponds to the specified address range

C synopsis target-domain
Void Cache_setMar(Ptr baseAddr, SizeT byteSize, Cache_Mar value);
ARGUMENTS
baseAddr — start address for which to set MAR
byteSize — size (in bytes) of memory block
value — enum of type Cache_Mar
Cache_setMode() // module-wide
index URL

Set mode of a cache

C synopsis target-domain
Cache_Mode Cache_setMode(Bits16 type, Cache_Mode mode);
ARGUMENTS
type — bit mask of cache type
mode — mode of cache
RETURNS
previous mode of cache
Cache_setSize() // module-wide
index URL

Set sizes of all caches

C synopsis target-domain
Void Cache_setSize(Cache_Size *size);
ARGUMENTS
size — pointer to structure of type Cache_Size
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Perform a global write back. There is no effect on L1P cache. All cache lines are left valid in L1D cache and the data in L1D cache is written back to L2 or external. All cache lines are left valid in L2 cache and the data in L2 cache is written back to external.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Performs a global write back and invalidate. All cache lines are invalidated in L1P cache. All cache lines are written back to L2 or external and then invalidated in L1D cache. All cache lines are written back to external and then invalidated in L2 cache.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.c64p.Cache');
module-wide constants & types
    values of type Cache.L1Size// Level 1 cache size type definition. Can be used for both L1D & L1P
        const Cache.L1Size_0K// Amount of cache is 0K, Amount of SRAM is 32K;
        const Cache.L1Size_4K// Amount of cache is 4K, Amount of SRAM is 28K;
        const Cache.L1Size_8K// Amount of cache is 8K, Amount of SRAM is 24K;
        const Cache.L1Size_16K// Amount of cache is 16K, Amount of SRAM is 16K;
        const Cache.L1Size_32K// Amount of cache is 32K, Amount of SRAM is 0K;
    values of type Cache.L2Size// Level 2 cache size type definition
        const Cache.L2Size_0K// L2 is all SRAM;
        const Cache.L2Size_32K// Amount of cache is 32K;
        const Cache.L2Size_64K// Amount of cache is 64K;
        const Cache.L2Size_128K// Amount of cache is 128K;
        const Cache.L2Size_256K// Amount of cache is 256K;
        const Cache.L2Size_512K// Amount of cache is 512K;
        const Cache.L2Size_1024K// Amount of cache is 1024K;
    values of type Cache.Mar// MAR register setting type definition
        const Cache.Mar_DISABLE// The Permit Copy bit of MAR register is disabled;
        const Cache.Mar_ENABLE// The Permit Copy bit of MAR register is enabled;
    values of type Cache.Mode// Lists of cache modes for L1/L2 caches
        const Cache.Mode_FREEZE// No new cache lines are allocated;
        const Cache.Mode_BYPASS// All access result in long-distance access;
        const Cache.Mode_NORMAL// Normal operation of cache;
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
    var obj = new Cache.Size// Structure for specifying all cache sizes;
        obj.l1pSize// L1 Program cache size = Cache.L1Size ...
        obj.l1dSize// L1 Data data size = Cache.L1Size ...
        obj.l2Size// L2 cache size = Cache.L2Size ...
module-wide config parameters
     Cache.EMIFA_BASE// EMIF A base register address = UInt undefined;
     Cache.EMIFA_CFG// EMIF A configuration address = UInt* undefined;
     Cache.EMIFA_LENGTH// EMIF A address space length = UInt undefined;
     Cache.EMIFB_BASE// EMIF B base register address = UInt undefined;
     Cache.EMIFB_CFG// EMIF B configuration address = UInt* undefined;
     Cache.EMIFB_LENGTH// EMIF B address space length = UInt undefined;
     Cache.EMIFC_BASE// EMIF C base register address = UInt undefined;
     Cache.EMIFC_CFG// EMIF C configuration address = UInt* undefined;
     Cache.EMIFC_LENGTH// EMIF C address space length = UInt undefined;
     Cache.MAR0_31// MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF) = UInt32 undefined;
     Cache.MAR128_159// MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF) = UInt32 undefined;
     Cache.MAR160_191// MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF) = UInt32 undefined;
     Cache.MAR192_223// MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF) = UInt32 undefined;
     Cache.MAR224_255// MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF) = UInt32 undefined;
     Cache.MAR32_63// MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF) = UInt32 undefined;
     Cache.MAR64_95// MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF) = UInt32 undefined;
     Cache.MAR96_127// MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF) = UInt32 undefined;
     Cache.initSize// Cache sizes = Cache.Size {
        l1pSize: Cache.L1Size_32K,
        l1dSize: Cache.L1Size_32K,
        l2Size: Cache.L2Size_0K
    };
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
enum Cache.L1Size
index URL

Level 1 cache size type definition. Can be used for both L1D & L1P

XDCscript usage meta-domain
values of type Cache.L1Size
    const Cache.L1Size_0K;
    // Amount of cache is 0K, Amount of SRAM is 32K
    const Cache.L1Size_4K;
    // Amount of cache is 4K, Amount of SRAM is 28K
    const Cache.L1Size_8K;
    // Amount of cache is 8K, Amount of SRAM is 24K
    const Cache.L1Size_16K;
    // Amount of cache is 16K, Amount of SRAM is 16K
    const Cache.L1Size_32K;
    // Amount of cache is 32K, Amount of SRAM is 0K
C SYNOPSIS
Cache_L1Size
enum Cache.L2Size
index URL

Level 2 cache size type definition

XDCscript usage meta-domain
values of type Cache.L2Size
    const Cache.L2Size_0K;
    // L2 is all SRAM
    const Cache.L2Size_32K;
    // Amount of cache is 32K
    const Cache.L2Size_64K;
    // Amount of cache is 64K
    const Cache.L2Size_128K;
    // Amount of cache is 128K
    const Cache.L2Size_256K;
    // Amount of cache is 256K
    const Cache.L2Size_512K;
    // Amount of cache is 512K
    const Cache.L2Size_1024K;
    // Amount of cache is 1024K
C SYNOPSIS
Cache_L2Size
enum Cache.Mar
index URL

MAR register setting type definition

XDCscript usage meta-domain
values of type Cache.Mar
    const Cache.Mar_DISABLE;
    // The Permit Copy bit of MAR register is disabled
    const Cache.Mar_ENABLE;
    // The Permit Copy bit of MAR register is enabled
C SYNOPSIS
Cache_Mar
enum Cache.Mode
index URL

Lists of cache modes for L1/L2 caches

XDCscript usage meta-domain
values of type Cache.Mode
    const Cache.Mode_FREEZE;
    // No new cache lines are allocated
    const Cache.Mode_BYPASS;
    // All access result in long-distance access
    const Cache.Mode_NORMAL;
    // Normal operation of cache
C SYNOPSIS
Cache_Mode
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
struct Cache.Size
index URL

Structure for specifying all cache sizes

XDCscript usage meta-domain
var obj = new Cache.Size;
    obj.l1pSize = Cache.L1Size ...
    // L1 Program cache size
    obj.l1dSize = Cache.L1Size ...
    // L1 Data data size
    obj.l2Size = Cache.L2Size ...
    // L2 cache size
C SYNOPSIS
Cache_Size
config Cache.EMIFA_BASE // module-wide
index URL

EMIF A base register address

XDCscript usage meta-domain
Cache.EMIFA_BASE = UInt undefined;
DETAILS
By default, this is set to the emif A base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFA_BASE
config Cache.EMIFA_CFG // module-wide
index URL

EMIF A configuration address

XDCscript usage meta-domain
Cache.EMIFA_CFG = UInt* undefined;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFA_CFG
config Cache.EMIFA_LENGTH // module-wide
index URL

EMIF A address space length

XDCscript usage meta-domain
Cache.EMIFA_LENGTH = UInt undefined;
C SYNOPSIS
Cache_EMIFA_LENGTH
config Cache.EMIFB_BASE // module-wide
index URL

EMIF B base register address

XDCscript usage meta-domain
Cache.EMIFB_BASE = UInt undefined;
DETAILS
By default, this is set to the emif B base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFB_BASE
config Cache.EMIFB_CFG // module-wide
index URL

EMIF B configuration address

XDCscript usage meta-domain
Cache.EMIFB_CFG = UInt* undefined;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFB_CFG
config Cache.EMIFB_LENGTH // module-wide
index URL

EMIF B address space length

XDCscript usage meta-domain
Cache.EMIFB_LENGTH = UInt undefined;
C SYNOPSIS
Cache_EMIFB_LENGTH
config Cache.EMIFC_BASE // module-wide
index URL

EMIF C base register address

XDCscript usage meta-domain
Cache.EMIFC_BASE = UInt undefined;
DETAILS
By default, this is set to the emif C base register physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFC_BASE
config Cache.EMIFC_CFG // module-wide
index URL

EMIF C configuration address

XDCscript usage meta-domain
Cache.EMIFC_CFG = UInt* undefined;
DETAILS
By default, this is set to the physical address. On devices with a MMU where the physical address is mapped to a virtual address, the virtual address must be specified here.
C SYNOPSIS
Cache_EMIFC_CFG
config Cache.EMIFC_LENGTH // module-wide
index URL

EMIF C address space length

XDCscript usage meta-domain
Cache.EMIFC_LENGTH = UInt undefined;
C SYNOPSIS
Cache_EMIFC_LENGTH
config Cache.MAR0_31 // module-wide
index URL

MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF)

XDCscript usage meta-domain
Cache.MAR0_31 = UInt32 undefined;
DETAILS
If undefined by the user, this parameter is configured to match the memory map of the platform. Each memory region defined in the platform will have all of its corresponding MAR bits set.
To override the default behavior you must initialize this parameter in your configuration script:
  // disable MAR bits for addresses 0x00000000 to 0x1FFFFFFF
  Cache.MAR0_31 = 0x00000000;
C SYNOPSIS
Cache_MAR0_31
config Cache.MAR128_159 // module-wide
index URL

MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF)

XDCscript usage meta-domain
Cache.MAR128_159 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR128_159
config Cache.MAR160_191 // module-wide
index URL

MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF)

XDCscript usage meta-domain
Cache.MAR160_191 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR160_191
config Cache.MAR192_223 // module-wide
index URL

MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF)

XDCscript usage meta-domain
Cache.MAR192_223 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR192_223
config Cache.MAR224_255 // module-wide
index URL

MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF)

XDCscript usage meta-domain
Cache.MAR224_255 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR224_255
config Cache.MAR32_63 // module-wide
index URL

MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF)

XDCscript usage meta-domain
Cache.MAR32_63 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR32_63
config Cache.MAR64_95 // module-wide
index URL

MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF)

XDCscript usage meta-domain
Cache.MAR64_95 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR64_95
config Cache.MAR96_127 // module-wide
index URL

MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF)

XDCscript usage meta-domain
Cache.MAR96_127 = UInt32 undefined;
DETAILS
see MAR0_31 for more info
C SYNOPSIS
Cache_MAR96_127
config Cache.initSize // module-wide
index URL

Cache sizes

XDCscript usage meta-domain
Cache.initSize = Cache.Size {
    l1pSize: Cache.L1Size_32K,
    l1dSize: Cache.L1Size_32K,
    l2Size: Cache.L2Size_0K
};
DETAILS
When this parameter is set in user's cfg script, user set cache sizes override those specified by the Cache module or the platform.
C SYNOPSIS
Cache_initSize
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:48 GMT


module ti.sysbios.family.c64p.EventCombiner
index URL

Event Combiner Manager module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The event combiner allows the user to combine up to 32 system events into a single combined event. The events 0, 1, 2, and 3 are the events associated with the event combiner. Using the EventCombiner module along with the Hwi module, allows the user to route a combined event to any of the 12 maskable CPU interrupts available on GEM. The EventCombiner supports up to 128 system events. Users can specify a function and an argument for each system event and can choose to enable whichever system events they want. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/EventCombiner.xdc
#include <ti/sysbios/family/c64p/EventCombiner.h>
Functions
Void | EventCombiner_disableEvent// Disables 'evt' from contributing to its combined event group(UInt evt);
Void | EventCombiner_dispatch// The Event Combiner dispatcher(UInt evt);
Void | EventCombiner_dispatchPlug// Used to configure a dispatcher entry for 'evt'(UInt evt, EventCombiner_FuncPtr fxn, UArg arg, Bool unmask);
Void | EventCombiner_enableEvent// Enables 'evt' to contribute to its combined event group(UInt evt);
Functions common to all target modules
 | EventCombiner_Module_getMask// Returns the diagnostics mask for this module, EventCombiner_Module_hasMask// Test whether this module has a diagnostics mask, EventCombiner_Module_heap// The heap from which this module allocates memory, EventCombiner_Module_id// Get this module's unique id, EventCombiner_Module_setMask// Set the diagnostics mask for this module, EventCombiner_Module_startupDone// Test if this module has completed startup
Defines
#define | EventCombiner_NUM_EVENTS// C64+ supports 128 events (Int)128
Typedefs
typedef Void | (*EventCombiner_FuncPtr// Event Combiner dispatcher function type definition)(UArg);
Constants
extern const Bits32 | EventCombiner_EVTMASK// Holds the initialization values for the C64+ EVTMASK registers (0-3)[4];
extern const Error_Id | EventCombiner_E_unpluggedEvent// Error raised when an unplug Event is executed;
DETAILS
The event combiner allows the user to combine up to 32 system events into a single combined event. The events 0, 1, 2, and 3 are the events associated with the event combiner. Using the EventCombiner module along with the Hwi module, allows the user to route a combined event to any of the 12 maskable CPU interrupts available on GEM. The EventCombiner supports up to 128 system events. Users can specify a function and an argument for each system event and can choose to enable whichever system events they want.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disableEvent | Y | Y | Y | Y | Y
dispatch | Y | N | N | N | N
dispatchPlug | Y | Y | Y | Y | Y
enableEvent | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. EventCombiner_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. EventCombiner_Module_startupDone() returns FALSE).
const EventCombiner_NUM_EVENTS
index URL

C64+ supports 128 events

C synopsis target-domain
#define EventCombiner_NUM_EVENTS (Int)128
typedef EventCombiner_FuncPtr
index URL

Event Combiner dispatcher function type definition

C synopsis target-domain
typedef Void (*EventCombiner_FuncPtr)(UArg);
config EventCombiner_EVTMASK // module-wide
index URL

Holds the initialization values for the C64+ EVTMASK registers (0-3)

C synopsis target-domain
extern const Bits32 EventCombiner_EVTMASK[4];
DETAILS
It is assigned values based on the 'unmask' member of the 'events' configuration array. It can also be assigned manually in the program configuration script.
config EventCombiner_E_unpluggedEvent // module-wide
index URL

Error raised when an unplug Event is executed

C synopsis target-domain
extern const Error_Id EventCombiner_E_unpluggedEvent;
EventCombiner_disableEvent() // module-wide
index URL

Disables 'evt' from contributing to its combined event group

C synopsis target-domain
Void EventCombiner_disableEvent(UInt evt);
DETAILS
It accomplishes this by setting the corresponding bit in the C64+ EVTMASK array to 1 (to mask it).
EventCombiner_dispatch() // module-wide
index URL

The Event Combiner dispatcher

C synopsis target-domain
Void EventCombiner_dispatch(UInt evt);
DETAILS
It is mostly used internally, but can be used directly by the user.
EventCombiner_dispatchPlug() // module-wide
index URL

Used to configure a dispatcher entry for 'evt'

C synopsis target-domain
Void EventCombiner_dispatchPlug(UInt evt, EventCombiner_FuncPtr fxn, UArg arg, Bool unmask);
DETAILS
The parameters correspond to the same ones for static configuration in EventObj. dispatchPlug does not map the corresponding combined event group to an Hwi interrupt - such an action needs to be performed either using the event combiner configuration or using the Hwi module.
EventCombiner_enableEvent() // module-wide
index URL

Enables 'evt' to contribute to its combined event group

C synopsis target-domain
Void EventCombiner_enableEvent(UInt evt);
DETAILS
It accomplishes this by setting the corresponding bit in the C64+ EVTMASK array to 0 (to unmask it).
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId EventCombiner_Module_id();
// Get this module's unique id
Bool EventCombiner_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle EventCombiner_Module_heap();
// The heap from which this module allocates memory
Bool EventCombiner_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 EventCombiner_Module_getMask();
// Returns the diagnostics mask for this module
Void EventCombiner_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/EventCombiner.xdc
var EventCombiner = xdc.useModule('ti.sysbios.family.c64p.EventCombiner');
module-wide constants & types
    const EventCombiner.NUM_EVENTS// C64+ supports 128 events = 128;
    var obj = new EventCombiner.EventObj// Event Configuration Object;
        obj.unmask = Bool ...
        obj.fxn = Void(*)(UArg) ...
        obj.arg = UArg ...
module-wide config parameters
     EventCombiner.EVTMASK// Holds the initialization values for the C64+ EVTMASK registers (0-3) = Bits32[4] undefined;
     EventCombiner.E_unpluggedEvent// Error raised when an unplug Event is executed = Error.Desc {
        msg: "E_unpluggedEvent: Event# %d is unplugged"
    };
     EventCombiner.common$// Common module configuration parameters = Types.Common$ undefined;
     EventCombiner.eventGroupHwiNum// Configures the mapping of a C64+ combined event group to an interrupt = Int[4] undefined;
     EventCombiner.events// For holding configuration values for all C64+ events = EventCombiner.EventObj[EventCombiner.NUM_EVENTS] undefined;
module-wide functions
     EventCombiner.dispatchEventGroup// Configuration method for assigning the eventGroupHwiNum array(UInt evt, UInt hwiVec) returns Void
const EventCombiner.NUM_EVENTS
index URL

C64+ supports 128 events

XDCscript usage meta-domain
const EventCombiner.NUM_EVENTS = 128;
C SYNOPSIS
EventCombiner_NUM_EVENTS
metaonly struct EventCombiner.EventObj
index URL

Event Configuration Object

XDCscript usage meta-domain
var obj = new EventCombiner.EventObj;
    obj.unmask = Bool ...
    obj.fxn = Void(*)(UArg) ...
    obj.arg = UArg ...
DETAILS
unmask - Boolean value that specifies if an event should be unmasked in the C64+ EVTMASK registers. fxn - function to call when this event occurs. arg - arg to fxn.
config EventCombiner.EVTMASK // module-wide
index URL

Holds the initialization values for the C64+ EVTMASK registers (0-3)

XDCscript usage meta-domain
EventCombiner.EVTMASK = Bits32[4] undefined;
DETAILS
It is assigned values based on the 'unmask' member of the 'events' configuration array. It can also be assigned manually in the program configuration script.
C SYNOPSIS
EventCombiner_EVTMASK
config EventCombiner.E_unpluggedEvent // module-wide
index URL

Error raised when an unplug Event is executed

XDCscript usage meta-domain
EventCombiner.E_unpluggedEvent = Error.Desc {
    msg: "E_unpluggedEvent: Event# %d is unplugged"
};
C SYNOPSIS
EventCombiner_E_unpluggedEvent
metaonly config EventCombiner.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
EventCombiner.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config EventCombiner.eventGroupHwiNum // module-wide
index URL

Configures the mapping of a C64+ combined event group to an interrupt

XDCscript usage meta-domain
EventCombiner.eventGroupHwiNum = Int[4] undefined;
DETAILS
There is one element per combined event group (0-3).
metaonly config EventCombiner.events // module-wide
index URL

For holding configuration values for all C64+ events

XDCscript usage meta-domain
EventCombiner.events = EventCombiner.EventObj[EventCombiner.NUM_EVENTS] undefined;
DETAILS
Array elements can be configured in the program configuration script.
metaonly EventCombiner.dispatchEventGroup() // module-wide
index URL

Configuration method for assigning the eventGroupHwiNum array

XDCscript usage meta-domain
EventCombiner.dispatchEventGroup(UInt evt, UInt hwiVec) returns Void
DETAILS
It accomplishes the same thing as directly setting eventGroupHwiNum[0-3].
generated on Fri, 17 Jun 2011 00:22:48 GMT


module ti.sysbios.family.c64p.Exception
index URL

Exception Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Exception module is a basic C64+ exception handler. It is generally considered to be a program endpoint, since an exception usually indicates something fatal to the system. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/Exception.xdc
#include <ti/sysbios/family/c64p/Exception.h>
Functions
Void | Exception_clearLastStatus// clearLastStatus - Clears internal Status structure();
Void | Exception_evtEvtClear// evtEvtClear - Clear a C64+ event from the EVTFLAG register(UInt event);
Void | Exception_evtExpMaskEnable// evtExpMaskEnable - Enable a C64+ event to generate an exception(UInt event);
Void | Exception_getLastStatus// getLastStatus - Fills passed status structure with the Status fields that were recorded by the last invocation of dispatch(), handler() and internalHandler(). The 'excContext' is valid only in the scope of sub-handler "Hook" functions, since the Context structure is stored on the Hwi ISR stack(Exception_Status *status);
Exception_FuncPtr | Exception_setReturnPtr// setReturnPtr - Configures dispatch() to "return" (branch) to the passed ptr(Exception_FuncPtr ptr);
Functions common to all target modules
 | Exception_Module_getMask// Returns the diagnostics mask for this module, Exception_Module_hasMask// Test whether this module has a diagnostics mask, Exception_Module_heap// The heap from which this module allocates memory, Exception_Module_id// Get this module's unique id, Exception_Module_setMask// Set the diagnostics mask for this module, Exception_Module_startupDone// Test if this module has completed startup
Defines
#define | Exception_ECREXF// EXCEP flag (Bits32)Exception.EFREXF
#define | Exception_ECRIXF// Internal exception flag (Bits32)Exception.EFRIXF
#define | Exception_ECRNXF// NMI exception flag (Bits32)Exception.EFRNXF
#define | Exception_ECRSXF// Software exception flag (Bits32)Exception.EFRSXF
#define | Exception_EFREXF// EXCEP flag (Bits32)0x40000000
#define | Exception_EFRIXF// Internal exception flag (Bits32)0x00000002
#define | Exception_EFRNXF// NMI exception flag (Bits32)0x80000000
#define | Exception_EFRSXF// Software exception flag (Bits32)0x00000001
#define | Exception_IERREPX// Execute packet exception (Bits32)0x00000004
#define | Exception_IERRFPX// Fetch packet exception (Bits32)0x00000002
#define | Exception_IERRIFX// Instruction fetch exception (Bits32)0x00000001
#define | Exception_IERRLBX// Loop buffer exception (Bits32)0x00000080
#define | Exception_IERRMSX// Missed stall exception (Bits32)0x00000100
#define | Exception_IERROPX// Opcode exception (Bits32)0x00000008
#define | Exception_IERRPRX// Priviledge exception (Bits32)0x00000040
#define | Exception_IERRRAX// Resource access exeption (Bits32)0x00000020
#define | Exception_IERRRCX// Resource conflict exception (Bits32)0x00000010
#define | Exception_TSRCXM// Current execution mode bits (Bits32)0x000000C0
#define | Exception_TSRCXMSHIFT// TSR.CXM left shift value (Bits32)6
#define | Exception_TSRCXMSV// Supervisor mode (Bits32)0x00000000
#define | Exception_TSRCXMUS// User mode (Bits32)0x00000040
#define | Exception_TSREXC// Exception processing (Bits32)0x00000400
#define | Exception_TSRGEE// Global exception enable (Bits32)0x00000004
#define | Exception_TSRXEN// External exception enable (Bits32)0x00000008
Typedefs
typedef Void | (*Exception_FuncPtr// FuncPtr - Hook function type definition)(Void);
typedef struct | Exception_Status// Status - structure filled by getLastStatus() ...
Constants
extern const Bool | Exception_enableExternalMPC// enableExternalMPC - Enable handling of Memory Protection Controller (MPC) exceptions;
extern const Bool | Exception_enablePrint// enablePrint - Enable print of exception details and Register values;
extern const Exception_FuncPtr | Exception_exceptionHook// exceptionHook - Function hook called by handler This is called anytime an exception occurs;
extern const Exception_FuncPtr | Exception_externalHook// externalHook - Function hook called by externalHandler Function is only called when an external exception has occurred;
extern const Error_Id | Exception_E_exceptionMax// ;
extern const Error_Id | Exception_E_exceptionMin// Error raised when abortFlag is true;
extern const Exception_FuncPtr | Exception_internalHook// internalHook - Function hook called by internalHandler Function is only called when an internal exception has occurred;
extern const Exception_FuncPtr | Exception_nmiHook// nmiHook - Function hook called by nmiHandler Function is called for legacy NMI exceptions only;
extern const Exception_FuncPtr | Exception_returnHook// returnHook - Function hook called at the end of Exception_dispatch;
DETAILS
The Exception module is a basic C64+ exception handler. It is generally considered to be a program endpoint, since an exception usually indicates something fatal to the system.
During initialization, the Exception module sets TSR.GEE and TSR.XEN to enable the CPU to recognize the EXECP input.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearLastStatus | Y | Y | Y | Y | Y
evtEvtClear | Y | Y | Y | Y | Y
evtExpMaskEnable | Y | Y | Y | Y | Y
getLastStatus | Y | Y | Y | Y | Y
setReturnPtr | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
const Exception_ECREXF
index URL

EXCEP flag

C synopsis target-domain
#define Exception_ECREXF (Bits32)Exception.EFREXF
const Exception_ECRIXF
index URL

Internal exception flag

C synopsis target-domain
#define Exception_ECRIXF (Bits32)Exception.EFRIXF
const Exception_ECRNXF
index URL

NMI exception flag

C synopsis target-domain
#define Exception_ECRNXF (Bits32)Exception.EFRNXF
const Exception_ECRSXF
index URL

Software exception flag

C synopsis target-domain
#define Exception_ECRSXF (Bits32)Exception.EFRSXF
const Exception_EFREXF
index URL

EXCEP flag

C synopsis target-domain
#define Exception_EFREXF (Bits32)0x40000000
const Exception_EFRIXF
index URL

Internal exception flag

C synopsis target-domain
#define Exception_EFRIXF (Bits32)0x00000002
const Exception_EFRNXF
index URL

NMI exception flag

C synopsis target-domain
#define Exception_EFRNXF (Bits32)0x80000000
const Exception_EFRSXF
index URL

Software exception flag

C synopsis target-domain
#define Exception_EFRSXF (Bits32)0x00000001
const Exception_IERREPX
index URL

Execute packet exception

C synopsis target-domain
#define Exception_IERREPX (Bits32)0x00000004
const Exception_IERRFPX
index URL

Fetch packet exception

C synopsis target-domain
#define Exception_IERRFPX (Bits32)0x00000002
const Exception_IERRIFX
index URL

Instruction fetch exception

C synopsis target-domain
#define Exception_IERRIFX (Bits32)0x00000001
const Exception_IERRLBX
index URL

Loop buffer exception

C synopsis target-domain
#define Exception_IERRLBX (Bits32)0x00000080
const Exception_IERRMSX
index URL

Missed stall exception

C synopsis target-domain
#define Exception_IERRMSX (Bits32)0x00000100
const Exception_IERROPX
index URL

Opcode exception

C synopsis target-domain
#define Exception_IERROPX (Bits32)0x00000008
const Exception_IERRPRX
index URL

Priviledge exception

C synopsis target-domain
#define Exception_IERRPRX (Bits32)0x00000040
const Exception_IERRRAX
index URL

Resource access exeption

C synopsis target-domain
#define Exception_IERRRAX (Bits32)0x00000020
const Exception_IERRRCX
index URL

Resource conflict exception

C synopsis target-domain
#define Exception_IERRRCX (Bits32)0x00000010
const Exception_TSRCXM
index URL

Current execution mode bits

C synopsis target-domain
#define Exception_TSRCXM (Bits32)0x000000C0
const Exception_TSRCXMSHIFT
index URL

TSR.CXM left shift value

C synopsis target-domain
#define Exception_TSRCXMSHIFT (Bits32)6
const Exception_TSRCXMSV
index URL

Supervisor mode

C synopsis target-domain
#define Exception_TSRCXMSV (Bits32)0x00000000
const Exception_TSRCXMUS
index URL

User mode

C synopsis target-domain
#define Exception_TSRCXMUS (Bits32)0x00000040
const Exception_TSREXC
index URL

Exception processing

C synopsis target-domain
#define Exception_TSREXC (Bits32)0x00000400
const Exception_TSRGEE
index URL

Global exception enable

C synopsis target-domain
#define Exception_TSRGEE (Bits32)0x00000004
const Exception_TSRXEN
index URL

External exception enable

C synopsis target-domain
#define Exception_TSRXEN (Bits32)0x00000008
typedef Exception_FuncPtr
index URL

FuncPtr - Hook function type definition

C synopsis target-domain
typedef Void (*Exception_FuncPtr)(Void);
struct Exception_Status
index URL

Status - structure filled by getLastStatus()

C synopsis target-domain
typedef struct Exception_Status {
    Bits32 efr;
    // EFR register
    Bits32 nrp;
    // NRP register
    Bits32 ntsr;
    // NTSR register
    Bits32 ierr;
    // IERR register
     Exception_Context *excContext;
    // Context structure filled by last exception
} Exception_Status;
config Exception_E_exceptionMax // module-wide
index URL
C synopsis target-domain
extern const Error_Id Exception_E_exceptionMax;
config Exception_E_exceptionMin // module-wide
index URL

Error raised when abortFlag is true

C synopsis target-domain
extern const Error_Id Exception_E_exceptionMin;
config Exception_enableExternalMPC // module-wide
index URL

enableExternalMPC - Enable handling of Memory Protection Controller (MPC) exceptions

C synopsis target-domain
extern const Bool Exception_enableExternalMPC;
config Exception_enablePrint // module-wide
index URL

enablePrint - Enable print of exception details and Register values

C synopsis target-domain
extern const Bool Exception_enablePrint;
config Exception_exceptionHook // module-wide
index URL

exceptionHook - Function hook called by handler This is called anytime an exception occurs

C synopsis target-domain
extern const Exception_FuncPtr Exception_exceptionHook;
config Exception_externalHook // module-wide
index URL

externalHook - Function hook called by externalHandler Function is only called when an external exception has occurred

C synopsis target-domain
extern const Exception_FuncPtr Exception_externalHook;
config Exception_internalHook // module-wide
index URL

internalHook - Function hook called by internalHandler Function is only called when an internal exception has occurred

C synopsis target-domain
extern const Exception_FuncPtr Exception_internalHook;
config Exception_nmiHook // module-wide
index URL

nmiHook - Function hook called by nmiHandler Function is called for legacy NMI exceptions only

C synopsis target-domain
extern const Exception_FuncPtr Exception_nmiHook;
config Exception_returnHook // module-wide
index URL

returnHook - Function hook called at the end of Exception_dispatch

C synopsis target-domain
extern const Exception_FuncPtr Exception_returnHook;
Exception_clearLastStatus() // module-wide
index URL

clearLastStatus - Clears internal Status structure

C synopsis target-domain
Void Exception_clearLastStatus();
Exception_evtEvtClear() // module-wide
index URL

evtEvtClear - Clear a C64+ event from the EVTFLAG register

C synopsis target-domain
Void Exception_evtEvtClear(UInt event);
Exception_evtExpMaskEnable() // module-wide
index URL

evtExpMaskEnable - Enable a C64+ event to generate an exception

C synopsis target-domain
Void Exception_evtExpMaskEnable(UInt event);
Exception_getLastStatus() // module-wide
index URL

getLastStatus - Fills passed status structure with the Status fields that were recorded by the last invocation of dispatch(), handler() and internalHandler(). The 'excContext' is valid only in the scope of sub-handler "Hook" functions, since the Context structure is stored on the Hwi ISR stack

C synopsis target-domain
Void Exception_getLastStatus(Exception_Status *status);
Exception_setReturnPtr() // module-wide
index URL

setReturnPtr - Configures dispatch() to "return" (branch) to the passed ptr

C synopsis target-domain
Exception_FuncPtr Exception_setReturnPtr(Exception_FuncPtr ptr);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Exception_Module_id();
// Get this module's unique id
Bool Exception_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Exception_Module_heap();
// The heap from which this module allocates memory
Bool Exception_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Exception_Module_getMask();
// Returns the diagnostics mask for this module
Void Exception_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/Exception.xdc
var Exception = xdc.useModule('ti.sysbios.family.c64p.Exception');
module-wide constants & types
    const Exception.ECREXF// EXCEP flag = Exception.EFREXF;
    const Exception.ECRIXF// Internal exception flag = Exception.EFRIXF;
    const Exception.ECRNXF// NMI exception flag = Exception.EFRNXF;
    const Exception.ECRSXF// Software exception flag = Exception.EFRSXF;
    const Exception.EFREXF// EXCEP flag = 0x40000000;
    const Exception.EFRIXF// Internal exception flag = 0x00000002;
    const Exception.EFRNXF// NMI exception flag = 0x80000000;
    const Exception.EFRSXF// Software exception flag = 0x00000001;
    const Exception.IERREPX// Execute packet exception = 0x00000004;
    const Exception.IERRFPX// Fetch packet exception = 0x00000002;
    const Exception.IERRIFX// Instruction fetch exception = 0x00000001;
    const Exception.IERRLBX// Loop buffer exception = 0x00000080;
    const Exception.IERRMSX// Missed stall exception = 0x00000100;
    const Exception.IERROPX// Opcode exception = 0x00000008;
    const Exception.IERRPRX// Priviledge exception = 0x00000040;
    const Exception.IERRRAX// Resource access exeption = 0x00000020;
    const Exception.IERRRCX// Resource conflict exception = 0x00000010;
    const Exception.TSRCXM// Current execution mode bits = 0x000000C0;
    const Exception.TSRCXMSHIFT// TSR.CXM left shift value = 6;
    const Exception.TSRCXMSV// Supervisor mode = 0x00000000;
    const Exception.TSRCXMUS// User mode = 0x00000040;
    const Exception.TSREXC// Exception processing = 0x00000400;
    const Exception.TSRGEE// Global exception enable = 0x00000004;
    const Exception.TSRXEN// External exception enable = 0x00000008;
    var obj = new Exception.Status// Status - structure filled by getLastStatus();
        obj.efr// EFR register = Bits32 ...
        obj.nrp// NRP register = Bits32 ...
        obj.ntsr// NTSR register = Bits32 ...
        obj.ierr// IERR register = Bits32 ...
        obj.excContext// Context structure filled by last exception = Exception.Context* ...
module-wide config parameters
     Exception.E_exceptionMax// = Error.Desc {
        msg: "E_exceptionMax: pc = 0x%08x, sp = 0x%08x.\nTo see more exception detail, use ROV or set 'ti.sysbios.family.c64p.Exception.enablePrint = true;'"
    };
     Exception.E_exceptionMin// Error raised when abortFlag is true = Error.Desc {
        msg: "E_exceptionMin: pc = 0x%08x, sp = 0x%08x."
    };
     Exception.enableExternalMPC// enableExternalMPC - Enable handling of Memory Protection Controller (MPC) exceptions = Bool false;
     Exception.enablePrint// enablePrint - Enable print of exception details and Register values = Bool true;
     Exception.exceptionHook// exceptionHook - Function hook called by handler This is called anytime an exception occurs = Void(*)(Void) null;
     Exception.externalHook// externalHook - Function hook called by externalHandler Function is only called when an external exception has occurred = Void(*)(Void) null;
     Exception.internalHook// internalHook - Function hook called by internalHandler Function is only called when an internal exception has occurred = Void(*)(Void) null;
     Exception.nmiHook// nmiHook - Function hook called by nmiHandler Function is called for legacy NMI exceptions only = Void(*)(Void) null;
     Exception.returnHook// returnHook - Function hook called at the end of Exception_dispatch = Void(*)(Void) null;
     Exception.common$// Common module configuration parameters = Types.Common$ undefined;
const Exception.ECREXF
index URL

EXCEP flag

XDCscript usage meta-domain
const Exception.ECREXF = Exception.EFREXF;
C SYNOPSIS
Exception_ECREXF
const Exception.ECRIXF
index URL

Internal exception flag

XDCscript usage meta-domain
const Exception.ECRIXF = Exception.EFRIXF;
C SYNOPSIS
Exception_ECRIXF
const Exception.ECRNXF
index URL

NMI exception flag

XDCscript usage meta-domain
const Exception.ECRNXF = Exception.EFRNXF;
C SYNOPSIS
Exception_ECRNXF
const Exception.ECRSXF
index URL

Software exception flag

XDCscript usage meta-domain
const Exception.ECRSXF = Exception.EFRSXF;
C SYNOPSIS
Exception_ECRSXF
const Exception.EFREXF
index URL

EXCEP flag

XDCscript usage meta-domain
const Exception.EFREXF = 0x40000000;
C SYNOPSIS
Exception_EFREXF
const Exception.EFRIXF
index URL

Internal exception flag

XDCscript usage meta-domain
const Exception.EFRIXF = 0x00000002;
C SYNOPSIS
Exception_EFRIXF
const Exception.EFRNXF
index URL

NMI exception flag

XDCscript usage meta-domain
const Exception.EFRNXF = 0x80000000;
C SYNOPSIS
Exception_EFRNXF
const Exception.EFRSXF
index URL

Software exception flag

XDCscript usage meta-domain
const Exception.EFRSXF = 0x00000001;
C SYNOPSIS
Exception_EFRSXF
const Exception.IERREPX
index URL

Execute packet exception

XDCscript usage meta-domain
const Exception.IERREPX = 0x00000004;
C SYNOPSIS
Exception_IERREPX
const Exception.IERRFPX
index URL

Fetch packet exception

XDCscript usage meta-domain
const Exception.IERRFPX = 0x00000002;
C SYNOPSIS
Exception_IERRFPX
const Exception.IERRIFX
index URL

Instruction fetch exception

XDCscript usage meta-domain
const Exception.IERRIFX = 0x00000001;
C SYNOPSIS
Exception_IERRIFX
const Exception.IERRLBX
index URL

Loop buffer exception

XDCscript usage meta-domain
const Exception.IERRLBX = 0x00000080;
C SYNOPSIS
Exception_IERRLBX
const Exception.IERRMSX
index URL

Missed stall exception

XDCscript usage meta-domain
const Exception.IERRMSX = 0x00000100;
C SYNOPSIS
Exception_IERRMSX
const Exception.IERROPX
index URL

Opcode exception

XDCscript usage meta-domain
const Exception.IERROPX = 0x00000008;
C SYNOPSIS
Exception_IERROPX
const Exception.IERRPRX
index URL

Priviledge exception

XDCscript usage meta-domain
const Exception.IERRPRX = 0x00000040;
C SYNOPSIS
Exception_IERRPRX
const Exception.IERRRAX
index URL

Resource access exeption

XDCscript usage meta-domain
const Exception.IERRRAX = 0x00000020;
C SYNOPSIS
Exception_IERRRAX
const Exception.IERRRCX
index URL

Resource conflict exception

XDCscript usage meta-domain
const Exception.IERRRCX = 0x00000010;
C SYNOPSIS
Exception_IERRRCX
const Exception.TSRCXM
index URL

Current execution mode bits

XDCscript usage meta-domain
const Exception.TSRCXM = 0x000000C0;
C SYNOPSIS
Exception_TSRCXM
const Exception.TSRCXMSHIFT
index URL

TSR.CXM left shift value

XDCscript usage meta-domain
const Exception.TSRCXMSHIFT = 6;
C SYNOPSIS
Exception_TSRCXMSHIFT
const Exception.TSRCXMSV
index URL

Supervisor mode

XDCscript usage meta-domain
const Exception.TSRCXMSV = 0x00000000;
C SYNOPSIS
Exception_TSRCXMSV
const Exception.TSRCXMUS
index URL

User mode

XDCscript usage meta-domain
const Exception.TSRCXMUS = 0x00000040;
C SYNOPSIS
Exception_TSRCXMUS
const Exception.TSREXC
index URL

Exception processing

XDCscript usage meta-domain
const Exception.TSREXC = 0x00000400;
C SYNOPSIS
Exception_TSREXC
const Exception.TSRGEE
index URL

Global exception enable

XDCscript usage meta-domain
const Exception.TSRGEE = 0x00000004;
C SYNOPSIS
Exception_TSRGEE
const Exception.TSRXEN
index URL

External exception enable

XDCscript usage meta-domain
const Exception.TSRXEN = 0x00000008;
C SYNOPSIS
Exception_TSRXEN
struct Exception.Status
index URL

Status - structure filled by getLastStatus()

XDCscript usage meta-domain
var obj = new Exception.Status;
    obj.efr = Bits32 ...
    // EFR register
    obj.nrp = Bits32 ...
    // NRP register
    obj.ntsr = Bits32 ...
    // NTSR register
    obj.ierr = Bits32 ...
    // IERR register
    obj.excContext = Exception.Context* ...
    // Context structure filled by last exception
C SYNOPSIS
Exception_Status
config Exception.E_exceptionMax // module-wide
index URL
XDCscript usage meta-domain
Exception.E_exceptionMax = Error.Desc {
    msg: "E_exceptionMax: pc = 0x%08x, sp = 0x%08x.\nTo see more exception detail, use ROV or set 'ti.sysbios.family.c64p.Exception.enablePrint = true;'"
};
C SYNOPSIS
Exception_E_exceptionMax
config Exception.E_exceptionMin // module-wide
index URL

Error raised when abortFlag is true

XDCscript usage meta-domain
Exception.E_exceptionMin = Error.Desc {
    msg: "E_exceptionMin: pc = 0x%08x, sp = 0x%08x."
};
C SYNOPSIS
Exception_E_exceptionMin
config Exception.enableExternalMPC // module-wide
index URL

enableExternalMPC - Enable handling of Memory Protection Controller (MPC) exceptions

XDCscript usage meta-domain
Exception.enableExternalMPC = Bool false;
C SYNOPSIS
Exception_enableExternalMPC
config Exception.enablePrint // module-wide
index URL

enablePrint - Enable print of exception details and Register values

XDCscript usage meta-domain
Exception.enablePrint = Bool true;
C SYNOPSIS
Exception_enablePrint
config Exception.exceptionHook // module-wide
index URL

exceptionHook - Function hook called by handler This is called anytime an exception occurs

XDCscript usage meta-domain
Exception.exceptionHook = Void(*)(Void) null;
C SYNOPSIS
Exception_exceptionHook
config Exception.externalHook // module-wide
index URL

externalHook - Function hook called by externalHandler Function is only called when an external exception has occurred

XDCscript usage meta-domain
Exception.externalHook = Void(*)(Void) null;
C SYNOPSIS
Exception_externalHook
config Exception.internalHook // module-wide
index URL

internalHook - Function hook called by internalHandler Function is only called when an internal exception has occurred

XDCscript usage meta-domain
Exception.internalHook = Void(*)(Void) null;
C SYNOPSIS
Exception_internalHook
config Exception.nmiHook // module-wide
index URL

nmiHook - Function hook called by nmiHandler Function is called for legacy NMI exceptions only

XDCscript usage meta-domain
Exception.nmiHook = Void(*)(Void) null;
C SYNOPSIS
Exception_nmiHook
config Exception.returnHook // module-wide
index URL

returnHook - Function hook called at the end of Exception_dispatch

XDCscript usage meta-domain
Exception.returnHook = Void(*)(Void) null;
C SYNOPSIS
Exception_returnHook
metaonly config Exception.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Exception.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:49 GMT


module ti.sysbios.family.c64p.Hwi
index URL

C64+ Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides C64+ family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/Hwi.xdc
#include <ti/sysbios/family/c64p/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Void | Hwi_eventMap// Maps a GEM event to interrupt number(Int intNum, Int eventId);
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with interrupt number(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigures a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called(Bits16 mask);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// C64+ supports 16 interrupts (Int)16
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_enableException// enable Exception module for exception processing;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides C64+ family-specific implementations of the APIs defined in IHwi.
Additional C64+ device-specific APIs are also provided.
An example of creating a Hwi instance:
  Int intNum;
  Hwi_Params params;
  Error_Block eb;

  // Initialize the error block
  Error_init(&eb);

  // Initialize the Hwi parameters
  Hwi_Params_init(&params);

  // Set the GEM event id in the params
  params.eventId = 78

  // Specify the interrupt vector number
  intNum = 8;

  // create the Hwi for the specified interrupt number and params
  Hwi_create(intNum, myIsr, &params, &eb);
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | N
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableIER | Y | Y | Y | Y | N
enableInterrupt | Y | Y | Y | Y | N
eventMap | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | N
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

C64+ supports 16 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)16
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
config Hwi_enableException // module-wide
index URL

enable Exception module for exception processing

C synopsis target-domain
extern const Bool Hwi_enableException;
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to enable
RETURNS
previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_eventMap() // module-wide
index URL

Maps a GEM event to interrupt number

C synopsis target-domain
Void Hwi_eventMap(Int intNum, Int eventId);
ARGUMENTS
intNum — interrupt number
eventId — event ID
DETAILS
Function maps a GEM event to an interrupt number so that the event is the interrupt source of the vector.
      // Maps GEM event #65 as the interrupt source of int vector #7
      Hwi_eventMap(7, 65);
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with interrupt number

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
RETURNS
handle associated with intNum
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous IER settings bitmask
DETAILS
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigures a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
params — pointer to Hwi parameter structure
DETAILS
This function reconfigures the dispatched interrupt so the specified function is called with the specified parameters.
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.c64p.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// C64+ supports 16 interrupts = 16;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.fxn// "Hwi_plug'd" ISR function = Void(*)(Void) ...
        obj.enableInt = Bool ...
        obj.eventId = Int ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.enableException// enable Exception module for exception processing = Bool true;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.resetVectorAddress// Alternate reset vector address. Default is undefined = Ptr undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.eventMapMeta// Maps GEM Event to interrupt number statically(Int intNum, Int eventId) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

C64+ supports 16 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 16;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    // "Hwi_plug'd" ISR function
    obj.enableInt = Bool ...
    obj.eventId = Int ...
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
config Hwi.enableException // module-wide
index URL

enable Exception module for exception processing

XDCscript usage meta-domain
Hwi.enableException = Bool true;
C SYNOPSIS
Hwi_enableException
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.resetVectorAddress // module-wide
index URL

Alternate reset vector address. Default is undefined

XDCscript usage meta-domain
Hwi.resetVectorAddress = Ptr undefined;
DETAILS
if initialized by the user then an additional reset vector is created and placed in the ".resetVector" section. To place the .resetVector section into a specific memory section, add the following command to your config script:
  Program.sectMap[".resetVector"] = YourMemorySection;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.eventMapMeta() // module-wide
index URL

Maps GEM Event to interrupt number statically

XDCscript usage meta-domain
Hwi.eventMapMeta(Int intNum, Int eventId) returns Void
ARGUMENTS
intNum — interrupt number
eventId — event Id
DETAILS
Function maps a GEM event to an interrupt number so that the event is the interrupt source of the vector.
      // Maps GEM event #65 as the interrupt source of int vector #7
      Hwi.eventMapMeta(7, 65);
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:22:49 GMT


module ti.sysbios.family.c64p.MemoryProtect
index URL

MemoryProtect Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provide an API to get and to set the permission attributes of a memory range. A memory range can be set to user executable, user writable, user readable, supervisor executable, supervisor writable, or supervisor readable. Setting a memory range to only user readable, writable or executable should be done with caution because BIOS executes in supervisor mode. Whenever setting the permission attributes of a memory range, the local CPU access field must be set, if the local CPU accesses the memory range. If the local field is not set, an exception is generated if the CPU tries to access the memory range. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/MemoryProtect.xdc
#include <ti/sysbios/family/c64p/MemoryProtect.h>
Functions
Bool | MemoryProtect_getPA// Gets the PA (Permission Attribute) corresponding to addr(Ptr addr, UInt32 *paMask);
Bool | MemoryProtect_setPA// Sets the PA (Permission Attribute) corresponding to addr/size(Ptr addr, SizeT size, UInt32 paMask);
Functions common to all target modules
 | MemoryProtect_Module_getMask// Returns the diagnostics mask for this module, MemoryProtect_Module_hasMask// Test whether this module has a diagnostics mask, MemoryProtect_Module_heap// The heap from which this module allocates memory, MemoryProtect_Module_id// Get this module's unique id, MemoryProtect_Module_setMask// Set the diagnostics mask for this module, MemoryProtect_Module_startupDone// Test if this module has completed startup
Defines
#define | MemoryProtect_MPPA_LOCAL// Local CPU may access (UInt32)0x00000100
#define | MemoryProtect_MPPA_SR// Supervisor mode read (UInt32)0x00000020
#define | MemoryProtect_MPPA_SW// Supervisor mode may write (UInt32)0x00000010
#define | MemoryProtect_MPPA_SX// Supervisor mode may execute (UInt32)0x00000008
#define | MemoryProtect_MPPA_UR// User mode may read (UInt32)0x00000004
#define | MemoryProtect_MPPA_UW// User mode may write (UInt32)0x00000002
#define | MemoryProtect_MPPA_UX// User mode may execute (UInt32)0x00000001
DETAILS
This module provide an API to get and to set the permission attributes of a memory range. A memory range can be set to user executable, user writable, user readable, supervisor executable, supervisor writable, or supervisor readable. Setting a memory range to only user readable, writable or executable should be done with caution because BIOS executes in supervisor mode. Whenever setting the permission attributes of a memory range, the local CPU access field must be set, if the local CPU accesses the memory range. If the local field is not set, an exception is generated if the CPU tries to access the memory range.
This module is to be used in correlation with the Exception module. When this module is in use, external exceptions are enabled by default. Any memory protection fault which arises generates an exception. This exception is processed and decoded by the Exception module.
An example of setting Local L2 RAM to be supervisor read-only and CPU accessible:
    UInt32 paMask;
    paMask = MemoryProtect_MPPA_LOCAL |
             MemoryProtect_MPPA_SR;

    MemoryProtect_setPA((Ptr)0x11800000, 0x40000, paMask);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getPA | Y | Y | Y | Y | Y
setPA | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
const MemoryProtect_MPPA_LOCAL
index URL

Local CPU may access

C synopsis target-domain
#define MemoryProtect_MPPA_LOCAL (UInt32)0x00000100
const MemoryProtect_MPPA_SR
index URL

Supervisor mode read

C synopsis target-domain
#define MemoryProtect_MPPA_SR (UInt32)0x00000020
const MemoryProtect_MPPA_SW
index URL

Supervisor mode may write

C synopsis target-domain
#define MemoryProtect_MPPA_SW (UInt32)0x00000010
const MemoryProtect_MPPA_SX
index URL

Supervisor mode may execute

C synopsis target-domain
#define MemoryProtect_MPPA_SX (UInt32)0x00000008
const MemoryProtect_MPPA_UR
index URL

User mode may read

C synopsis target-domain
#define MemoryProtect_MPPA_UR (UInt32)0x00000004
const MemoryProtect_MPPA_UW
index URL

User mode may write

C synopsis target-domain
#define MemoryProtect_MPPA_UW (UInt32)0x00000002
const MemoryProtect_MPPA_UX
index URL

User mode may execute

C synopsis target-domain
#define MemoryProtect_MPPA_UX (UInt32)0x00000001
MemoryProtect_getPA() // module-wide
index URL

Gets the PA (Permission Attribute) corresponding to addr

C synopsis target-domain
Bool MemoryProtect_getPA(Ptr addr, UInt32 *paMask);
ARGUMENTS
addr — address of memory location for which the PA applies
paMask — ptr to location where PA mask for addr is stored
RETURNS
if address doesn't belong to any configured MPC then FALSE, otherwise TRUE and *paMask contains addr's MPPA setting
MemoryProtect_setPA() // module-wide
index URL

Sets the PA (Permission Attribute) corresponding to addr/size

C synopsis target-domain
Bool MemoryProtect_setPA(Ptr addr, SizeT size, UInt32 paMask);
ARGUMENTS
addr — begin address of memory block for which the PA applies
size — size of memory block
paMask — PA mask to assign for the memory block
RETURNS
if address doesn't belong to any configured MPC then FALSE, otherwise TRUE and PA was written to addr's MPPA register
DETAILS
The PA is applied to all addresses that are spanned by the memory block.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId MemoryProtect_Module_id();
// Get this module's unique id
Bool MemoryProtect_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle MemoryProtect_Module_heap();
// The heap from which this module allocates memory
Bool MemoryProtect_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 MemoryProtect_Module_getMask();
// Returns the diagnostics mask for this module
Void MemoryProtect_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/MemoryProtect.xdc
var MemoryProtect = xdc.useModule('ti.sysbios.family.c64p.MemoryProtect');
module-wide constants & types
    const MemoryProtect.MPPA_LOCAL// Local CPU may access = 0x00000100;
    const MemoryProtect.MPPA_SR// Supervisor mode read = 0x00000020;
    const MemoryProtect.MPPA_SW// Supervisor mode may write = 0x00000010;
    const MemoryProtect.MPPA_SX// Supervisor mode may execute = 0x00000008;
    const MemoryProtect.MPPA_UR// User mode may read = 0x00000004;
    const MemoryProtect.MPPA_UW// User mode may write = 0x00000002;
    const MemoryProtect.MPPA_UX// User mode may execute = 0x00000001;
module-wide config parameters
     MemoryProtect.common$// Common module configuration parameters = Types.Common$ undefined;
const MemoryProtect.MPPA_LOCAL
index URL

Local CPU may access

XDCscript usage meta-domain
const MemoryProtect.MPPA_LOCAL = 0x00000100;
C SYNOPSIS
MemoryProtect_MPPA_LOCAL
const MemoryProtect.MPPA_SR
index URL

Supervisor mode read

XDCscript usage meta-domain
const MemoryProtect.MPPA_SR = 0x00000020;
C SYNOPSIS
MemoryProtect_MPPA_SR
const MemoryProtect.MPPA_SW
index URL

Supervisor mode may write

XDCscript usage meta-domain
const MemoryProtect.MPPA_SW = 0x00000010;
C SYNOPSIS
MemoryProtect_MPPA_SW
const MemoryProtect.MPPA_SX
index URL

Supervisor mode may execute

XDCscript usage meta-domain
const MemoryProtect.MPPA_SX = 0x00000008;
C SYNOPSIS
MemoryProtect_MPPA_SX
const MemoryProtect.MPPA_UR
index URL

User mode may read

XDCscript usage meta-domain
const MemoryProtect.MPPA_UR = 0x00000004;
C SYNOPSIS
MemoryProtect_MPPA_UR
const MemoryProtect.MPPA_UW
index URL

User mode may write

XDCscript usage meta-domain
const MemoryProtect.MPPA_UW = 0x00000002;
C SYNOPSIS
MemoryProtect_MPPA_UW
const MemoryProtect.MPPA_UX
index URL

User mode may execute

XDCscript usage meta-domain
const MemoryProtect.MPPA_UX = 0x00000001;
C SYNOPSIS
MemoryProtect_MPPA_UX
metaonly config MemoryProtect.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
MemoryProtect.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:49 GMT


module ti.sysbios.family.c64p.Settings

metaonly module ti.sysbios.family.c64p.Settings
index URL

Device/Family-specific delegate assignment module for C64P and C674 target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.c64p.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:22:49 GMT


module ti.sysbios.family.c64p.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c64p/TimestampProvider.xdc
#include <ti/sysbios/family/c64p/TimestampProvider.h>
Functions common to all ITimestamp modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.c64p.TimestampProvider');
module-wide config parameters
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:49 GMT


package ti.sysbios.family.c64p.dm6437
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/dm6437/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.dm6437 [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:50 GMT


package ti.sysbios.family.c64p.dm6446
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/dm6446/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.dm6446 [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:50 GMT


package ti.sysbios.family.c64p.omap3430
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/omap3430/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.omap3430 [2, 0, 0, 0] {
    module Wugen;
    // Wugen Module
}
generated on Fri, 17 Jun 2011 00:22:52 GMT


module ti.sysbios.family.c64p.omap3430.Wugen
index URL

Wugen Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Unconstrained Functions All functions [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/omap3430/Wugen.xdc
#include <ti/sysbios/family/c64p/omap3430/Wugen.h>
Functions
Void | Wugen_applyMasks// This function takes an array of 3 integers and applies the specified mask to the WUGEN interrupt mask registers. If the bit in the mask is enabled, the corresponding interrupt in the WUGEN will be blocked(UInt32 mask[]);
Void | Wugen_disableDma// Disables the specified DMA source in the WUGEN(UInt dmaid);
Void | Wugen_disableEvent// Disables the specified interrupt event source in the WUGEN(UInt eventid);
Void | Wugen_enableDma// Enables the specified DMA source in the WUGEN(UInt dmaid);
Void | Wugen_enableEvent// Enables the specified interrupt event source in the WUGEN(UInt eventid);
Void | Wugen_getMasks// This function returns the WUGEN interrupt mask registers(UInt32 mask[]);
Void | Wugen_ierToMasks// Compute the WUGEN masks needed to allow the interrupts set in the IER register to propagate through the WUGEN. This function does not enable external DMA requests. You must set these explicitly to configure a DMA request as a wakeup event(UInt32 mask[]);
Functions common to all target modules
 | Wugen_Module_getMask// Returns the diagnostics mask for this module, Wugen_Module_hasMask// Test whether this module has a diagnostics mask, Wugen_Module_heap// The heap from which this module allocates memory, Wugen_Module_id// Get this module's unique id, Wugen_Module_setMask// Set the diagnostics mask for this module, Wugen_Module_startupDone// Test if this module has completed startup
DETAILS
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
applyMasks | Y | Y | Y | Y | Y
disableDma | Y | Y | Y | Y | Y
disableEvent | Y | Y | Y | Y | Y
enableDma | Y | Y | Y | Y | Y
enableEvent | Y | Y | Y | Y | Y
getMasks | Y | Y | Y | Y | Y
ierToMasks | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
Wugen_applyMasks() // module-wide
index URL

This function takes an array of 3 integers and applies the specified mask to the WUGEN interrupt mask registers. If the bit in the mask is enabled, the corresponding interrupt in the WUGEN will be blocked

C synopsis target-domain
Void Wugen_applyMasks(UInt32 mask[]);
ARGUMENTS
mask — array of three integers for applying to the WUGEN interrupt mask register. First mask consists of IRQ 0-31 Second mask consists of IRQ 32-47 Third mask consists of DMA requests
Wugen_disableDma() // module-wide
index URL

Disables the specified DMA source in the WUGEN

C synopsis target-domain
Void Wugen_disableDma(UInt dmaid);
ARGUMENTS
dmaid — the DMA id for a particular EDMA source.
Wugen_disableEvent() // module-wide
index URL

Disables the specified interrupt event source in the WUGEN

C synopsis target-domain
Void Wugen_disableEvent(UInt eventid);
ARGUMENTS
eventid — the event number of an interrupt source
Wugen_enableDma() // module-wide
index URL

Enables the specified DMA source in the WUGEN

C synopsis target-domain
Void Wugen_enableDma(UInt dmaid);
ARGUMENTS
dmaid — the DMA id for a particular EDMA source.
Wugen_enableEvent() // module-wide
index URL

Enables the specified interrupt event source in the WUGEN

C synopsis target-domain
Void Wugen_enableEvent(UInt eventid);
ARGUMENTS
eventid — the event number of an interrupt source
Wugen_getMasks() // module-wide
index URL

This function returns the WUGEN interrupt mask registers

C synopsis target-domain
Void Wugen_getMasks(UInt32 mask[]);
ARGUMENTS
mask — array of three integers used to return the WUGEN interrupt mask registers First mask consists of IRQ 0-31 Second mask consists of IRQ 32-47 Third mask consists of DMA requests
Wugen_ierToMasks() // module-wide
index URL

Compute the WUGEN masks needed to allow the interrupts set in the IER register to propagate through the WUGEN. This function does not enable external DMA requests. You must set these explicitly to configure a DMA request as a wakeup event

C synopsis target-domain
Void Wugen_ierToMasks(UInt32 mask[]);
ARGUMENTS
mask — array of three integers for returning WUGEN masks. First mask consists of IRQ 0-31 Second mask consists of IRQ 32-47 Third mask consists of DMA requests
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Wugen_Module_id();
// Get this module's unique id
Bool Wugen_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Wugen_Module_heap();
// The heap from which this module allocates memory
Bool Wugen_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Wugen_Module_getMask();
// Returns the diagnostics mask for this module
Void Wugen_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/omap3430/Wugen.xdc
var Wugen = xdc.useModule('ti.sysbios.family.c64p.omap3430.Wugen');
module-wide config parameters
     Wugen.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config Wugen.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Wugen.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:52 GMT


package ti.sysbios.family.c64p.primus
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/primus/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.primus [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:52 GMT


package ti.sysbios.family.c64p.tci6482
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/tci6482/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.tci6482 [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:51 GMT


package ti.sysbios.family.c64p.tci6488
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/tci6488/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.tci6488 [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:51 GMT


package ti.sysbios.family.c64p.tesla
index URL

Contains specifications for the c64p.tesla-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/tesla/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.tesla [1, 0, 0, 0] {
    module Power;
    // Power Module
    module Wugen;
    // Wugen Module
}
generated on Fri, 17 Jun 2011 00:22:54 GMT


module ti.sysbios.family.c64p.tesla.Power
index URL

Power Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module is used to reduce power consumption of the Tesla subsystem. Three reduction techniques are supported: [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/tesla/Power.xdc
#include <ti/sysbios/family/c64p/tesla/Power.h>
Functions
Void | Power_idleCPU// Function used to automatically idle the CPU in the Idle loop();
UInt | Power_suspend// Function used for suspend/resume of the Tesla subsystem(Power_Suspend level);
Functions common to all target modules
 | Power_Module_getMask// Returns the diagnostics mask for this module, Power_Module_hasMask// Test whether this module has a diagnostics mask, Power_Module_heap// The heap from which this module allocates memory, Power_Module_id// Get this module's unique id, Power_Module_setMask// Set the diagnostics mask for this module, Power_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Power_Suspend// Suspend Level ...
Constants
extern const Bool | Power_idle// Idle the CPU when threads blocked waiting for an interrupt?;
extern const Ptr | Power_syscRegs// Base address of SYSC registers;
extern const Ptr | Power_tpccRegs// Base address of EDMA TPCC registers;
DETAILS
This module is used to reduce power consumption of the Tesla subsystem. Three reduction techniques are supported:
Suspend/Resume with Retention: The Tesla subsystem is put into standby, upon which PRCM will transition the power domain to closed-switch retention (CSWR). Upon release from retention reset, the CPU will start executing from reset; a reset hook function will hijack the boot process, restore CPU state to that before retention, and then return back into the Power_suspend() API, which will return to its caller, to resume the application.
Suspend/Resume with Hibernation: The Tesla subsystem context is saved to external RAM, and GEM is put into standby. Upon the standby transition, PRCM will transition the power domain to off. Upon release from reset, the CPU will start executing from reset; a reset hook function will hijack the boot process, restore CPU state, return back into the Power_suspend() API, which will restore the remaining Tesla subsystem context, and then return to its caller, to resume the application.
Idling in the Idle loop: A function will be inserted into the Idle loop, which will automatically idle the CPU while waiting for the next interrupt.
The application must explicitly call to Power_suspend() for Suspend/Resume functionality. For idling functionality, this enabled statically, in the application configuration, and the idling in the idle loop will happen routinely upon execution of the Idle loop.
Suspend/Resume can be invoked from Task, Swi, or Idle loop context. It cannot be invoked from Hwi context.
enum Power_Suspend
index URL

Suspend Level

C synopsis target-domain
typedef enum Power_Suspend {
    Power_Suspend_RETENTION,
    // Suspend to RETENTION state
    Power_Suspend_HIBERNATE
    // Suspend to HIBERNATE state
} Power_Suspend;
config Power_idle // module-wide
index URL

Idle the CPU when threads blocked waiting for an interrupt?

C synopsis target-domain
extern const Bool Power_idle;
config Power_syscRegs // module-wide
index URL

Base address of SYSC registers

C synopsis target-domain
extern const Ptr Power_syscRegs;
config Power_tpccRegs // module-wide
index URL

Base address of EDMA TPCC registers

C synopsis target-domain
extern const Ptr Power_tpccRegs;
Power_idleCPU() // module-wide
index URL

Function used to automatically idle the CPU in the Idle loop

C synopsis target-domain
Void Power_idleCPU();
DETAILS
When the 'idle' configuration flag is set: this function will be added to the list of Idle loop functions. When called from the Idle loop, it will invoke the IDLE instruction, to idle the CPU until the next interrupt occurs. This function will idle the CPU, but will not put the whole megamodule (GEM) into standby.
Power_suspend() // module-wide
index URL

Function used for suspend/resume of the Tesla subsystem

C synopsis target-domain
UInt Power_suspend(Power_Suspend level);
DETAILS
This function will save Tesla subsystem context and then put GEM into standby, as the final steps for a transition to either retention (CSWR), or hibernate (also referred to as off-mode).
Prior to invoking this function the application software must prepare for suspend, which includes: configuring PRCM for the appropriate transition once GEM goes to standby; disabling unintended wakeup interrupts, and configuring intended wakeups; taking care of any required notifications to software components; and 'quieting' of the DSP application (e.g., ensuring that all in-progress EDMA activity completes).
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Power_Module_id();
// Get this module's unique id
Bool Power_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Power_Module_heap();
// The heap from which this module allocates memory
Bool Power_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Power_Module_getMask();
// Returns the diagnostics mask for this module
Void Power_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/tesla/Power.xdc
var Power = xdc.useModule('ti.sysbios.family.c64p.tesla.Power');
module-wide constants & types
    values of type Power.Suspend// Suspend Level
        const Power.Suspend_RETENTION// Suspend to RETENTION state;
        const Power.Suspend_HIBERNATE// Suspend to HIBERNATE state;
module-wide config parameters
     Power.idle// Idle the CPU when threads blocked waiting for an interrupt? = Bool false;
     Power.syscRegs// Base address of SYSC registers = Ptr 0x01C20000;
     Power.tpccRegs// Base address of EDMA TPCC registers = Ptr 0x01C00000;
     Power.common$// Common module configuration parameters = Types.Common$ undefined;
     Power.loadSegment// Name of segment to load Power's reset code and saved context = String "EXT_RAM";
enum Power.Suspend
index URL

Suspend Level

XDCscript usage meta-domain
values of type Power.Suspend
    const Power.Suspend_RETENTION;
    // Suspend to RETENTION state
    const Power.Suspend_HIBERNATE;
    // Suspend to HIBERNATE state
C SYNOPSIS
Power_Suspend
config Power.idle // module-wide
index URL

Idle the CPU when threads blocked waiting for an interrupt?

XDCscript usage meta-domain
Power.idle = Bool false;
C SYNOPSIS
Power_idle
config Power.syscRegs // module-wide
index URL

Base address of SYSC registers

XDCscript usage meta-domain
Power.syscRegs = Ptr 0x01C20000;
C SYNOPSIS
Power_syscRegs
config Power.tpccRegs // module-wide
index URL

Base address of EDMA TPCC registers

XDCscript usage meta-domain
Power.tpccRegs = Ptr 0x01C00000;
C SYNOPSIS
Power_tpccRegs
metaonly config Power.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Power.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Power.loadSegment // module-wide
index URL

Name of segment to load Power's reset code and saved context

XDCscript usage meta-domain
Power.loadSegment = String "EXT_RAM";
generated on Fri, 17 Jun 2011 00:22:54 GMT


module ti.sysbios.family.c64p.tesla.Wugen
index URL

Wugen Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Using Wugen will install a Hwi beginHook that automatically clears the corresponding pending WUGEN IRQ bit for the interrupting event. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c64p/tesla/Wugen.xdc
#include <ti/sysbios/family/c64p/tesla/Wugen.h>
Functions
Void | Wugen_applyMasks// This function takes an array of 5 integers and applies the specified mask to the WUGEN interrupt mask registers. If the bit in the mask is enabled, the corresponding interrupt in the WUGEN will be blocked(UInt32 mask[]);
Void | Wugen_disableDma// Disables the specified DMA source in the WUGEN(UInt dmaid);
Void | Wugen_disableEvent// Disables the specified interrupt event source in the WUGEN(UInt eventid);
Void | Wugen_enableDma// Enables the specified DMA source in the WUGEN(UInt dmaid);
Void | Wugen_enableEvent// Enables the specified interrupt event source in the WUGEN(UInt eventid);
Void | Wugen_getMasks// This function returns the WUGEN interrupt mask registers(UInt32 mask[]);
Void | Wugen_ierToMasks// Compute the WUGEN masks needed to allow the interrupts set in the IER register to propagate through the WUGEN. This function does not enable external DMA requests. You must set these explicitly to configure a DMA request as a wakeup event(UInt32 mask[]);
Functions common to all target modules
 | Wugen_Module_getMask// Returns the diagnostics mask for this module, Wugen_Module_hasMask// Test whether this module has a diagnostics mask, Wugen_Module_heap// The heap from which this module allocates memory, Wugen_Module_id// Get this module's unique id, Wugen_Module_setMask// Set the diagnostics mask for this module, Wugen_Module_startupDone// Test if this module has completed startup
DETAILS
Using Wugen will install a Hwi beginHook that automatically clears the corresponding pending WUGEN IRQ bit for the interrupting event.
Currently this functionality is provided only for non-combined events.
Combined events must be cleared manually by the user's ISR.
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
applyMasks | Y | Y | Y | Y | Y
disableDma | Y | Y | Y | Y | Y
disableEvent | Y | Y | Y | Y | Y
enableDma | Y | Y | Y | Y | Y
enableEvent | Y | Y | Y | Y | Y
getMasks | Y | Y | Y | Y | Y
ierToMasks | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
Wugen_applyMasks() // module-wide
index URL

This function takes an array of 5 integers and applies the specified mask to the WUGEN interrupt mask registers. If the bit in the mask is enabled, the corresponding interrupt in the WUGEN will be blocked

C synopsis target-domain
Void Wugen_applyMasks(UInt32 mask[]);
ARGUMENTS
mask — array of five integers for applying to the WUGEN interrupt mask register. mask[0] consists of IRQ 0-31 mask[1] consists of IRQ 32-63 mask[2] consists of IRQ 64-71 mask[3] consists of DMA 0-31 requests mask[4] consists of DMA 32-63 requests
Wugen_disableDma() // module-wide
index URL

Disables the specified DMA source in the WUGEN

C synopsis target-domain
Void Wugen_disableDma(UInt dmaid);
ARGUMENTS
dmaid — the DMA id for a particular EDMA source.
Wugen_disableEvent() // module-wide
index URL

Disables the specified interrupt event source in the WUGEN

C synopsis target-domain
Void Wugen_disableEvent(UInt eventid);
ARGUMENTS
eventid — the event number of an interrupt source
Wugen_enableDma() // module-wide
index URL

Enables the specified DMA source in the WUGEN

C synopsis target-domain
Void Wugen_enableDma(UInt dmaid);
ARGUMENTS
dmaid — the DMA id for a particular EDMA source.
Wugen_enableEvent() // module-wide
index URL

Enables the specified interrupt event source in the WUGEN

C synopsis target-domain
Void Wugen_enableEvent(UInt eventid);
ARGUMENTS
eventid — the event number of an interrupt source
Wugen_getMasks() // module-wide
index URL

This function returns the WUGEN interrupt mask registers

C synopsis target-domain
Void Wugen_getMasks(UInt32 mask[]);
ARGUMENTS
mask — array of five integers used to return the WUGEN interrupt mask registers mask[0] consists of IRQ 0-31 mask[1] consists of IRQ 32-63 mask[2] consists of IRQ 64-71 mask[3] consists of DMA 0-31 requests mask[4] consists of DMA 32-63 requests
Wugen_ierToMasks() // module-wide
index URL

Compute the WUGEN masks needed to allow the interrupts set in the IER register to propagate through the WUGEN. This function does not enable external DMA requests. You must set these explicitly to configure a DMA request as a wakeup event

C synopsis target-domain
Void Wugen_ierToMasks(UInt32 mask[]);
ARGUMENTS
mask — array of five integers for returning WUGEN masks. mask[0] consists of IRQ 0-31 mask[1] consists of IRQ 32-63 mask[2] consists of IRQ 64-71 mask[3] consists of DMA 0-31 requests mask[4] consists of DMA 32-63 requests
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Wugen_Module_id();
// Get this module's unique id
Bool Wugen_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Wugen_Module_heap();
// The heap from which this module allocates memory
Bool Wugen_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Wugen_Module_getMask();
// Returns the diagnostics mask for this module
Void Wugen_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c64p/tesla/Wugen.xdc
var Wugen = xdc.useModule('ti.sysbios.family.c64p.tesla.Wugen');
module-wide config parameters
     Wugen.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config Wugen.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Wugen.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:54 GMT


package ti.sysbios.family.c64p.ti81xx
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/c64p/ti81xx/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c64p.ti81xx [2, 0, 0, 0] {
}
generated on Fri, 17 Jun 2011 00:22:54 GMT


package ti.sysbios.family.c66
index URL

Contains specifications for the C64P specific SYS/BIOS functions

The link below provides SYS/BIOS C6x register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/c66/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c66 [2, 0, 0, 0] {
    module Cache;
    // Cache Module
}
DETAILS
The link below provides SYS/BIOS C6x register usage information:
SYS/BIOS C6x Register Usage
generated on Fri, 17 Jun 2011 00:22:55 GMT


module ti.sysbios.family.c66.Cache
index URL

Cache Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Cache module provides C66 family-specific implementations of the APIs defined in ICache. It also provides additional C66 specific cache functions. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c66/Cache.xdc
#include <ti/sysbios/family/c66/Cache.h>
Functions
UInt32 | Cache_getMar// Gets the MAR register for the specified base address(Ptr baseAddr);
Cache_Mode | Cache_getMode// Get mode of a cache(Bits16 type);
Void | Cache_getSize// Get sizes of all caches(Cache_Size *size);
Void | Cache_invL1pAll// Invalidate all of L1 Program cache();
Void | Cache_setMar// Set MAR register(s) that corresponds to the specified address range(Ptr baseAddr, SizeT byteSize, UInt32 value);
Cache_Mode | Cache_setMode// Set mode of a cache(Bits16 type, Cache_Mode mode);
Void | Cache_setSize// Set sizes of all caches(Cache_Size *size);
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Defines
#define | Cache_PC// Permit Caching (UInt32)1
#define | Cache_PCX// Permit caching in external cache (UInt32)4
#define | Cache_PFX// Prefetchable by external engines (UInt32)8
#define | Cache_WTE// Write through enabled (UInt32)2
Typedefs
typedef enum | Cache_L1Size// Level 1 cache size type definition. Can be used for both L1D & L1P ...
typedef enum | Cache_L2Size// Level 2 cache size type definition ...
typedef enum | Cache_Mar// MAR register setting type definition ...
typedef enum | Cache_Mode// Lists of cache modes for L1/L2 caches ...
typedef struct | Cache_Size// Structure for specifying all cache sizes ...
typedef enum | Cache_Type// Lists of bitmask cache types ...
DETAILS
This Cache module provides C66 family-specific implementations of the APIs defined in ICache. It also provides additional C66 specific cache functions.
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
getMar* | Y | Y | Y | Y | Y
getMode* | Y | Y | Y | Y | Y
getSize* | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
invL1pAll* | Y | Y | Y | Y | Y
setMar* | Y | Y | Y | Y | Y
setMode* | Y | Y | Y | Y | Y
setSize* | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbAll* | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
wbInvAll | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).
  • *: These APIs are intended to be made at initialization time, but are not restricted to this.
const Cache_PC
index URL

Permit Caching

C synopsis target-domain
#define Cache_PC (UInt32)1
const Cache_PCX
index URL

Permit caching in external cache

C synopsis target-domain
#define Cache_PCX (UInt32)4
const Cache_PFX
index URL

Prefetchable by external engines

C synopsis target-domain
#define Cache_PFX (UInt32)8
const Cache_WTE
index URL

Write through enabled

C synopsis target-domain
#define Cache_WTE (UInt32)2
enum Cache_L1Size
index URL

Level 1 cache size type definition. Can be used for both L1D & L1P

C synopsis target-domain
typedef enum Cache_L1Size {
    Cache_L1Size_0K,
    // Amount of cache is 0K, Amount of SRAM is 32K
    Cache_L1Size_4K,
    // Amount of cache is 4K, Amount of SRAM is 28K
    Cache_L1Size_8K,
    // Amount of cache is 8K, Amount of SRAM is 24K
    Cache_L1Size_16K,
    // Amount of cache is 16K, Amount of SRAM is 16K
    Cache_L1Size_32K
    // Amount of cache is 32K, Amount of SRAM is 0K
} Cache_L1Size;
enum Cache_L2Size
index URL

Level 2 cache size type definition

C synopsis target-domain
typedef enum Cache_L2Size {
    Cache_L2Size_0K,
    // L2 is all SRAM
    Cache_L2Size_32K,
    // Amount of cache is 32K
    Cache_L2Size_64K,
    // Amount of cache is 64K
    Cache_L2Size_128K,
    // Amount of cache is 128K
    Cache_L2Size_256K,
    // Amount of cache is 256K
    Cache_L2Size_512K,
    // Amount of cache is 512K
    Cache_L2Size_1024K
    // Amount of cache is 1024K
} Cache_L2Size;
enum Cache_Mar
index URL

MAR register setting type definition

C synopsis target-domain
typedef enum Cache_Mar {
    Cache_Mar_DISABLE,
    // The Permit Copy bit of MAR register is disabled
    Cache_Mar_ENABLE
    // The Permit Copy bit of MAR register is enabled
} Cache_Mar;
enum Cache_Mode
index URL

Lists of cache modes for L1/L2 caches

C synopsis target-domain
typedef enum Cache_Mode {
    Cache_Mode_FREEZE,
    // No new cache lines are allocated
    Cache_Mode_BYPASS,
    // All access result in long-distance access
    Cache_Mode_NORMAL
    // Normal operation of cache
} Cache_Mode;
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
struct Cache_Size
index URL

Structure for specifying all cache sizes

C synopsis target-domain
typedef struct Cache_Size {
     Cache_L1Size l1pSize;
    // L1 Program cache size
     Cache_L1Size l1dSize;
    // L1 Data data size
     Cache_L2Size l2Size;
    // L2 cache size
} Cache_Size;
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
DETAILS
Disabling of L2 cache is currently not supported.
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_getMar() // module-wide
index URL

Gets the MAR register for the specified base address

C synopsis target-domain
UInt32 Cache_getMar(Ptr baseAddr);
ARGUMENTS
baseAddr — address for which MAR is requested
RETURNS
value of MAR register
Cache_getMode() // module-wide
index URL

Get mode of a cache

C synopsis target-domain
Cache_Mode Cache_getMode(Bits16 type);
ARGUMENTS
type — bit mask of cache type
RETURNS
mode of specified level of cache
Cache_getSize() // module-wide
index URL

Get sizes of all caches

C synopsis target-domain
Void Cache_getSize(Cache_Size *size);
ARGUMENTS
size — pointer to structure of type Cache_Size
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_invL1pAll() // module-wide
index URL

Invalidate all of L1 Program cache

C synopsis target-domain
Void Cache_invL1pAll();
DETAILS
Performs a global invalidate of L1P cache. Polls the L1P invalidate register until done.
Cache_setMar() // module-wide
index URL

Set MAR register(s) that corresponds to the specified address range

C synopsis target-domain
Void Cache_setMar(Ptr baseAddr, SizeT byteSize, UInt32 value);
ARGUMENTS
baseAddr — start address for which to set MAR
byteSize — size (in bytes) of memory block
value — value for setting MAR register
DETAILS
All cached entries in L1 and L2 are written back and invalidated.
Cache_setMode() // module-wide
index URL

Set mode of a cache

C synopsis target-domain
Cache_Mode Cache_setMode(Bits16 type, Cache_Mode mode);
ARGUMENTS
type — bit mask of cache type
mode — mode of cache
RETURNS
previous mode of cache
Cache_setSize() // module-wide
index URL

Set sizes of all caches

C synopsis target-domain
Void Cache_setSize(Cache_Size *size);
ARGUMENTS
size — pointer to structure of type Cache_Size
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Perform a global write back. There is no effect on L1P cache. All cache lines are left valid in L1D cache and the data in L1D cache is written back to L2 or external. All cache lines are left valid in L2 cache and the data in L2 cache is written back to external.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Performs a global write back and invalidate. All cache lines are invalidated in L1P cache. All cache lines are written back to L2 or external and then invalidated in L1D cache. All cache lines are written back to external and then invalidated in L2 cache.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c66/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.c66.Cache');
module-wide constants & types
    const Cache.PC// Permit Caching = 1;
    const Cache.PCX// Permit caching in external cache = 4;
    const Cache.PFX// Prefetchable by external engines = 8;
    const Cache.WTE// Write through enabled = 2;
    values of type Cache.L1Size// Level 1 cache size type definition. Can be used for both L1D & L1P
        const Cache.L1Size_0K// Amount of cache is 0K, Amount of SRAM is 32K;
        const Cache.L1Size_4K// Amount of cache is 4K, Amount of SRAM is 28K;
        const Cache.L1Size_8K// Amount of cache is 8K, Amount of SRAM is 24K;
        const Cache.L1Size_16K// Amount of cache is 16K, Amount of SRAM is 16K;
        const Cache.L1Size_32K// Amount of cache is 32K, Amount of SRAM is 0K;
    values of type Cache.L2Size// Level 2 cache size type definition
        const Cache.L2Size_0K// L2 is all SRAM;
        const Cache.L2Size_32K// Amount of cache is 32K;
        const Cache.L2Size_64K// Amount of cache is 64K;
        const Cache.L2Size_128K// Amount of cache is 128K;
        const Cache.L2Size_256K// Amount of cache is 256K;
        const Cache.L2Size_512K// Amount of cache is 512K;
        const Cache.L2Size_1024K// Amount of cache is 1024K;
    values of type Cache.Mar// MAR register setting type definition
        const Cache.Mar_DISABLE// The Permit Copy bit of MAR register is disabled;
        const Cache.Mar_ENABLE// The Permit Copy bit of MAR register is enabled;
    values of type Cache.Mode// Lists of cache modes for L1/L2 caches
        const Cache.Mode_FREEZE// No new cache lines are allocated;
        const Cache.Mode_BYPASS// All access result in long-distance access;
        const Cache.Mode_NORMAL// Normal operation of cache;
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
    var obj = new Cache.Size// Structure for specifying all cache sizes;
        obj.l1pSize// L1 Program cache size = Cache.L1Size ...
        obj.l1dSize// L1 Data data size = Cache.L1Size ...
        obj.l2Size// L2 cache size = Cache.L2Size ...
module-wide config parameters
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     Cache.getMarMeta// Gets the current MAR value for the specified base address(Ptr baseAddr) returns UInt32
     Cache.setMarMeta// Set MAR register(s) that corresponds to the specified address range(Ptr baseAddr, SizeT byteSize, UInt32 value) returns Void
const Cache.PC
index URL

Permit Caching

XDCscript usage meta-domain
const Cache.PC = 1;
C SYNOPSIS
Cache_PC
const Cache.PCX
index URL

Permit caching in external cache

XDCscript usage meta-domain
const Cache.PCX = 4;
C SYNOPSIS
Cache_PCX
const Cache.PFX
index URL

Prefetchable by external engines

XDCscript usage meta-domain
const Cache.PFX = 8;
C SYNOPSIS
Cache_PFX
const Cache.WTE
index URL

Write through enabled

XDCscript usage meta-domain
const Cache.WTE = 2;
C SYNOPSIS
Cache_WTE
enum Cache.L1Size
index URL

Level 1 cache size type definition. Can be used for both L1D & L1P

XDCscript usage meta-domain
values of type Cache.L1Size
    const Cache.L1Size_0K;
    // Amount of cache is 0K, Amount of SRAM is 32K
    const Cache.L1Size_4K;
    // Amount of cache is 4K, Amount of SRAM is 28K
    const Cache.L1Size_8K;
    // Amount of cache is 8K, Amount of SRAM is 24K
    const Cache.L1Size_16K;
    // Amount of cache is 16K, Amount of SRAM is 16K
    const Cache.L1Size_32K;
    // Amount of cache is 32K, Amount of SRAM is 0K
C SYNOPSIS
Cache_L1Size
enum Cache.L2Size
index URL

Level 2 cache size type definition

XDCscript usage meta-domain
values of type Cache.L2Size
    const Cache.L2Size_0K;
    // L2 is all SRAM
    const Cache.L2Size_32K;
    // Amount of cache is 32K
    const Cache.L2Size_64K;
    // Amount of cache is 64K
    const Cache.L2Size_128K;
    // Amount of cache is 128K
    const Cache.L2Size_256K;
    // Amount of cache is 256K
    const Cache.L2Size_512K;
    // Amount of cache is 512K
    const Cache.L2Size_1024K;
    // Amount of cache is 1024K
C SYNOPSIS
Cache_L2Size
enum Cache.Mar
index URL

MAR register setting type definition

XDCscript usage meta-domain
values of type Cache.Mar
    const Cache.Mar_DISABLE;
    // The Permit Copy bit of MAR register is disabled
    const Cache.Mar_ENABLE;
    // The Permit Copy bit of MAR register is enabled
C SYNOPSIS
Cache_Mar
enum Cache.Mode
index URL

Lists of cache modes for L1/L2 caches

XDCscript usage meta-domain
values of type Cache.Mode
    const Cache.Mode_FREEZE;
    // No new cache lines are allocated
    const Cache.Mode_BYPASS;
    // All access result in long-distance access
    const Cache.Mode_NORMAL;
    // Normal operation of cache
C SYNOPSIS
Cache_Mode
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
struct Cache.Size
index URL

Structure for specifying all cache sizes

XDCscript usage meta-domain
var obj = new Cache.Size;
    obj.l1pSize = Cache.L1Size ...
    // L1 Program cache size
    obj.l1dSize = Cache.L1Size ...
    // L1 Data data size
    obj.l2Size = Cache.L2Size ...
    // L2 cache size
C SYNOPSIS
Cache_Size
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly Cache.getMarMeta() // module-wide
index URL

Gets the current MAR value for the specified base address

XDCscript usage meta-domain
Cache.getMarMeta(Ptr baseAddr) returns UInt32
ARGUMENTS
baseAddr — address for which MAR value is requested
RETURNS
MAR value for specified address
metaonly Cache.setMarMeta() // module-wide
index URL

Set MAR register(s) that corresponds to the specified address range

XDCscript usage meta-domain
Cache.setMarMeta(Ptr baseAddr, SizeT byteSize, UInt32 value) returns Void
ARGUMENTS
baseAddr — start address for which to set MAR
byteSize — size (in bytes) of memory block
value — value for setting MAR register
DETAILS
The 'pc' ("Permit Caching") field is enabled for all memory regions in the device platform. Only set the fields of the Mar structure which need to be modified. Any field not set retains its reset value.
generated on Fri, 17 Jun 2011 00:22:55 GMT


package ti.sysbios.family.c66.tci66xx
index URL
XDCspec declarations sourced in ti/sysbios/family/c66/tci66xx/package.xdc
package ti.sysbios.family.c66.tci66xx [2, 0, 0, 0] {
    module CpIntc;
    // Common Platform Interrupt Controller Manager
}
generated on Fri, 17 Jun 2011 00:22:56 GMT


module ti.sysbios.family.c66.tci66xx.CpIntc
index URL

Common Platform Interrupt Controller Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages the CP_INTC hardware. This module supports enabling and disabling of both system and host interrupts. This module also supports mapping system interrupts to host interrupts and host interrupts to Hwis or to the EventCombiner. These functionality are supported statically and during runtime for CP_INTCs connected to the GEM interrupt controller but only during runtime for other CP_INTCs. There is a dispatch function for handling GEM hardware interrupts triggered by a system interrupt. The Global Enable Register is enabled by default in the module startup function. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c66/tci66xx/CpIntc.xdc
#include <ti/sysbios/family/c66/tci66xx/CpIntc.h>
Functions
Void | CpIntc_clearSysInt// Clears the system interrupt(UInt id, UInt sysInt);
Void | CpIntc_disableAllHostInts// Disables all host interrupts(UInt id);
Void | CpIntc_disableHostInt// Disables the host interrupts(UInt id, UInt hostInt);
Void | CpIntc_disableSysInt// Disables the system interrupt(UInt id, UInt sysInt);
Void | CpIntc_dispatch// The Interrupt service routine handler for CP_INTC events(UInt hostInt);
Void | CpIntc_dispatchPlug// Configures a CpIntc ISR dispatch entry(UInt sysInt, CpIntc_FuncPtr fxn, UArg arg, Bool unmask);
Void | CpIntc_enableAllHostInts// Enables all host interrupts(UInt id);
Void | CpIntc_enableHostInt// Enables the host interrupt(UInt id, UInt hostInt);
Void | CpIntc_enableSysInt// Enables the system interrupt(UInt id, UInt sysInt);
Int | CpIntc_getEventId// Returns the event id associated with the host interrupt(UInt hostInt);
Void | CpIntc_mapSysIntToHostInt// Maps a system interrupt to a host interrupt(UInt id, UInt sysInt, UInt hostInt);
Void | CpIntc_postSysInt// Triggers the system interrupt(UInt id, UInt sysInt);
Functions common to all target modules
 | CpIntc_Module_getMask// Returns the diagnostics mask for this module, CpIntc_Module_hasMask// Test whether this module has a diagnostics mask, CpIntc_Module_heap// The heap from which this module allocates memory, CpIntc_Module_id// Get this module's unique id, CpIntc_Module_setMask// Set the diagnostics mask for this module, CpIntc_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*CpIntc_FuncPtr// CpIntc dispatcher function type definition)(UArg);
typedef struct | CpIntc_RegisterMap// Common Platform Interrupt Controller ...
Constants
extern const Error_Id | CpIntc_E_unpluggedSysInt// Error raised when an unplug system interrupt is executed;
DETAILS
This module manages the CP_INTC hardware. This module supports enabling and disabling of both system and host interrupts. This module also supports mapping system interrupts to host interrupts and host interrupts to Hwis or to the EventCombiner. These functionality are supported statically and during runtime for CP_INTCs connected to the GEM interrupt controller but only during runtime for other CP_INTCs. There is a dispatch function for handling GEM hardware interrupts triggered by a system interrupt. The Global Enable Register is enabled by default in the module startup function.
System interrupts are those interrupts generated by a hardware module in the system. These interrupts are inputs into CP_INTC. Host interrupts are the output interrupts of CP_INTC. There is a one-to-one mapping between channels and host interrupts therefore, the term "host interrupt" is also used for channels.
This modules does not support prioritization, nesting, and vectorization.
typedef CpIntc_FuncPtr
index URL

CpIntc dispatcher function type definition

C synopsis target-domain
typedef Void (*CpIntc_FuncPtr)(UArg);
struct CpIntc_RegisterMap
index URL

Common Platform Interrupt Controller

C synopsis target-domain
typedef struct CpIntc_RegisterMap {
    UInt32 REV;
    // 0x00 Revision Register
    UInt32 CR;
    // 0x04 Control Register
    UInt32 RES_08;
    // 0x08 reserved
    UInt32 HCR;
    // 0x0C Host Control Register
    UInt32 GER;
    // 0x10 Global Enable Register
    UInt32 RES_14;
    // 0x14 reserved
    UInt32 RES_18;
    // 0x18 reserved
    UInt32 GNLR;
    // 0x1C Global Nesting Level Register
    UInt32 SISR;
    // 0x20 Status Index Set Register
    UInt32 SICR;
    // 0x24 Status Index Clear Register
    UInt32 EISR;
    // 0x28 Enable Index Set Register
    UInt32 EICR;
    // 0x2C Enable Index Clear Register
    UInt32 GWER;
    // 0x30 Global Wakeup Enable Register
    UInt32 HIEISR;
    // 0x34 Host Int Enable Index Set Register
    UInt32 HIDISR;
    // 0x38 Host Int Disable Index Set Register
    UInt32 RES_3C;
    // 0x3C reserved
    UInt32 PPR;
    // 0x40 Pacer Prescale Register
    UInt32 RES_44;
    // 0x44 reserved
    UInt32 RES_48;
    // 0x48 reserved
    UInt32 RES_4C;
    // 0x4C reserved
    Ptr *VBR;
    // 0x50 Vector Base Register
    UInt32 VSR;
    // 0x54 Vector Size Register
    Ptr VNR;
    // 0x58 Vector Null Register
    UInt32 RES_5C[9];
    // 0x5C-0x7C reserved
    Int32 GPIR;
    // 0x80 Global Prioritized Index Register
    Ptr *GPVR;
    // 0x84 Global Prioritized Vector Register
    UInt32 RES_88;
    // 0x88 reserved
    UInt32 RES_8C;
    // 0x8C reserved
    UInt32 GSIER;
    // 0x90 Global Secure Interrupt Enable Register
    UInt32 SPIR;
    // 0x94 Secure Prioritized Index Register
    UInt32 RES_98[26];
    // 0x98-0xFC reserved
    UInt32 PPMR[64];
    // 0x100-0x1FC Pacer Parameter/Map Registers
    UInt32 SRSR[32];
    // 0x200-0x27C Status Raw/Set Registers
    UInt32 SECR[32];
    // 0x280-0x2FC Status Enabled/Clear Registers
    UInt32 ESR[32];
    // 0x300-0x37C Enable Set Registers
    UInt32 ECR[32];
    // 0x380-0x3FC Enable Clear Registers
    UInt8 CMR[1024];
    // 0x400-0x7FC Channel Map Registers
    UInt8 HIMR[256];
    // 0x800-0x8FC Host Interrupt Map Registers
    UInt32 HIPIR[256];
    // 0x900-0xCFC Host Interrupt Pri Index Registers
    UInt32 PR[32];
    // 0xD00-0xD7C Polarity Registers
    UInt32 TR[32];
    // 0xD80-0xDFC Type Registers
    UInt32 WER[64];
    // 0xE00-0xEFC Wakeup Enable Registers
    UInt32 DSR[64];
    // 0xF00-0xFFC Debug Select Registers
    UInt32 SER[32];
    // 0x1000-0x107C Secure Enable Registers
    UInt32 SDR[32];
    // 0x1080-0x10FC Secure Disable Registers
    UInt32 HINLR[256];
    // 0x1100-0x14FC Host Interrupt Nesting Level Registers
    UInt32 HIER[8];
    // 0x1500-0x151F Host Interrupt Enable Registers
    UInt32 RES1520[56];
    // 0x1520-0x15fC Reserved
    Ptr *HIPVR[256];
    // 0x1600-0x19fC Host Interrupt Prioritized Vector
    UInt32 RES1A00[384];
    // 0x1A00-0x1FFC Reserved
} CpIntc_RegisterMap;
config CpIntc_E_unpluggedSysInt // module-wide
index URL

Error raised when an unplug system interrupt is executed

C synopsis target-domain
extern const Error_Id CpIntc_E_unpluggedSysInt;
CpIntc_clearSysInt() // module-wide
index URL

Clears the system interrupt

C synopsis target-domain
Void CpIntc_clearSysInt(UInt id, UInt sysInt);
ARGUMENTS
id — Cp_Intc number
sysInt — system interrupt number
DETAILS
Writes the system interrupt number to the System Interrupt Status Indexed Clear Register.
CpIntc_disableAllHostInts() // module-wide
index URL

Disables all host interrupts

C synopsis target-domain
Void CpIntc_disableAllHostInts(UInt id);
ARGUMENTS
id — Cp_Intc number
DETAILS
Writes a 0 to the Global Enable Register. It does not override the individual host interrupt enable/disable bits.
CpIntc_disableHostInt() // module-wide
index URL

Disables the host interrupts

C synopsis target-domain
Void CpIntc_disableHostInt(UInt id, UInt hostInt);
ARGUMENTS
id — Cp_Intc number
hostInt — host interrupt number
DETAILS
Writes the host interrupt number to the Host Interrupt Enable Index Clear Register.
CpIntc_disableSysInt() // module-wide
index URL

Disables the system interrupt

C synopsis target-domain
Void CpIntc_disableSysInt(UInt id, UInt sysInt);
ARGUMENTS
id — Cp_Intc number
sysInt — system interrupt number
DETAILS
Writes the system interrupt number to the System Interrupt Enable Indexed Clear Register.
CpIntc_dispatch() // module-wide
index URL

The Interrupt service routine handler for CP_INTC events

C synopsis target-domain
Void CpIntc_dispatch(UInt hostInt);
ARGUMENTS
hostInt — host interrupt number
DETAILS
It is used internally, but can also be used by the user.
CpIntc_dispatchPlug() // module-wide
index URL

Configures a CpIntc ISR dispatch entry

C synopsis target-domain
Void CpIntc_dispatchPlug(UInt sysInt, CpIntc_FuncPtr fxn, UArg arg, Bool unmask);
ARGUMENTS
sysInt — system interrupt number
fxn — function
arg — argument to function
unmask — bool to unmask interrupt
DETAILS
Plugs the function and argument for the specified system interrupt. Also enables the system interrupt if 'unmask' is set to 'true'. Function does not map the system interrupt to a Hwi interrupt.
CpIntc_enableAllHostInts() // module-wide
index URL

Enables all host interrupts

C synopsis target-domain
Void CpIntc_enableAllHostInts(UInt id);
ARGUMENTS
id — Cp_Intc number
DETAILS
Writes a 1 to the Global Enable Register. It does not override the individual host interrupt enable/disable bits.
CpIntc_enableHostInt() // module-wide
index URL

Enables the host interrupt

C synopsis target-domain
Void CpIntc_enableHostInt(UInt id, UInt hostInt);
ARGUMENTS
id — Cp_Intc number
hostInt — host interrupt number
DETAILS
Writes the host interrupt number to the Host Interrupt Enable Indexed Set Register.
CpIntc_enableSysInt() // module-wide
index URL

Enables the system interrupt

C synopsis target-domain
Void CpIntc_enableSysInt(UInt id, UInt sysInt);
ARGUMENTS
id — Cp_Intc number
sysInt — system interrupt number
DETAILS
Writes the system interrupt number to the System Interrupt Enable Indexed Set Register.
CpIntc_getEventId() // module-wide
index URL

Returns the event id associated with the host interrupt

C synopsis target-domain
Int CpIntc_getEventId(UInt hostInt);
ARGUMENTS
hostInt — host interrupt number
CpIntc_mapSysIntToHostInt() // module-wide
index URL

Maps a system interrupt to a host interrupt

C synopsis target-domain
Void CpIntc_mapSysIntToHostInt(UInt id, UInt sysInt, UInt hostInt);
ARGUMENTS
id — Cp_Intc number
sysInt — system interrupt number
hostInt — host interrupt number
DETAILS
Writes the Channel Map Register to map a system interrupt to a channel. There is a 1 to 1 mapping between channels and host interrupts.
CpIntc_postSysInt() // module-wide
index URL

Triggers the system interrupt

C synopsis target-domain
Void CpIntc_postSysInt(UInt id, UInt sysInt);
ARGUMENTS
id — Cp_Intc number
sysInt — system interrupt number
DETAILS
Writes the system interrupt number to the System Interrupt Status Index Set Register. Used for diagnostic and test purposes only.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId CpIntc_Module_id();
// Get this module's unique id
Bool CpIntc_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle CpIntc_Module_heap();
// The heap from which this module allocates memory
Bool CpIntc_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 CpIntc_Module_getMask();
// Returns the diagnostics mask for this module
Void CpIntc_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c66/tci66xx/CpIntc.xdc
var CpIntc = xdc.useModule('ti.sysbios.family.c66.tci66xx.CpIntc');
module-wide constants & types
    var obj = new CpIntc.RegisterMap// Common Platform Interrupt Controller;
        obj.REV// 0x00 Revision Register = UInt32 ...
        obj.CR// 0x04 Control Register = UInt32 ...
        obj.RES_08// 0x08 reserved = UInt32 ...
        obj.HCR// 0x0C Host Control Register = UInt32 ...
        obj.GER// 0x10 Global Enable Register = UInt32 ...
        obj.RES_14// 0x14 reserved = UInt32 ...
        obj.RES_18// 0x18 reserved = UInt32 ...
        obj.GNLR// 0x1C Global Nesting Level Register = UInt32 ...
        obj.SISR// 0x20 Status Index Set Register = UInt32 ...
        obj.SICR// 0x24 Status Index Clear Register = UInt32 ...
        obj.EISR// 0x28 Enable Index Set Register = UInt32 ...
        obj.EICR// 0x2C Enable Index Clear Register = UInt32 ...
        obj.GWER// 0x30 Global Wakeup Enable Register = UInt32 ...
        obj.HIEISR// 0x34 Host Int Enable Index Set Register = UInt32 ...
        obj.HIDISR// 0x38 Host Int Disable Index Set Register = UInt32 ...
        obj.RES_3C// 0x3C reserved = UInt32 ...
        obj.PPR// 0x40 Pacer Prescale Register = UInt32 ...
        obj.RES_44// 0x44 reserved = UInt32 ...
        obj.RES_48// 0x48 reserved = UInt32 ...
        obj.RES_4C// 0x4C reserved = UInt32 ...
        obj.VBR// 0x50 Vector Base Register = Ptr* ...
        obj.VSR// 0x54 Vector Size Register = UInt32 ...
        obj.VNR// 0x58 Vector Null Register = Ptr ...
        obj.RES_5C// 0x5C-0x7C reserved = UInt32[9] ...
        obj.GPIR// 0x80 Global Prioritized Index Register = Int32 ...
        obj.GPVR// 0x84 Global Prioritized Vector Register = Ptr* ...
        obj.RES_88// 0x88 reserved = UInt32 ...
        obj.RES_8C// 0x8C reserved = UInt32 ...
        obj.GSIER// 0x90 Global Secure Interrupt Enable Register = UInt32 ...
        obj.SPIR// 0x94 Secure Prioritized Index Register = UInt32 ...
        obj.RES_98// 0x98-0xFC reserved = UInt32[26] ...
        obj.PPMR// 0x100-0x1FC Pacer Parameter/Map Registers = UInt32[64] ...
        obj.SRSR// 0x200-0x27C Status Raw/Set Registers = UInt32[32] ...
        obj.SECR// 0x280-0x2FC Status Enabled/Clear Registers = UInt32[32] ...
        obj.ESR// 0x300-0x37C Enable Set Registers = UInt32[32] ...
        obj.ECR// 0x380-0x3FC Enable Clear Registers = UInt32[32] ...
        obj.CMR// 0x400-0x7FC Channel Map Registers = UInt8[1024] ...
        obj.HIMR// 0x800-0x8FC Host Interrupt Map Registers = UInt8[256] ...
        obj.HIPIR// 0x900-0xCFC Host Interrupt Pri Index Registers = UInt32[256] ...
        obj.PR// 0xD00-0xD7C Polarity Registers = UInt32[32] ...
        obj.TR// 0xD80-0xDFC Type Registers = UInt32[32] ...
        obj.WER// 0xE00-0xEFC Wakeup Enable Registers = UInt32[64] ...
        obj.DSR// 0xF00-0xFFC Debug Select Registers = UInt32[64] ...
        obj.SER// 0x1000-0x107C Secure Enable Registers = UInt32[32] ...
        obj.SDR// 0x1080-0x10FC Secure Disable Registers = UInt32[32] ...
        obj.HINLR// 0x1100-0x14FC Host Interrupt Nesting Level Registers = UInt32[256] ...
        obj.HIER// 0x1500-0x151F Host Interrupt Enable Registers = UInt32[8] ...
        obj.RES1520// 0x1520-0x15fC Reserved = UInt32[56] ...
        obj.HIPVR// 0x1600-0x19fC Host Interrupt Prioritized Vector = Ptr*[256] ...
        obj.RES1A00// 0x1A00-0x1FFC Reserved = UInt32[384] ...
    var obj = new CpIntc.SysIntObj// System Interrupt Object;
        obj.fxn = Void(*)(UArg) ...
        obj.arg = UArg ...
        obj.hostInt = UInt8 ...
        obj.enable = Bool ...
module-wide config parameters
     CpIntc.E_unpluggedSysInt// Error raised when an unplug system interrupt is executed = Error.Desc {
        msg: "E_unpluggedSysInt: System Interrupt# %d is unplugged"
    };
     CpIntc.common$// Common module configuration parameters = Types.Common$ undefined;
     CpIntc.sysInts// Use for configuring the system interrupts = CpIntc.SysIntObj[] undefined;
module-wide functions
     CpIntc.getEventIdMeta// Returns the GEM event id associated with the host interrupt(UInt hostInt) returns Int
     CpIntc.mapHostIntToEventCombinerMeta// Maps the host interrupt to the Event Combiner(UInt hostInt) returns Void
     CpIntc.mapHostIntToHwiMeta// Maps the host interrupt to a Hwi(UInt hostInt, UInt hwiNum) returns Void
struct CpIntc.RegisterMap
index URL

Common Platform Interrupt Controller

XDCscript usage meta-domain
var obj = new CpIntc.RegisterMap;
    obj.REV = UInt32 ...
    // 0x00 Revision Register
    obj.CR = UInt32 ...
    // 0x04 Control Register
    obj.RES_08 = UInt32 ...
    // 0x08 reserved
    obj.HCR = UInt32 ...
    // 0x0C Host Control Register
    obj.GER = UInt32 ...
    // 0x10 Global Enable Register
    obj.RES_14 = UInt32 ...
    // 0x14 reserved
    obj.RES_18 = UInt32 ...
    // 0x18 reserved
    obj.GNLR = UInt32 ...
    // 0x1C Global Nesting Level Register
    obj.SISR = UInt32 ...
    // 0x20 Status Index Set Register
    obj.SICR = UInt32 ...
    // 0x24 Status Index Clear Register
    obj.EISR = UInt32 ...
    // 0x28 Enable Index Set Register
    obj.EICR = UInt32 ...
    // 0x2C Enable Index Clear Register
    obj.GWER = UInt32 ...
    // 0x30 Global Wakeup Enable Register
    obj.HIEISR = UInt32 ...
    // 0x34 Host Int Enable Index Set Register
    obj.HIDISR = UInt32 ...
    // 0x38 Host Int Disable Index Set Register
    obj.RES_3C = UInt32 ...
    // 0x3C reserved
    obj.PPR = UInt32 ...
    // 0x40 Pacer Prescale Register
    obj.RES_44 = UInt32 ...
    // 0x44 reserved
    obj.RES_48 = UInt32 ...
    // 0x48 reserved
    obj.RES_4C = UInt32 ...
    // 0x4C reserved
    obj.VBR = Ptr* ...
    // 0x50 Vector Base Register
    obj.VSR = UInt32 ...
    // 0x54 Vector Size Register
    obj.VNR = Ptr ...
    // 0x58 Vector Null Register
    obj.RES_5C = UInt32[9] ...
    // 0x5C-0x7C reserved
    obj.GPIR = Int32 ...
    // 0x80 Global Prioritized Index Register
    obj.GPVR = Ptr* ...
    // 0x84 Global Prioritized Vector Register
    obj.RES_88 = UInt32 ...
    // 0x88 reserved
    obj.RES_8C = UInt32 ...
    // 0x8C reserved
    obj.GSIER = UInt32 ...
    // 0x90 Global Secure Interrupt Enable Register
    obj.SPIR = UInt32 ...
    // 0x94 Secure Prioritized Index Register
    obj.RES_98 = UInt32[26] ...
    // 0x98-0xFC reserved
    obj.PPMR = UInt32[64] ...
    // 0x100-0x1FC Pacer Parameter/Map Registers
    obj.SRSR = UInt32[32] ...
    // 0x200-0x27C Status Raw/Set Registers
    obj.SECR = UInt32[32] ...
    // 0x280-0x2FC Status Enabled/Clear Registers
    obj.ESR = UInt32[32] ...
    // 0x300-0x37C Enable Set Registers
    obj.ECR = UInt32[32] ...
    // 0x380-0x3FC Enable Clear Registers
    obj.CMR = UInt8[1024] ...
    // 0x400-0x7FC Channel Map Registers
    obj.HIMR = UInt8[256] ...
    // 0x800-0x8FC Host Interrupt Map Registers
    obj.HIPIR = UInt32[256] ...
    // 0x900-0xCFC Host Interrupt Pri Index Registers
    obj.PR = UInt32[32] ...
    // 0xD00-0xD7C Polarity Registers
    obj.TR = UInt32[32] ...
    // 0xD80-0xDFC Type Registers
    obj.WER = UInt32[64] ...
    // 0xE00-0xEFC Wakeup Enable Registers
    obj.DSR = UInt32[64] ...
    // 0xF00-0xFFC Debug Select Registers
    obj.SER = UInt32[32] ...
    // 0x1000-0x107C Secure Enable Registers
    obj.SDR = UInt32[32] ...
    // 0x1080-0x10FC Secure Disable Registers
    obj.HINLR = UInt32[256] ...
    // 0x1100-0x14FC Host Interrupt Nesting Level Registers
    obj.HIER = UInt32[8] ...
    // 0x1500-0x151F Host Interrupt Enable Registers
    obj.RES1520 = UInt32[56] ...
    // 0x1520-0x15fC Reserved
    obj.HIPVR = Ptr*[256] ...
    // 0x1600-0x19fC Host Interrupt Prioritized Vector
    obj.RES1A00 = UInt32[384] ...
    // 0x1A00-0x1FFC Reserved
C SYNOPSIS
CpIntc_RegisterMap
metaonly struct CpIntc.SysIntObj
index URL

System Interrupt Object

XDCscript usage meta-domain
var obj = new CpIntc.SysIntObj;
    obj.fxn = Void(*)(UArg) ...
    obj.arg = UArg ...
    obj.hostInt = UInt8 ...
    obj.enable = Bool ...
config CpIntc.E_unpluggedSysInt // module-wide
index URL

Error raised when an unplug system interrupt is executed

XDCscript usage meta-domain
CpIntc.E_unpluggedSysInt = Error.Desc {
    msg: "E_unpluggedSysInt: System Interrupt# %d is unplugged"
};
C SYNOPSIS
CpIntc_E_unpluggedSysInt
metaonly config CpIntc.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
CpIntc.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config CpIntc.sysInts // module-wide
index URL

Use for configuring the system interrupts

XDCscript usage meta-domain
CpIntc.sysInts = CpIntc.SysIntObj[] undefined;
DETAILS
During static configuration this array can be used to configure the function to execute when a system interrupt is triggered, the arg to the function, the host interrupt to which the system interrupt is mapped too, and whether to enable the system interrupt.
metaonly CpIntc.getEventIdMeta() // module-wide
index URL

Returns the GEM event id associated with the host interrupt

XDCscript usage meta-domain
CpIntc.getEventIdMeta(UInt hostInt) returns Int
ARGUMENTS
hostInt — host interrupt number
DETAILS
If no event id is associated with the host interrupt, the value -1 will be returned.
metaonly CpIntc.mapHostIntToEventCombinerMeta() // module-wide
index URL

Maps the host interrupt to the Event Combiner

XDCscript usage meta-domain
CpIntc.mapHostIntToEventCombinerMeta(UInt hostInt) returns Void
ARGUMENTS
hostInt — host interrupt number
DETAILS
The GEM event corresponding to the 'hostInt' in the Event Combiner will be unmask but the event group will not be dispatched. The Event Combiner function for this event will be set to the dispatch function and argument set to 'hostInt'. The event group must be dispatched from the Event Combiner Module.
metaonly CpIntc.mapHostIntToHwiMeta() // module-wide
index URL

Maps the host interrupt to a Hwi

XDCscript usage meta-domain
CpIntc.mapHostIntToHwiMeta(UInt hostInt, UInt hwiNum) returns Void
ARGUMENTS
hostInt — host interrupt number
hwiNum — Hwi number
DETAILS
A Hwi object will be created with the 'hwiNum', the function set as the dispatch function and argument set to 'hostInt'.
generated on Fri, 17 Jun 2011 00:22:56 GMT


package ti.sysbios.family.c67p
index URL

Contains specifications for the C64 specific SYS/BIOS functions

The link below provides SYS/BIOS C6x register usage information: [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/c67p/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.c67p [2, 0, 0, 0] {
    module Cache;
    // Cache Module
    module Hwi;
    // C67+ Hardware Interrupt Support Module
    module Settings;
    // Device/Family-specific delegate assignment module for C67P target devices
    module Timer;
    // Timer Peripherals Manager for c67p family
    module TimestampProvider;
}
DETAILS
The link below provides SYS/BIOS C6x register usage information:
SYS/BIOS C6x Register Usage
generated on Fri, 17 Jun 2011 00:22:59 GMT


module ti.sysbios.family.c67p.Cache
index URL

Cache Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Unconstrained Functions All functions [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c67p/Cache.xdc
#include <ti/sysbios/family/c67p/Cache.h>
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Cache_Type// Lists of bitmask cache types ...
Constants
extern const Bool | Cache_enableCache// Enable the cache? The Default is true;
DETAILS
Unconstrained Functions All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
config Cache_enableCache // module-wide
index URL

Enable the cache? The Default is true

C synopsis target-domain
extern const Bool Cache_enableCache;
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c67p/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.family.c67p.Cache');
module-wide constants & types
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
module-wide config parameters
     Cache.enableCache// Enable the cache? The Default is true = Bool true;
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
config Cache.enableCache // module-wide
index URL

Enable the cache? The Default is true

XDCscript usage meta-domain
Cache.enableCache = Bool true;
C SYNOPSIS
Cache_enableCache
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:59 GMT


module ti.sysbios.family.c67p.Hwi
index URL

C67+ Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides C67+ family-specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/c67p/Hwi.xdc
#include <ti/sysbios/family/c67p/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Void | Hwi_eventMap// Map Event to Interrupt(Int intNum, Int eventId);
Hwi_Handle | Hwi_getHandle// Returns Hwi_handle associated with intNum(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called(Bits16 mask);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// C64 supports 16 interrupts (Int)16
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
DETAILS
This Hwi module provides C67+ family-specific implementations of the APIs defined in IHwi.
Additional C67+ device-specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | N
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableIER | Y | Y | Y | Y | N
enableInterrupt | Y | Y | Y | Y | N
eventMap | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | N
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

C64 supports 16 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)16
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to disable
RETURNS
previous IER settings bitmask
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to enable
RETURNS
previous IER settings bitmask
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_eventMap() // module-wide
index URL

Map Event to Interrupt

C synopsis target-domain
Void Hwi_eventMap(Int intNum, Int eventId);
ARGUMENTS
intNum — interrupt number
eventId — event ID
DETAILS
Function maps an event to an interrupt vector so that the event will be the source of the interrupt of the vector.
      // Maps GEM event #65 as the interrupt source of int vector #7
      Hwi_eventMap(7, 65);
Hwi_getHandle() // module-wide
index URL

Returns Hwi_handle associated with intNum

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — interrupt number
RETURNS
handle associated with intNum
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — bitmask of interrupts to restore
RETURNS
previous IER settings bitmask
DETAILS
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c67p/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.c67p.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// C64 supports 16 interrupts = 16;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts;
        obj.intNum = Int ...
        obj.fxn// "Hwi_plug'd" ISR function = Void(*)(Void) ...
        obj.enableInt = Bool ...
        obj.eventId = Int ...
module-wide config parameters
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts = Hwi.NonDispatchedInterrupt[string] undefined;
     Hwi.resetVectorAddress// Alternate reset vector address. Default is undefined = Ptr undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.eventMapMeta// Statically map Event to Interrupt(Int intNum, Int eventId) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Void(*)(Void) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

C64 supports 16 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 16;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

non-dispatched interrupt object. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    obj.fxn = Void(*)(Void) ...
    // "Hwi_plug'd" ISR function
    obj.enableInt = Bool ...
    obj.eventId = Int ...
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

non-dispatched interrupt array. provided so that XGCONF users can easily plug non-dispatched interrupts

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
metaonly config Hwi.resetVectorAddress // module-wide
index URL

Alternate reset vector address. Default is undefined

XDCscript usage meta-domain
Hwi.resetVectorAddress = Ptr undefined;
DETAILS
if initialized by the user then an additional reset vector is created and placed in the ".resetVector" section. To place the .resetVector section into a specific memory section, add the following command to your config script:
  Program.sectMap[".resetVector"] = YourMemorySection;
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.eventMapMeta() // module-wide
index URL

Statically map Event to Interrupt

XDCscript usage meta-domain
Hwi.eventMapMeta(Int intNum, Int eventId) returns Void
ARGUMENTS
intNum — interrupt number
eventId — pointer to ISR function
DETAILS
Function maps an event to an interrupt number so that the event will be the source of the interrupt of the vector.
      // Maps GEM event #65 as the interrupt source of int vector #7
      Hwi.eventMapMeta(7, 65);
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(Void) fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:22:59 GMT


module ti.sysbios.family.c67p.Settings

metaonly module ti.sysbios.family.c67p.Settings
index URL

Device/Family-specific delegate assignment module for C67P target devices

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/c67p/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.c67p.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:22:59 GMT


module ti.sysbios.family.c67p.Timer
index URL

Timer Peripherals Manager for c67p family

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c67p/Timer.xdc
#include <ti/sysbios/family/c67p/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Number of timer peripherals on chip (Int)2
Typedefs
typedef struct | Timer_Control// Timer Configuration struct ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = Timer_ANY;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)2
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Control
index URL

Timer Configuration struct

C synopsis target-domain
typedef struct Timer_Control {
    Bool cos;
    // 0=stop in debug mode; 1=continue in debug mode
} Timer_Control;
FIELDS
cos — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

C synopsis target-domain
extern const Error_Id Timer_E_invalidHwiMask;
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_Control controlRegInit;
    // Control register configuration. Default cos=0
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    Int intNum;
    // Hwi intNum to be used by Timer
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_controlRegInit // instance
index URL

Control register configuration. Default cos=0

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Control controlRegInit;
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_intNum // instance
index URL

Hwi intNum to be used by Timer

C synopsis target-domain
struct Timer_Params {
     ...
    Int intNum;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires.
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/c67p/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.c67p.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Number of timer peripherals on chip = 2;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Control// Timer Configuration struct;
        obj.cos// 0=stop in debug mode; 1=continue in debug mode = Bool ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidHwiMask// Error raised when Hwi Params has mask where self is turned on = Error.Desc {
        msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.controlRegInit// Control register configuration. Default cos=0 = Timer.Control {
            cos: 0
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.intNum// Hwi intNum to be used by Timer = Int -1;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Number of timer peripherals on chip

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 2;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Control
index URL

Timer Configuration struct

XDCscript usage meta-domain
var obj = new Timer.Control;
    obj.cos = Bool ...
    // 0=stop in debug mode; 1=continue in debug mode
FIELDS
cos — When true timer stops counting during emulation halt. When false timer continues to count during emulation halt.
C SYNOPSIS
Timer_Control
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidHwiMask // module-wide
index URL

Error raised when Hwi Params has mask where self is turned on

XDCscript usage meta-domain
Timer.E_invalidHwiMask = Error.Desc {
    msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
};
DETAILS
This is not allowed because the timers on this platform do not support one-shot mode and a stub is used to stop it. Another timer interrupt cannot go off when the ISR is running.
C SYNOPSIS
Timer_E_invalidHwiMask
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.controlRegInit = Timer.Control {
    // Control register configuration. Default cos=0
        cos: 0
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.intNum = Int -1;
    // Hwi intNum to be used by Timer
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.controlRegInit // instance
index URL

Control register configuration. Default cos=0

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.controlRegInit = Timer.Control {
    cos: 0
};
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.intNum // instance
index URL

Hwi intNum to be used by Timer

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.intNum = Int -1;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:59 GMT


module ti.sysbios.family.c67p.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/c67p/TimestampProvider.xdc
#include <ti/sysbios/family/c67p/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id. Max id value is 2;
extern const Bool | TimestampProvider_useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module;
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
config TimestampProvider_useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
This parameter overrides the timeId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/c67p/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.c67p.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id. Max id value is 2 = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module = Bool true;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool true;
DETAILS
This parameter overrides the timeId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:59 GMT


package ti.sysbios.family.msp430
index URL

Contains specifications for the msp430 family-specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/family/msp430/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.msp430 [1, 0, 0, 0] {
    module ClockFreqs;
    // ClockFreqs Module
    module Hwi;
    // MSP430 Hardware Interrupt Manager
    module Power;
    // Power Manager Module
    module Settings;
    module TaskSupport;
    // MSP430 Task Support Module
    module Timer;
    // MSP430 Timer Peripherals Manager
    module TimestampProvider;
    // MSP430 Timestamp Provider
}
generated on Fri, 17 Jun 2011 00:23:07 GMT


module ti.sysbios.family.msp430.ClockFreqs
index URL

ClockFreqs Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module is used to define the ACLK and SMCLK frequencies in effect when BIOS_start() is called at the end of main(). It also provides a function that can be called by the application at runtime to query individual clock frequencies. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/msp430/ClockFreqs.xdc
#include <ti/sysbios/family/msp430/ClockFreqs.h>
Functions
UInt32 | ClockFreqs_getFrequency// Get the frequency for a clock(ClockFreqs_Clock clock);
Functions common to all target modules
 | ClockFreqs_Module_getMask// Returns the diagnostics mask for this module, ClockFreqs_Module_hasMask// Test whether this module has a diagnostics mask, ClockFreqs_Module_heap// The heap from which this module allocates memory, ClockFreqs_Module_id// Get this module's unique id, ClockFreqs_Module_setMask// Set the diagnostics mask for this module, ClockFreqs_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | ClockFreqs_Clock// Clocks ...
Constants
extern const UInt32 | ClockFreqs_ACLK// ACLK frequency (Hz);
extern const UInt32 | ClockFreqs_SMCLK// SMCLK frequency (Hz);
DETAILS
This module is used to define the ACLK and SMCLK frequencies in effect when BIOS_start() is called at the end of main(). It also provides a function that can be called by the application at runtime to query individual clock frequencies.
If the application configuration defines values for these two clocks, it (the application) is responsible for setting up the clocks to the corresponding frequencies. This module will simply hold the values specified, for reference by other SYS/BIOS modules, or for query by the application.
If the application configuration specifies a value for one of these two clock frequencies, it must specify values for both clock frequencies; if it does not, a build error will be thrown.
If the application does not define values for one of these clocks, the values will default either to the device reset values, or the boost values setup by the Boot module (ti.catalog.msp430.init.Boot). For example, if the application does not configure values for ClockFreq, and does not turn off the Boot module's default frequency boost, then the Boot module boost frequencies are used.
If the application does not configure values for ClockFreq, and *does* turn off the Boot module's frequency boost (see snippet below), then the default reset frequency values will be used.
      var Boot = xdc.module('ti.catalog.msp430.init.Boot');
      Boot.configureDCO = false;
Currently the reset and Boot module boost values are fixed, as shown below. In future releases these values may made changeable.
The default reset values are:
      ACLK  = 32768 Hz
      SMCLK = 1000000 Hz
The default Boot module boost values are:
      ACLK  = 32768 Hz
      SMCLK = 8192000 Hz
Note: This module allows query of the CPU clock (MCLK) frequency via the ClockFreqs_getFrequency() API. But MCLK cannot be configured with this module. Since MCLK is the CPU frequency, it is configured in the BIOS module. For example:
      var BIOS = xdc.useModule('ti.sysbios.BIOS');
      BIOS.cpuFreq.lo = 25000000;
      BIOS.cpuFreq.hi = 0;

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getFrequency | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable from main().
  • Startup: API is callable during any module startup.
enum ClockFreqs_Clock
index URL

Clocks

C synopsis target-domain
typedef enum ClockFreqs_Clock {
    ClockFreqs_Clock_ACLK,
    ClockFreqs_Clock_SMCLK,
    ClockFreqs_Clock_MCLK
} ClockFreqs_Clock;
config ClockFreqs_ACLK // module-wide
index URL

ACLK frequency (Hz)

C synopsis target-domain
extern const UInt32 ClockFreqs_ACLK;
config ClockFreqs_SMCLK // module-wide
index URL

SMCLK frequency (Hz)

C synopsis target-domain
extern const UInt32 ClockFreqs_SMCLK;
ClockFreqs_getFrequency() // module-wide
index URL

Get the frequency for a clock

C synopsis target-domain
UInt32 ClockFreqs_getFrequency(ClockFreqs_Clock clock);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId ClockFreqs_Module_id();
// Get this module's unique id
Bool ClockFreqs_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle ClockFreqs_Module_heap();
// The heap from which this module allocates memory
Bool ClockFreqs_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 ClockFreqs_Module_getMask();
// Returns the diagnostics mask for this module
Void ClockFreqs_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/ClockFreqs.xdc
var ClockFreqs = xdc.useModule('ti.sysbios.family.msp430.ClockFreqs');
module-wide constants & types
    values of type ClockFreqs.Clock// Clocks
        const ClockFreqs.Clock_ACLK;
        const ClockFreqs.Clock_SMCLK;
        const ClockFreqs.Clock_MCLK;
module-wide config parameters
     ClockFreqs.ACLK// ACLK frequency (Hz) = UInt32 undefined;
     ClockFreqs.SMCLK// SMCLK frequency (Hz) = UInt32 undefined;
     ClockFreqs.common$// Common module configuration parameters = Types.Common$ undefined;
enum ClockFreqs.Clock
index URL

Clocks

XDCscript usage meta-domain
values of type ClockFreqs.Clock
    const ClockFreqs.Clock_ACLK;
    const ClockFreqs.Clock_SMCLK;
    const ClockFreqs.Clock_MCLK;
C SYNOPSIS
ClockFreqs_Clock
config ClockFreqs.ACLK // module-wide
index URL

ACLK frequency (Hz)

XDCscript usage meta-domain
ClockFreqs.ACLK = UInt32 undefined;
C SYNOPSIS
ClockFreqs_ACLK
config ClockFreqs.SMCLK // module-wide
index URL

SMCLK frequency (Hz)

XDCscript usage meta-domain
ClockFreqs.SMCLK = UInt32 undefined;
C SYNOPSIS
ClockFreqs_SMCLK
metaonly config ClockFreqs.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
ClockFreqs.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:06 GMT


module ti.sysbios.family.msp430.Hwi
index URL

MSP430 Hardware Interrupt Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module implements the generic Hwi module functions Hwi_enable, Hwi_disable, and Hwi_restore as defined by IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/msp430/Hwi.xdc
#include <ti/sysbios/family/msp430/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
typedef Void | (*Hwi_VectorFuncPtr// Hwi vector function type definition)(Void);
Constants
extern const Assert_Id | Hwi_A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided;
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id | Hwi_E_notImplemented// Error raised when an unimplemented Hwi function is called;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const Int | Hwi_NUM_INTERRUPTS// The MSP430 supports up to 64 interrupts/exceptions;
DETAILS
This module implements the generic Hwi module functions Hwi_enable, Hwi_disable, and Hwi_restore as defined by IHwi.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_VectorFuncPtr
index URL

Hwi vector function type definition

C synopsis target-domain
typedef Void (*Hwi_VectorFuncPtr)(Void);
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_NUM_INTERRUPTS // module-wide
index URL

The MSP430 supports up to 64 interrupts/exceptions

C synopsis target-domain
extern const Int Hwi_NUM_INTERRUPTS;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
config Hwi_A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

C synopsis target-domain
extern const Assert_Id Hwi_A_unsupportedMaskingOption;
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_notImplemented // module-wide
index URL

Error raised when an unimplemented Hwi function is called

C synopsis target-domain
extern const Error_Id Hwi_E_notImplemented;
DETAILS
The MSP430 does not implement all of the functions defined by ti.sysbios.interfaces.IHwi. If applications call such a function, an E_notImplemented error is raised with the name of the unimplemented function passed as an argument. See xdc.runtime.Error.raise.
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // override maskSetting - Hwi does not manage nesting on 430
    Int priority;
    // Interrupt priority
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

override maskSetting - Hwi does not manage nesting on 430

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.msp430.Hwi');
module-wide constants & types
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
module-wide config parameters
    const Hwi.NUM_INTERRUPTS// The MSP430 supports up to 64 interrupts/exceptions = Int computed value;
     Hwi.A_unsupportedMaskingOption// Assert when bad maskSetting parameter provided = Assert.Desc {
        msg: "A_unsupportedMaskingOption: unsupported maskSetting."
    };
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.E_notImplemented// Error raised when an unimplemented Hwi function is called = Error.Desc {
        msg: "E_notImplemented: Function not implemented: %s"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.alwaysLog// Always emit Log messages from interrupt stubs? = Bool false;
     Hwi.alwaysWake// Always keep the CPU awake upon return from interrupt? = Bool false;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.fillVectors// Plug all unused interrupt vectors = Bool true;
     Hwi.nullIsrFunc// Unused vector handler = Void(*)(UArg) undefined;
     Hwi.resetFunc// Reset handler = Void(*)(Void) undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.plugMeta// Statically plug an interrupt vector with an ISR address(UInt intNum, Fxn fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.isrStackEnabled// Switch to ISR stack for this interrupt? Default is true = Bool true;
        params.keepAwakeEnabled// Should keep CPU awake following this interrupt? Default is false = Bool false;
        params.loggingEnabled// Does this interrupt support logging? = Bool false;
        params.maskSetting// override maskSetting - Hwi does not manage nesting on 430 = IHwi.MaskingOption IHwi.MaskingOption_ALL;
        params.nestingEnabled// Does this interrupt allow nesting by other interrupts? Default is false = Bool false;
        params.priority// Interrupt priority = Int -1;
        params.swiEnabled// Does this interrupt support posting of Swis? Default is true = Bool true;
        params.taskEnabled// Does this interrupt support task pre-emption? Default is true = Bool true;
        params.threadTypeEnabled// Does this interrupt support thread-type tracking? Default is true = Bool true;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
config Hwi.NUM_INTERRUPTS // module-wide
index URL

The MSP430 supports up to 64 interrupts/exceptions

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = Int computed value;
DETAILS
The actual number supported is device specific and provided by the catalog device specification.
C SYNOPSIS
Hwi_NUM_INTERRUPTS
config Hwi.A_unsupportedMaskingOption // module-wide
index URL

Assert when bad maskSetting parameter provided

XDCscript usage meta-domain
Hwi.A_unsupportedMaskingOption = Assert.Desc {
    msg: "A_unsupportedMaskingOption: unsupported maskSetting."
};
C SYNOPSIS
Hwi_A_unsupportedMaskingOption
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_notImplemented // module-wide
index URL

Error raised when an unimplemented Hwi function is called

XDCscript usage meta-domain
Hwi.E_notImplemented = Error.Desc {
    msg: "E_notImplemented: Function not implemented: %s"
};
DETAILS
The MSP430 does not implement all of the functions defined by ti.sysbios.interfaces.IHwi. If applications call such a function, an E_notImplemented error is raised with the name of the unimplemented function passed as an argument. See xdc.runtime.Error.raise.
C SYNOPSIS
Hwi_E_notImplemented
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.alwaysLog // module-wide
index URL

Always emit Log messages from interrupt stubs?

XDCscript usage meta-domain
Hwi.alwaysLog = Bool false;
DETAILS
This parameter serves as a global 'switch' to control whether Log begin and end messages will be emitted from interrupt stubs. Note that the behavior of each interrupt instance can be controlled individually (see loggingEnabled); when set to true, alwaysLog serves as an override of the individual instance selections, forcing logging from the stubs of all configured interrupts.
metaonly config Hwi.alwaysWake // module-wide
index URL

Always keep the CPU awake upon return from interrupt?

XDCscript usage meta-domain
Hwi.alwaysWake = Bool false;
DETAILS
This parameter serves as a global 'switch' to control whether the CPU is kept awake (i.e., not allowed to return to a low power mode) at the end of servicing a hardware interrupt (Hwi) managed by SYS/BIOS. The behavior of each interrupt instance can be controlled individually (see keepAwakeEnabled); when set to true, this parameter serves as an override of the individual instance selection, to force keep awake of the CPU. This parameter is provided to assist with debug, and to ease use and transition of legacy code to work with SYS/BIOS.
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.fillVectors // module-wide
index URL

Plug all unused interrupt vectors

XDCscript usage meta-domain
Hwi.fillVectors = Bool true;
DETAILS
This parameter allows one to plug all unused interrupt vectors a common "stub", nullIsrFunc. This allows one to more easily catch unexpected interrupts and "run away" code.
metaonly config Hwi.nullIsrFunc // module-wide
index URL

Unused vector handler

XDCscript usage meta-domain
Hwi.nullIsrFunc = Void(*)(UArg) undefined;
DETAILS
This parameter specifies the interrupt service routine used when filling unused interrupt vectors. It defaults to a function that simply loops to itself.
metaonly config Hwi.resetFunc // module-wide
index URL

Reset handler

XDCscript usage meta-domain
Hwi.resetFunc = Void(*)(Void) undefined;
DETAILS
This parameter specifies the interrupt service routine triggered on reset. The default is c_int00.
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.plugMeta() // module-wide
index URL

Statically plug an interrupt vector with an ISR address

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Fxn fxn) returns Void
ARGUMENTS
intNum — interrupt number
fxn — pointer to ISR function
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.isrStackEnabled = Bool true;
    // Switch to ISR stack for this interrupt? Default is true
    params.keepAwakeEnabled = Bool false;
    // Should keep CPU awake following this interrupt? Default is false
    params.loggingEnabled = Bool false;
    // Does this interrupt support logging?
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_ALL;
    // override maskSetting - Hwi does not manage nesting on 430
    params.nestingEnabled = Bool false;
    // Does this interrupt allow nesting by other interrupts? Default is false
    params.priority = Int -1;
    // Interrupt priority
    params.swiEnabled = Bool true;
    // Does this interrupt support posting of Swis? Default is true
    params.taskEnabled = Bool true;
    // Does this interrupt support task pre-emption? Default is true
    params.threadTypeEnabled = Bool true;
    // Does this interrupt support thread-type tracking? Default is true
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

override maskSetting - Hwi does not manage nesting on 430

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_ALL;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
metaonly config Hwi.isrStackEnabled // instance
index URL

Switch to ISR stack for this interrupt? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.isrStackEnabled = Bool true;
metaonly config Hwi.keepAwakeEnabled // instance
index URL

Should keep CPU awake following this interrupt? Default is false

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.keepAwakeEnabled = Bool false;
metaonly config Hwi.loggingEnabled // instance
index URL

Does this interrupt support logging?

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.loggingEnabled = Bool false;
DETAILS
If set to true, Log statements are inserted into the generated interrupt stub that calls the user's interrupt function. The stub posts an LM_begin event at the beginning of the interrupt service routine and a LD_end event after the user's function returns.
In addition to enabling this flag, you must also enable USER1 and/or USER2 logging for this module. Otherwise, the events posted by the inserted Log statments will be ignored.
metaonly config Hwi.nestingEnabled // instance
index URL

Does this interrupt allow nesting by other interrupts? Default is false

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.nestingEnabled = Bool false;
metaonly config Hwi.swiEnabled // instance
index URL

Does this interrupt support posting of Swis? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.swiEnabled = Bool true;
metaonly config Hwi.taskEnabled // instance
index URL

Does this interrupt support task pre-emption? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.taskEnabled = Bool true;
metaonly config Hwi.threadTypeEnabled // instance
index URL

Does this interrupt support thread-type tracking? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.threadTypeEnabled = Bool true;
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:06 GMT


module ti.sysbios.family.msp430.Power
index URL

Power Manager Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides functions that can be called to reduce MSP430 power consumption. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/msp430/Power.xdc
#include <ti/sysbios/family/msp430/Power.h>
Functions
Void | Power_changeIdleMode// Change the idleMode used for idling the CPU(Power_IdleMode mode);
Void | Power_idleCPU// Function to automatically idle the CPU during idle time();
Void | Power_sleepCPU// Function called by the application to sleep the CPU(Power_SleepMode sleepMode);
Functions common to all target modules
 | Power_Module_getMask// Returns the diagnostics mask for this module, Power_Module_hasMask// Test whether this module has a diagnostics mask, Power_Module_heap// The heap from which this module allocates memory, Power_Module_id// Get this module's unique id, Power_Module_setMask// Set the diagnostics mask for this module, Power_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Power_IdleMode// Available idle modes ...
typedef enum | Power_SleepMode// Available sleep modes ...
typedef Void | (*Power_SleepPrepFuncPtr// Sleep mode preparation function type definition)();
Constants
extern const Bool | Power_allowDynamicMode// Allow dynamic changes to idleMode at runtime?;
extern const Error_Id | Power_E_dynamicModeNotAllowed// Dynamic mode change not allowed error;
extern const Bool | Power_idle// Idle CPU when threads blocked waiting for an interrupt?;
extern const Power_IdleMode | Power_idleMode// Idle mode for CPU to enter while waiting for an interrupt;
extern const Power_SleepPrepFuncPtr | Power_sleepPrepFunction// I/O preparation function to be called by Power_sleepCPU();
DETAILS
This module provides functions that can be called to reduce MSP430 power consumption.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
idleCPU | N | N | N | N | N
changeIdleMode | Y | Y | Y | Y | Y
sleepCPU | N | N | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable from main().
  • Startup: API is callable during any module startup.
enum Power_IdleMode
index URL

Available idle modes

C synopsis target-domain
typedef enum Power_IdleMode {
    Power_LPM0,
    Power_LPM1,
    Power_LPM2,
    Power_LPM3,
    Power_LPM4
} Power_IdleMode;
enum Power_SleepMode
index URL

Available sleep modes

C synopsis target-domain
typedef enum Power_SleepMode {
    Power_Sleep_LPM4_5
    // Shutdown (LPM4.5)
} Power_SleepMode;
typedef Power_SleepPrepFuncPtr
index URL

Sleep mode preparation function type definition

C synopsis target-domain
typedef Void (*Power_SleepPrepFuncPtr)();
config Power_E_dynamicModeNotAllowed // module-wide
index URL

Dynamic mode change not allowed error

C synopsis target-domain
extern const Error_Id Power_E_dynamicModeNotAllowed;
DETAILS
This Error is raised if there is an attempt to change idleMode at runtime and allowDynamicMode is set to "false".
config Power_allowDynamicMode // module-wide
index URL

Allow dynamic changes to idleMode at runtime?

C synopsis target-domain
extern const Bool Power_allowDynamicMode;
config Power_idle // module-wide
index URL

Idle CPU when threads blocked waiting for an interrupt?

C synopsis target-domain
extern const Bool Power_idle;
config Power_idleMode // module-wide
index URL

Idle mode for CPU to enter while waiting for an interrupt

C synopsis target-domain
extern const Power_IdleMode Power_idleMode;
config Power_sleepPrepFunction // module-wide
index URL

I/O preparation function to be called by Power_sleepCPU()

C synopsis target-domain
extern const Power_SleepPrepFuncPtr Power_sleepPrepFunction;
Power_changeIdleMode() // module-wide
index URL

Change the idleMode used for idling the CPU

C synopsis target-domain
Void Power_changeIdleMode(Power_IdleMode mode);
DETAILS
This function does not immediately affect the state of the CPU, but defines the idleMode that will be invoked at subsequent opportunities SYS/BIOS has to idle the CPU.
Changing the idleMode at runtime requires that idle be enabled, the initial idleMode is defined, and allowDynamicMode is specified in the application configuration. For example:
  var Power = xdc.useModule('ti.sysbios.family.msp430.Power');
  Power.idle = true;
  Power.idleMode = Power.LPM3;
  Power.allowDynamicMode = true;
Power_idleCPU() // module-wide
index URL

Function to automatically idle the CPU during idle time

C synopsis target-domain
Void Power_idleCPU();
DETAILS
When the idle configuration parameter is set, this function will be added to the list of Idle loop functions. When called from the Idle loop, it will transition the CPU into the idle mode specified by the idleMode configuration parameter. The CPU will stay in the corresponding low power mode until the next interrupt occurs.
Power_sleepCPU() // module-wide
index URL

Function called by the application to sleep the CPU

C synopsis target-domain
Void Power_sleepCPU(Power_SleepMode sleepMode);
DETAILS
This function currently supports the LPM4.5 sleep mode only, and only on MSP430 devices that support this mode. To be effective, the device I/Os MUST be properly configured before LPM4.5 is activated, otherwise there may be excessive current draw, which could be higher than before this function is called. The proper configuration of I/Os is device, application, and board specific. The caller of this function has two options:
1) Prepare the device I/Os, and any (non-reset) wakeup interrupts prior to calling this function, or 2) Write a function for this purpose, and configure it as the optional sleepPrepFunction, that Power_sleepCPU() should call before transitioning to LPM4.5.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Power_Module_id();
// Get this module's unique id
Bool Power_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Power_Module_heap();
// The heap from which this module allocates memory
Bool Power_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Power_Module_getMask();
// Returns the diagnostics mask for this module
Void Power_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/Power.xdc
var Power = xdc.useModule('ti.sysbios.family.msp430.Power');
module-wide constants & types
    values of type Power.IdleMode// Available idle modes
        const Power.LPM0;
        const Power.LPM1;
        const Power.LPM2;
        const Power.LPM3;
        const Power.LPM4;
    values of type Power.SleepMode// Available sleep modes
        const Power.Sleep_LPM4_5// Shutdown (LPM4.5);
module-wide config parameters
     Power.E_dynamicModeNotAllowed// Dynamic mode change not allowed error = Error.Desc {
        msg: "E_dynamicModeNotAllowed: Dynamic changes to LPM are not allowed (allowDynamicMode=false)"
    };
     Power.allowDynamicMode// Allow dynamic changes to idleMode at runtime? = Bool false;
     Power.idle// Idle CPU when threads blocked waiting for an interrupt? = Bool true;
     Power.idleMode// Idle mode for CPU to enter while waiting for an interrupt = Power.IdleMode Power.LPM0;
     Power.sleepPrepFunction// I/O preparation function to be called by Power_sleepCPU() = Void(*)() undefined;
     Power.common$// Common module configuration parameters = Types.Common$ undefined;
enum Power.IdleMode
index URL

Available idle modes

XDCscript usage meta-domain
values of type Power.IdleMode
    const Power.LPM0;
    const Power.LPM1;
    const Power.LPM2;
    const Power.LPM3;
    const Power.LPM4;
C SYNOPSIS
Power_IdleMode
enum Power.SleepMode
index URL

Available sleep modes

XDCscript usage meta-domain
values of type Power.SleepMode
    const Power.Sleep_LPM4_5;
    // Shutdown (LPM4.5)
C SYNOPSIS
Power_SleepMode
config Power.E_dynamicModeNotAllowed // module-wide
index URL

Dynamic mode change not allowed error

XDCscript usage meta-domain
Power.E_dynamicModeNotAllowed = Error.Desc {
    msg: "E_dynamicModeNotAllowed: Dynamic changes to LPM are not allowed (allowDynamicMode=false)"
};
DETAILS
This Error is raised if there is an attempt to change idleMode at runtime and allowDynamicMode is set to "false".
C SYNOPSIS
Power_E_dynamicModeNotAllowed
config Power.allowDynamicMode // module-wide
index URL

Allow dynamic changes to idleMode at runtime?

XDCscript usage meta-domain
Power.allowDynamicMode = Bool false;
C SYNOPSIS
Power_allowDynamicMode
config Power.idle // module-wide
index URL

Idle CPU when threads blocked waiting for an interrupt?

XDCscript usage meta-domain
Power.idle = Bool true;
C SYNOPSIS
Power_idle
config Power.idleMode // module-wide
index URL

Idle mode for CPU to enter while waiting for an interrupt

XDCscript usage meta-domain
Power.idleMode = Power.IdleMode Power.LPM0;
C SYNOPSIS
Power_idleMode
config Power.sleepPrepFunction // module-wide
index URL

I/O preparation function to be called by Power_sleepCPU()

XDCscript usage meta-domain
Power.sleepPrepFunction = Void(*)() undefined;
C SYNOPSIS
Power_sleepPrepFunction
metaonly config Power.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Power.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:06 GMT


module ti.sysbios.family.msp430.Settings

metaonly module ti.sysbios.family.msp430.Settings
index URL
  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.msp430.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:23:06 GMT


module ti.sysbios.family.msp430.TaskSupport
index URL

MSP430 Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/msp430/TaskSupport.xdc
#include <ti/sysbios/family/msp430/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Constants
extern const SizeT | TaskSupport_defaultStackSize// default Task stack size;
extern const UInt | TaskSupport_stackAlignment// required stack alignment (in MAUs);
config TaskSupport_defaultStackSize // module-wide
index URL

default Task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.msp430.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// default Task stack size = SizeT 512;
    const TaskSupport.stackAlignment// required stack alignment (in MAUs) = UInt 2;
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

default Task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 512;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 2;
C SYNOPSIS
TaskSupport_stackAlignment
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:06 GMT


module ti.sysbios.family.msp430.Timer
index URL

MSP430 Timer Peripherals Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages the timer peripherals available on MSP430 devices (see Timer Mapping Tables for supported device information). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/msp430/Timer.xdc
#include <ti/sysbios/family/msp430/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Modify timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0x0000ffff
Typedefs
typedef struct | Timer_Control// Timer Configuration struct ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_Source// Lists of input clock sources for timers ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Mask of available timers;
extern const Error_Id | Timer_E_cannotSupport// Error raised when requested period is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when specified timer id is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when requested timer is in use;
extern const Error_Id | Timer_E_runtimeCreate// Error raised when dynamic Timer create is attempted;
extern const Bool | Timer_keepAwake// Wakeup (enable) CPU when Timer ISR returns;
DETAILS
This module manages the timer peripherals available on MSP430 devices (see Timer Mapping Tables for supported device information).
The Timer module supports the timer in 'one shot', 'continuous', and 'dynamic' modes.
In 'one shot' mode, a timer function will "fire" (run) when the timer period expires. In 'one shot' mode this will only happen once.
In 'continuous' mode, the specified timer function will "fire" every time the period expires, throughout the lifetime of the program.
In 'dynamic' mode, the specified timer function will "fire" every time the period expires. But the period of the timer can be changed dynamically, to correspond to the next tick interrupt needed from the timer. This mode is used by the SYS/BIOS Clock module for implementing dynamic tick suppression, to reduce the number of interrupts from the timer to the minimum required for currently scheduled timeouts.
NOTE: In the current implementation on MSP430 Timers cannot be created dynamically at runtime by the application. Timers must be created statically in the application configuration.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | N | N | N | N | N
construct | N | N | N | N | N
create | N | N | N | N | N
delete | N | N | N | N | N
destruct | N | N | N | N | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getFunc | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).

Timer Mapping Tables

The Timer module allows the user to use and configure the various timers that exist on a particular device. This is achieved by specifying a timer ID when statically creating the Timer instance. A convention is used to assign logical IDs to physical timers. ID '0' corresponds to the first Timer_A peripheral (TA0). ID '1' is assigned to the next Timer_A (TA1), until there are no more Timer_A peripherals. Then the next ID is assigned to the first Timer_B peripheral (if present), and so on. These tables are provided to show which timers map to which timer IDs.

Timer Mapping Tables
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0x0000ffff
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_Source
index URL

Lists of input clock sources for timers

C synopsis target-domain
typedef enum Timer_Source {
    Timer_Source_ACLK,
    // ACLK
    Timer_Source_SMCLK,
    // SMCLK
    Timer_Source_EXTERNAL,
    // External clock
    Timer_Source_EXTERNAL_INVERTED
    // Inverted external clock
} Timer_Source;
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Control
index URL

Timer Configuration struct

C synopsis target-domain
typedef struct Timer_Control {
    UInt source;
    // 0x100=ACLK, 0x200=SMCLK, 0=EXT, 0x300=EXT_INVERT
} Timer_Control;
FIELDS
source — Timer clock source.
config Timer_E_cannotSupport // module-wide
index URL

Error raised when requested period is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when specified timer id is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when requested timer is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_E_runtimeCreate // module-wide
index URL

Error raised when dynamic Timer create is attempted

C synopsis target-domain
extern const Error_Id Timer_E_runtimeCreate;
config Timer_anyMask // module-wide
index URL

Mask of available timers

C synopsis target-domain
extern const UInt Timer_anyMask;
DETAILS
This mask is used to identify the timers that can be used when Timer_create() is called with an id equal to Timer_ANY.
config Timer_keepAwake // module-wide
index URL

Wakeup (enable) CPU when Timer ISR returns

C synopsis target-domain
extern const Bool Timer_keepAwake;
DETAILS
If set to true, all Timer instances keep the CPU awake upon return from interrupt.
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_Source clockSource;
    // Clock source input select. Default is ACLK
     Timer_Control controlRegInit;
    // Control register configuration. Default source = ACLK
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    Bool nesting;
    // Enable nesting of other interrupts on top of this Timer's ISR?
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
    UInt prevThreshold;
    // Previous threshold count value
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
    Bool synchronous;
    // Selected clock source is synchronous to CPU clock? Default is false
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_clockSource // instance
index URL

Clock source input select. Default is ACLK

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Source clockSource;
config Timer_controlRegInit // instance
index URL

Control register configuration. Default source = ACLK

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Control controlRegInit;
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_nesting // instance
index URL

Enable nesting of other interrupts on top of this Timer's ISR?

C synopsis target-domain
struct Timer_Params {
     ...
    Bool nesting;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_prevThreshold // instance
index URL

Previous threshold count value

C synopsis target-domain
struct Timer_Params {
     ...
    UInt prevThreshold;
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
config Timer_synchronous // instance
index URL

Selected clock source is synchronous to CPU clock? Default is false

C synopsis target-domain
struct Timer_Params {
     ...
    Bool synchronous;
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Modify timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — function that runs when timer expires.
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.msp430.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0x0000ffff;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.Source// Lists of input clock sources for timers
        const Timer.Source_ACLK// ACLK;
        const Timer.Source_SMCLK// SMCLK;
        const Timer.Source_EXTERNAL// External clock;
        const Timer.Source_EXTERNAL_INVERTED// Inverted external clock;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Control// Timer Configuration struct;
        obj.source// 0x100=ACLK, 0x200=SMCLK, 0=EXT, 0x300=EXT_INVERT = UInt ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when requested period is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when specified timer id is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when requested timer is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.E_runtimeCreate// Error raised when dynamic Timer create is attempted = Error.Desc {
        msg: "E_runtimeCreate: Runtime Timer create is not supported %d"
    };
     Timer.anyMask// Mask of available timers = UInt 0x7;
     Timer.keepAwake// Wakeup (enable) CPU when Timer ISR returns = Bool false;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.clockSource// Clock source input select. Default is ACLK = Timer.Source Timer.Source_ACLK;
        params.controlRegInit// Control register configuration. Default source = ACLK = Timer.Control {
            source: Timer.Source_ACLK
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.nesting// Enable nesting of other interrupts on top of this Timer's ISR? = Bool false;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.prevThreshold// Previous threshold count value = UInt 0;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
        params.synchronous// Selected clock source is synchronous to CPU clock? Default is false = Bool false;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0x0000ffff;
C SYNOPSIS
Timer_MAX_PERIOD
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.Source
index URL

Lists of input clock sources for timers

XDCscript usage meta-domain
values of type Timer.Source
    const Timer.Source_ACLK;
    // ACLK
    const Timer.Source_SMCLK;
    // SMCLK
    const Timer.Source_EXTERNAL;
    // External clock
    const Timer.Source_EXTERNAL_INVERTED;
    // Inverted external clock
C SYNOPSIS
Timer_Source
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Control
index URL

Timer Configuration struct

XDCscript usage meta-domain
var obj = new Timer.Control;
    obj.source = UInt ...
    // 0x100=ACLK, 0x200=SMCLK, 0=EXT, 0x300=EXT_INVERT
FIELDS
source — Timer clock source.
C SYNOPSIS
Timer_Control
config Timer.E_cannotSupport // module-wide
index URL

Error raised when requested period is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when specified timer id is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when requested timer is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.E_runtimeCreate // module-wide
index URL

Error raised when dynamic Timer create is attempted

XDCscript usage meta-domain
Timer.E_runtimeCreate = Error.Desc {
    msg: "E_runtimeCreate: Runtime Timer create is not supported %d"
};
C SYNOPSIS
Timer_E_runtimeCreate
config Timer.anyMask // module-wide
index URL

Mask of available timers

XDCscript usage meta-domain
Timer.anyMask = UInt 0x7;
DETAILS
This mask is used to identify the timers that can be used when Timer_create() is called with an id equal to Timer_ANY.
C SYNOPSIS
Timer_anyMask
config Timer.keepAwake // module-wide
index URL

Wakeup (enable) CPU when Timer ISR returns

XDCscript usage meta-domain
Timer.keepAwake = Bool false;
DETAILS
If set to true, all Timer instances keep the CPU awake upon return from interrupt.
C SYNOPSIS
Timer_keepAwake
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.clockSource = Timer.Source Timer.Source_ACLK;
    // Clock source input select. Default is ACLK
    params.controlRegInit = Timer.Control {
    // Control register configuration. Default source = ACLK
        source: Timer.Source_ACLK
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.nesting = Bool false;
    // Enable nesting of other interrupts on top of this Timer's ISR?
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.prevThreshold = UInt 0;
    // Previous threshold count value
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
    params.synchronous = Bool false;
    // Selected clock source is synchronous to CPU clock? Default is false
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.clockSource // instance
index URL

Clock source input select. Default is ACLK

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.clockSource = Timer.Source Timer.Source_ACLK;
C SYNOPSIS
null
config Timer.controlRegInit // instance
index URL

Control register configuration. Default source = ACLK

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.controlRegInit = Timer.Control {
    source: Timer.Source_ACLK
};
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.nesting // instance
index URL

Enable nesting of other interrupts on top of this Timer's ISR?

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.nesting = Bool false;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.prevThreshold // instance
index URL

Previous threshold count value

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.prevThreshold = UInt 0;
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
config Timer.synchronous // instance
index URL

Selected clock source is synchronous to CPU clock? Default is false

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.synchronous = Bool false;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:07 GMT


module ti.sysbios.family.msp430.TimestampProvider
index URL

MSP430 Timestamp Provider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
C synopsis target-domain sourced in ti/sysbios/family/msp430/TimestampProvider.xdc
#include <ti/sysbios/family/msp430/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | TimestampProvider_Source// Input clock sources for dedicated Timestamp timer ...
Constants
extern const TimestampProvider_Source | TimestampProvider_clockSource// Input clock source for dedicated timer;
extern const UInt | TimestampProvider_timerId// Id of the timer to use for creating timestamps;
extern const Bool | TimestampProvider_useClockTimer// Use the same timer as Clock;
enum TimestampProvider_Source
index URL

Input clock sources for dedicated Timestamp timer

C synopsis target-domain
typedef enum TimestampProvider_Source {
    TimestampProvider_Source_ACLK,
    // ACLK
    TimestampProvider_Source_SMCLK
    // SMCLK
} TimestampProvider_Source;
config TimestampProvider_clockSource // module-wide
index URL

Input clock source for dedicated timer

C synopsis target-domain
extern const TimestampProvider_Source TimestampProvider_clockSource;
DETAILS
If the TimestampProvider is to use a different timer than the one used by the Clock module, this parameter specifies the input clock source for that dedicated timer.
For example, to use a dedicated timer for Timestamps, and to have it run off of SMCLK, add the following to the application config script:
  var Timestamp = xdc.useModule('ti.sysbios.family.msp430.TimestampProvider');
  Timestamp.useClockTimer = false;
  Timestamp.clockSource = Timestamp.Source_SMCLK;
config TimestampProvider_timerId // module-wide
index URL

Id of the timer to use for creating timestamps

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
DETAILS
A value of Timer.ANY (-1) indicates any timer supported by Timer is ok.
config TimestampProvider_useClockTimer // module-wide
index URL

Use the same timer as Clock

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
Set this parameter when you want TimestampProvider to use the same timer as the BIOS Clock module.
This parameter overrides the timeId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/msp430/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.msp430.TimestampProvider');
module-wide constants & types
    values of type TimestampProvider.Source// Input clock sources for dedicated Timestamp timer
        const TimestampProvider.Source_ACLK// ACLK;
        const TimestampProvider.Source_SMCLK// SMCLK;
module-wide config parameters
     TimestampProvider.clockSource// Input clock source for dedicated timer = TimestampProvider.Source TimestampProvider.Source_ACLK;
     TimestampProvider.timerId// Id of the timer to use for creating timestamps = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Use the same timer as Clock = Bool undefined;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
enum TimestampProvider.Source
index URL

Input clock sources for dedicated Timestamp timer

XDCscript usage meta-domain
values of type TimestampProvider.Source
    const TimestampProvider.Source_ACLK;
    // ACLK
    const TimestampProvider.Source_SMCLK;
    // SMCLK
C SYNOPSIS
TimestampProvider_Source
config TimestampProvider.clockSource // module-wide
index URL

Input clock source for dedicated timer

XDCscript usage meta-domain
TimestampProvider.clockSource = TimestampProvider.Source TimestampProvider.Source_ACLK;
DETAILS
If the TimestampProvider is to use a different timer than the one used by the Clock module, this parameter specifies the input clock source for that dedicated timer.
For example, to use a dedicated timer for Timestamps, and to have it run off of SMCLK, add the following to the application config script:
  var Timestamp = xdc.useModule('ti.sysbios.family.msp430.TimestampProvider');
  Timestamp.useClockTimer = false;
  Timestamp.clockSource = Timestamp.Source_SMCLK;
C SYNOPSIS
TimestampProvider_clockSource
config TimestampProvider.timerId // module-wide
index URL

Id of the timer to use for creating timestamps

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
DETAILS
A value of Timer.ANY (-1) indicates any timer supported by Timer is ok.
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Use the same timer as Clock

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool undefined;
DETAILS
Set this parameter when you want TimestampProvider to use the same timer as the BIOS Clock module.
This parameter overrides the timeId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:07 GMT


package ti.sysbios.family.windows
index URL

Native Windows SYS/BIOS Support

  • DETAILS
  • MOTIVATION
  • HIGH_LEVEL_DESCRIPTION
  • CLOCK_RATE_CONSIDERATIONS
This package supports SYS/BIOS programs which are built and run as native Windows executables. This enables applications to be developed and tested on Windows using native Windows development tools. [ more ... ]
XDCspec declarations sourced in ti/sysbios/family/windows/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.family.windows [2, 0, 0, 0] {
    module Hwi;
    // Windows emulation Hardware Interrupt Support Module
    module Settings;
    // Device/Family-specific delegate assignment module for Windows emulation targets
    module TaskSupport;
    // Windows Task Support Module
    module Timer;
    // Timer Peripherals Manager for Windows family
    module TimestampProvider;
    // TimestampProvider implementation for Windows
}
DETAILS
This package supports SYS/BIOS programs which are built and run as native Windows executables. This enables applications to be developed and tested on Windows using native Windows development tools.
Although this package emulates timers and interrupts, special consideration must be given to the fact that Windows is not a real-time operating system. A program will not run in real-time nor is it cycle equivalent to a target program.
On Windows, the timer period may be programmed to as little as one millisecond, however, the actual minimum timer period is 10 - 15 milliseconds. This latency results from the Windows clock ticking at 10 milliseconds with additional delays in the Windows kernel. See below for more details on clock rate considerations.
This package emulates the C64+ DSP core with respect to hardware interrupt handling and dispatching. Currently, the only supported platform is host.platform.PC.
MOTIVATION
You can use SYS/BIOS emulation on Windows to model your application on a high-level operating system before moving to simulators or hardware.
When developing a software module, such as a codec, a common practice is to first write a "Golden C" version. Once the software is stable, the Golden C version is used as a baseline for porting to specific target platforms.
When developing the Golden C version, it is often preferable to do this work on a High-Level Operating System (HLOS), such as Windows. This allows the use of HLOS tool-chains for code profiling and validation. Providing a SYS/BIOS Emulation layer that runs on Windows makes this effort more efficient. It allows a native SYS/BIOS application to be built and run as a native Windows executable.
HIGH_LEVEL_DESCRIPTION
SYS/BIOS emulation is supported by implementing the platform proxy modules for Windows. These modules are contained in the ti.sysbios.family.windows package. These proxy modules provide interfaces for the following:
  • hardware interrupts
  • thread context switching
  • general purpose timers
  • system clock tick counter
To implement these interfaces, some hardware functionality is emulated in the proxy modules because Windows does not allow direct access to the hardware.
The following figure shows a block diagram of both a C64x+ implementation and a Windows implementation.
Application code written in C that makes only SYS/BIOS API calls should not require any changes. However, any code written for peripheral control will need to be replaced. Peripherals are not modeled in the emulation package.
The SYS/BIOS Kernel does not require any changes. Through XDC configuration, the kernel binds with the appropriate proxy modules relevant to the target platform (that is, for the Windows platform or a hardware platform).
When building the application, XDC configuration is used to select the run-time platform. Through configuration options, the application can bind with the appropriate modules that are hardware or emulation specific. This will most likely pertain to peripheral and/or test framework code.
On hardware platforms, peripheral devices typically raise interrupts to the CPU which then invokes the Hwi dispatcher to service it. To emulate this behavior, the SYS/BIOS emulation package simulates an interrupt that preempts the currently running task and invokes the Hwi dispatcher. This is done asynchronously with respect to SYS/BIOS tasks.
The Windows emulation package faithfully emulates the SYS/BIOS scheduler behavior. That is to say that task scheduling will occur in the same order on Windows as on hardware. However, interrupts are not real-time. Therefore, interrupt preemption will differ, and this may invoke the scheduler in a different sequence than observed when running on hardware.
Windows Win32 API functions may be invoked alongside SYS/BIOS API functions. This should be kept to a minimum in order to encourage code encapsulation and to maximize code reuse between hardware and the Windows platform.
CLOCK_RATE_CONSIDERATIONS
When running on Windows Emulation, the SYS/BIOS clock is configured to tick much slower. This is necessary because the Windows clock ticks slower than a typical hardware clock. Thus, any code that depends on clock ticks, instead of wall clock duration, should take this into account during the configuration phase.
For example, if Task_sleep(500) is called on a hardware platform where the SYS/BIOS clock ticks every one millisecond (resulting in a 500 millisecond sleep period), then the sleep period should be normalized for the Windows platform using the following formula:
  windowsTicks = 500 / (Clock_tickPeriod / 1000)
where the Clock_tickPeriod is the SYS/BIOS clock tick period on Windows.
generated on Fri, 17 Jun 2011 00:23:39 GMT


module ti.sysbios.family.windows.Hwi
index URL

Windows emulation Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTE
  • XDCscript usage
  • Individual elements
This Hwi module provides Windows emulation specific implementations of the APIs defined in IHwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/windows/Hwi.xdc
#include <ti/sysbios/family/windows/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Bits16 | Hwi_disableIER// Disable certain maskable interrupts(Bits16 mask);
Bits16 | Hwi_enableIER// Enable certain maskable interrupts(Bits16 mask);
Hwi_Handle | Hwi_getHandle// Return a pointer to an Hwi instance object(UInt intNum);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Void | Hwi_reconfig// Reconfigure a dispatched interrupt(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
Bits16 | Hwi_restoreIER// Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called(Bits16 mask);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Defines
#define | Hwi_NUM_INTERRUPTS// Dispatcher supports 16 interrupts (Int)16
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef Void | (*Hwi_IsrFxn// Isr function type definition)(UInt);
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Assert_Id | Hwi_A_interNum// Assert: invalid interrupt number;
extern const Assert_Id | Hwi_A_noPendingIntr// Assert: there must be a pending interrupt;
extern const Assert_Id | Hwi_A_pluggedIntr// Assert: an unplugged interrupt was raised;
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_alreadyDefined// Error raised when Hwi is already defined;
extern const Error_Id | Hwi_E_calloc// Error: memory allocation request failed;
extern const Error_Id | Hwi_E_event// Error: CreateEvent failed;
extern const Log_Event | Hwi_LD_end// Issued just after return from Hwi function (with interrupts disabled);
extern const Log_Event | Hwi_LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled);
extern const Log_Event | Hwi_LW_missedIntr// Log: missed interrupt detected;
DETAILS
This Hwi module provides Windows emulation specific implementations of the APIs defined in IHwi.
Additional Windows emulation specific APIs are also provided.
NOTE
In this Hwi module implementation, the instance config parameter value MaskingOption_LOWER is equivalent to MaskingOption_SELF. Statically configuring a Hwi object's Params.maskSetting to MaskingOption_LOWER will result in the generation of a benign build warning. Dynamic usages of MaskingOption_LOWER will be silently converted to MaskingOption_SELF.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableIER | Y | Y | Y | Y | N
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | Y | N
enableIER | Y | Y | Y | Y | N
enableInterrupt | Y | Y | Y | Y | N
getHandle | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
plug | Y | Y | Y | Y | N
restore | Y | Y | Y | Y | Y
restoreIER | Y | Y | Y | Y | N
restoreInterrupt | Y | Y | Y | Y | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
const Hwi_NUM_INTERRUPTS
index URL

Dispatcher supports 16 interrupts

C synopsis target-domain
#define Hwi_NUM_INTERRUPTS (Int)16
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
typedef Hwi_IsrFxn
index URL

Isr function type definition

C synopsis target-domain
typedef Void (*Hwi_IsrFxn)(UInt);
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_A_interNum // module-wide
index URL

Assert: invalid interrupt number

C synopsis target-domain
extern const Assert_Id Hwi_A_interNum;
DETAILS
Interrupt number must be greater than or equal to 0 and less than NUM_INTERRUPTS.
RAISED_IN
disableInterrupt
enableInterrupt
plug
ti.sysbios.interfaces.IHwi.post
SEE_ALSO
xdc.runtime.Assert
xdc.runtime.Diags
config Hwi_A_noPendingIntr // module-wide
index URL

Assert: there must be a pending interrupt

C synopsis target-domain
extern const Assert_Id Hwi_A_noPendingIntr;
DETAILS
The Hwi module decided to take an interrupt, but upon inspecting the IER and IFR registers did not find an enabled pending interrupt.
config Hwi_A_pluggedIntr // module-wide
index URL

Assert: an unplugged interrupt was raised

C synopsis target-domain
extern const Assert_Id Hwi_A_pluggedIntr;
DETAILS
An interrupt was raised which does not have an ISR plugged into the Interrupt Service Table (IST).
RAISED_IN
post
config Hwi_E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

C synopsis target-domain
extern const Error_Id Hwi_E_alreadyDefined;
config Hwi_E_calloc // module-wide
index URL

Error: memory allocation request failed

C synopsis target-domain
extern const Error_Id Hwi_E_calloc;
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
startup
config Hwi_E_event // module-wide
index URL

Error: CreateEvent failed

C synopsis target-domain
extern const Error_Id Hwi_E_event;
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
startup
config Hwi_LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LD_end;
config Hwi_LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

C synopsis target-domain
extern const Log_Event Hwi_LM_begin;
config Hwi_LW_missedIntr // module-wide
index URL

Log: missed interrupt detected

C synopsis target-domain
extern const Log_Event Hwi_LW_missedIntr;
DETAILS
An interrupt is being raised which has a previous instance recorded in the IFR register still waiting to be serviced.
RAISED_IN
post
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableIER() // module-wide
index URL

Disable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_disableIER(Bits16 mask);
ARGUMENTS
mask — Bitmask of interrupts to disable.
RETURNS
Previous IER settings bitmask.
DETAILS
Atomically disables specific interrupts by clearing the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be cleared should be set to 1 in the mask.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableIER() // module-wide
index URL

Enable certain maskable interrupts

C synopsis target-domain
Bits16 Hwi_enableIER(Bits16 mask);
ARGUMENTS
mask — Bitmask of interrupts to enable.
RETURNS
Previous IER settings bitmask.
DETAILS
Atomically enables specific interrupts by setting the bits specified by mask in the Interrupt Enable Register (IER).
The IER bits to be set should be set to 1 in the mask.
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_getHandle() // module-wide
index URL

Return a pointer to an Hwi instance object

C synopsis target-domain
Hwi_Handle Hwi_getHandle(UInt intNum);
ARGUMENTS
intNum — Interrupt number.
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreIER() // module-wide
index URL

Restore maskable interrupts to the state they were in when either disableIER() or enableIER() was called

C synopsis target-domain
Bits16 Hwi_restoreIER(Bits16 mask);
ARGUMENTS
mask — Bitmask of interrupts to restore.
RETURNS
Previous IER settings bitmask.
DETAILS
Atomically writes the given mask to the IER register. Typically used to restore the IER register to the state returned from a call to either disableIER() or enableIER().
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bits16 disableMask;
    // Dispatcher auto-nesting interrupt disable mask
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority. Not supported on this target
    Bits16 restoreMask;
    // Dispatcher auto-nesting interrupt restore mask
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 disableMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority. Not supported on this target

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

C synopsis target-domain
struct Hwi_Params {
     ...
    Bits16 restoreMask;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, IHwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_reconfig() // instance
index URL

Reconfigure a dispatched interrupt

C synopsis target-domain
Void Hwi_reconfig(Hwi_Handle handle, Hwi_FuncPtr fxn, Hwi_Params *params);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hookContext — value to write to context
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/windows/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.family.windows.Hwi');
module-wide constants & types
    const Hwi.NUM_INTERRUPTS// Dispatcher supports 16 interrupts = 16;
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
    var obj = new Hwi.NonDispatchedInterrupt// Non-dispatched interrupt object;
        obj.intNum// interrupt number = Int ...
        obj.fxn// plugged ISR function = Void(*)(UInt) ...
        obj.enableInt// interrupt enable flag = Bool ...
        obj.eventId// source event id = Int ...
module-wide config parameters
     Hwi.A_interNum// Assert: invalid interrupt number = Assert.Desc {
        msg: "A_interNum: interrupt number must be less then NUM_INTERRUPTS"
    };
     Hwi.A_noPendingIntr// Assert: there must be a pending interrupt = Assert.Desc {
        msg: "A_noPendingIntr: there must be a pending interrupt"
    };
     Hwi.A_pluggedIntr// Assert: an unplugged interrupt was raised = Assert.Desc {
        msg: "interrupt must be plugged"
    };
     Hwi.E_alreadyDefined// Error raised when Hwi is already defined = Error.Desc {
        msg: "E_alreadyDefined: Hwi already defined: intr# %d"
    };
     Hwi.E_calloc// Error: memory allocation request failed = Error.Desc {
        msg: "calloc failed"
    };
     Hwi.E_event// Error: CreateEvent failed = Error.Desc {
        msg: "CreateEvent failed"
    };
     Hwi.LD_end// Issued just after return from Hwi function (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: hwi: 0x%x"
    };
     Hwi.LM_begin// Issued just prior to Hwi function invocation (with interrupts disabled) = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d"
    };
     Hwi.LW_missedIntr// Log: missed interrupt detected = Log.EventDesc {
        mask: Diags.USER3,
        msg: "Warning: LW_missedIntr: missed interrupt detected: %d"
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.nonDispatchedInterrupts// Non-dispatched interrupt array = Hwi.NonDispatchedInterrupt[string] undefined;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
     Hwi.plugMeta// Plug an interrupt vector with an ISR address at config time(UInt intNum, Void(*)(UInt) fxn) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.disableMask// Dispatcher auto-nesting interrupt disable mask = Bits16 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority. Not supported on this target = Int 0;
        params.restoreMask// Dispatcher auto-nesting interrupt restore mask = Bits16 0;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
const Hwi.NUM_INTERRUPTS
index URL

Dispatcher supports 16 interrupts

XDCscript usage meta-domain
const Hwi.NUM_INTERRUPTS = 16;
C SYNOPSIS
Hwi_NUM_INTERRUPTS
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
metaonly struct Hwi.NonDispatchedInterrupt
index URL

Non-dispatched interrupt object

XDCscript usage meta-domain
var obj = new Hwi.NonDispatchedInterrupt;
    obj.intNum = Int ...
    // interrupt number
    obj.fxn = Void(*)(UInt) ...
    // plugged ISR function
    obj.enableInt = Bool ...
    // interrupt enable flag
    obj.eventId = Int ...
    // source event id
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts.
config Hwi.A_interNum // module-wide
index URL

Assert: invalid interrupt number

XDCscript usage meta-domain
Hwi.A_interNum = Assert.Desc {
    msg: "A_interNum: interrupt number must be less then NUM_INTERRUPTS"
};
DETAILS
Interrupt number must be greater than or equal to 0 and less than NUM_INTERRUPTS.
RAISED_IN
disableInterrupt
enableInterrupt
plug
ti.sysbios.interfaces.IHwi.post
SEE_ALSO
xdc.runtime.Assert
xdc.runtime.Diags
C SYNOPSIS
Hwi_A_interNum
config Hwi.A_noPendingIntr // module-wide
index URL

Assert: there must be a pending interrupt

XDCscript usage meta-domain
Hwi.A_noPendingIntr = Assert.Desc {
    msg: "A_noPendingIntr: there must be a pending interrupt"
};
DETAILS
The Hwi module decided to take an interrupt, but upon inspecting the IER and IFR registers did not find an enabled pending interrupt.
C SYNOPSIS
Hwi_A_noPendingIntr
config Hwi.A_pluggedIntr // module-wide
index URL

Assert: an unplugged interrupt was raised

XDCscript usage meta-domain
Hwi.A_pluggedIntr = Assert.Desc {
    msg: "interrupt must be plugged"
};
DETAILS
An interrupt was raised which does not have an ISR plugged into the Interrupt Service Table (IST).
RAISED_IN
post
C SYNOPSIS
Hwi_A_pluggedIntr
config Hwi.E_alreadyDefined // module-wide
index URL

Error raised when Hwi is already defined

XDCscript usage meta-domain
Hwi.E_alreadyDefined = Error.Desc {
    msg: "E_alreadyDefined: Hwi already defined: intr# %d"
};
C SYNOPSIS
Hwi_E_alreadyDefined
config Hwi.E_calloc // module-wide
index URL

Error: memory allocation request failed

XDCscript usage meta-domain
Hwi.E_calloc = Error.Desc {
    msg: "calloc failed"
};
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
startup
C SYNOPSIS
Hwi_E_calloc
config Hwi.E_event // module-wide
index URL

Error: CreateEvent failed

XDCscript usage meta-domain
Hwi.E_event = Error.Desc {
    msg: "CreateEvent failed"
};
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
startup
C SYNOPSIS
Hwi_E_event
config Hwi.LD_end // module-wide
index URL

Issued just after return from Hwi function (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: hwi: 0x%x"
};
C SYNOPSIS
Hwi_LD_end
config Hwi.LM_begin // module-wide
index URL

Issued just prior to Hwi function invocation (with interrupts disabled)

XDCscript usage meta-domain
Hwi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d"
};
C SYNOPSIS
Hwi_LM_begin
config Hwi.LW_missedIntr // module-wide
index URL

Log: missed interrupt detected

XDCscript usage meta-domain
Hwi.LW_missedIntr = Log.EventDesc {
    mask: Diags.USER3,
    msg: "Warning: LW_missedIntr: missed interrupt detected: %d"
};
DETAILS
An interrupt is being raised which has a previous instance recorded in the IFR register still waiting to be serviced.
RAISED_IN
post
C SYNOPSIS
Hwi_LW_missedIntr
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.nonDispatchedInterrupts // module-wide
index URL

Non-dispatched interrupt array

XDCscript usage meta-domain
Hwi.nonDispatchedInterrupts = Hwi.NonDispatchedInterrupt[string] undefined;
DETAILS
Provided so that XGCONF users can easily plug non-dispatched interrupts.
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
metaonly Hwi.plugMeta() // module-wide
index URL

Plug an interrupt vector with an ISR address at config time

XDCscript usage meta-domain
Hwi.plugMeta(UInt intNum, Void(*)(UInt) fxn) returns Void
ARGUMENTS
intNum — Interrupt number. The interrupt number must be in the range 0 - (NUM_INTERRUPTS - 1).
fxn — Pointer to ISR function. The ISR function pointer cannot be NULL.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.disableMask = Bits16 0;
    // Dispatcher auto-nesting interrupt disable mask
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int 0;
    // Interrupt priority. Not supported on this target
    params.restoreMask = Bits16 0;
    // Dispatcher auto-nesting interrupt restore mask
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.disableMask // instance
index URL

Dispatcher auto-nesting interrupt disable mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.disableMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are disabled prior to invoking the user's ISR function with GIE = 1.
disableMask bits set to 1 correspond to IER bits that will be cleared prior to invoking the ISR.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority. Not supported on this target

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int 0;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.restoreMask // instance
index URL

Dispatcher auto-nesting interrupt restore mask

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.restoreMask = Bits16 0;
DETAILS
When the dispatcher's auto interrupt nesting support feature is enabled (see dispatcherAutoNestingSupport), this mask defines which IER bits are restored to their previous setting upon return from the user's ISR function.
restoreMask bits set to 1 correspond to IER bits that will be restored.
The value of this mask is normally auto-calculated based on the value of the maskSetting. However, manual setting of this mask is enabled by setting the maskSetting to MaskingOption_BITMASK.
The default value is derived from the MaskingOption_SELF maskSetting.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:23:39 GMT


module ti.sysbios.family.windows.Settings

metaonly module ti.sysbios.family.windows.Settings
index URL

Device/Family-specific delegate assignment module for Windows emulation targets

  • XDCscript usage
  • Individual elements
XDCscript usage meta-domain sourced in ti/sysbios/family/windows/Settings.xdc
var Settings = xdc.useModule('ti.sysbios.family.windows.Settings');
module-wide functions
     Settings.getDefaultBootModule// returns the family-specific Boot module() returns String
     Settings.getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate() returns String
     Settings.getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod() returns UInt32
     Settings.getDefaultHwiDelegate// returns the family-specific Hwi module delegate() returns String
     Settings.getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate() returns String
     Settings.getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate() returns String
     Settings.getDefaultTimerDelegate// returns the family-specific Timer module delegate() returns String
     Settings.getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate() returns String
     Settings.getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate() returns String
     Settings.getFamilySettingsXml// Returns the path to the family-specific Grace page() returns String
Settings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCscript usage meta-domain
Settings.getDefaultBootModule() returns String
Settings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultCacheDelegate() returns String
Settings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCscript usage meta-domain
Settings.getDefaultClockTickPeriod() returns UInt32
Settings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCscript usage meta-domain
Settings.getDefaultHwiDelegate() returns String
Settings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultIntrinsicsSupportDelegate() returns String
Settings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCscript usage meta-domain
Settings.getDefaultTaskSupportDelegate() returns String
Settings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerDelegate() returns String
Settings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCscript usage meta-domain
Settings.getDefaultTimerSupportDelegate() returns String
Settings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCscript usage meta-domain
Settings.getDefaultTimestampDelegate() returns String
Settings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCscript usage meta-domain
Settings.getFamilySettingsXml() returns String
generated on Fri, 17 Jun 2011 00:23:39 GMT


module ti.sysbios.family.windows.TaskSupport
index URL

Windows Task Support Module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/family/windows/TaskSupport.xdc
#include <ti/sysbios/family/windows/TaskSupport.h>
Functions common to all target modules
 | TaskSupport_Module_getMask// Returns the diagnostics mask for this module, TaskSupport_Module_hasMask// Test whether this module has a diagnostics mask, TaskSupport_Module_heap// The heap from which this module allocates memory, TaskSupport_Module_id// Get this module's unique id, TaskSupport_Module_setMask// Set the diagnostics mask for this module, TaskSupport_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*TaskSupport_GlueFxn// Prototype of task enter and exit functions)();
typedef Void | (*TaskSupport_IsrFxn// Isr function type definition)(UInt);
typedef struct | TaskSupport_Task// Emulation task object TaskSupport_Task;
typedef Void | (*TaskSupport_TaskFxn// Task function type definition)(UArg,UArg);
Constants
extern const SizeT | TaskSupport_defaultStackSize// Default task stack size;
extern const Error_Id | TaskSupport_E_calloc// Error: memory allocation request failed;
extern const Error_Id | TaskSupport_E_event// Error: CreateEvent failed;
extern const Error_Id | TaskSupport_E_taskState// Error: invalid incoming task state;
extern const Error_Id | TaskSupport_E_thread// Error: CreateThread failed;
extern const Error_Id | TaskSupport_E_wait// Error: WaitForSingleObject failed;
extern const UInt | TaskSupport_stackAlignment// Required stack alignment (in MAUs);
typedef TaskSupport_GlueFxn
index URL

Prototype of task enter and exit functions

C synopsis target-domain
typedef Void (*TaskSupport_GlueFxn)();
typedef TaskSupport_IsrFxn
index URL

Isr function type definition

C synopsis target-domain
typedef Void (*TaskSupport_IsrFxn)(UInt);
typedef TaskSupport_TaskFxn
index URL

Task function type definition

C synopsis target-domain
typedef Void (*TaskSupport_TaskFxn)(UArg,UArg);
struct TaskSupport_Task
index URL

Emulation task object

C synopsis target-domain
typedef struct TaskSupport_Task TaskSupport_Task;
config TaskSupport_defaultStackSize // module-wide
index URL

Default task stack size

C synopsis target-domain
extern const SizeT TaskSupport_defaultStackSize;
config TaskSupport_stackAlignment // module-wide
index URL

Required stack alignment (in MAUs)

C synopsis target-domain
extern const UInt TaskSupport_stackAlignment;
config TaskSupport_E_calloc // module-wide
index URL

Error: memory allocation request failed

C synopsis target-domain
extern const Error_Id TaskSupport_E_calloc;
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
start
startup
config TaskSupport_E_event // module-wide
index URL

Error: CreateEvent failed

C synopsis target-domain
extern const Error_Id TaskSupport_E_event;
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
start
startup
config TaskSupport_E_taskState // module-wide
index URL

Error: invalid incoming task state

C synopsis target-domain
extern const Error_Id TaskSupport_E_taskState;
DETAILS
A task swap was attempted where the incoming task is in an invalid state.
RAISED_IN
swap
config TaskSupport_E_thread // module-wide
index URL

Error: CreateThread failed

C synopsis target-domain
extern const Error_Id TaskSupport_E_thread;
DETAILS
A CreateThread call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
config TaskSupport_E_wait // module-wide
index URL

Error: WaitForSingleObject failed

C synopsis target-domain
extern const Error_Id TaskSupport_E_wait;
DETAILS
A WaitForSingleObject call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TaskSupport_Module_id();
// Get this module's unique id
Bool TaskSupport_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TaskSupport_Module_heap();
// The heap from which this module allocates memory
Bool TaskSupport_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TaskSupport_Module_getMask();
// Returns the diagnostics mask for this module
Void TaskSupport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/windows/TaskSupport.xdc
var TaskSupport = xdc.useModule('ti.sysbios.family.windows.TaskSupport');
module-wide config parameters
    const TaskSupport.defaultStackSize// Default task stack size = SizeT 128;
    const TaskSupport.stackAlignment// Required stack alignment (in MAUs) = UInt 0;
     TaskSupport.E_calloc// Error: memory allocation request failed = Error.Desc {
        msg: "calloc failed"
    };
     TaskSupport.E_event// Error: CreateEvent failed = Error.Desc {
        msg: "CreateEvent failed"
    };
     TaskSupport.E_taskState// Error: invalid incoming task state = Error.Desc {
        msg: "invalid incoming task state"
    };
     TaskSupport.E_thread// Error: CreateThread failed = Error.Desc {
        msg: "CreateThread failed"
    };
     TaskSupport.E_wait// Error: WaitForSingleObject failed = Error.Desc {
        msg: "WaitForSingleObject failed"
    };
     TaskSupport.common$// Common module configuration parameters = Types.Common$ undefined;
config TaskSupport.defaultStackSize // module-wide
index URL

Default task stack size

XDCscript usage meta-domain
const TaskSupport.defaultStackSize = SizeT 128;
C SYNOPSIS
TaskSupport_defaultStackSize
config TaskSupport.stackAlignment // module-wide
index URL

Required stack alignment (in MAUs)

XDCscript usage meta-domain
const TaskSupport.stackAlignment = UInt 0;
C SYNOPSIS
TaskSupport_stackAlignment
config TaskSupport.E_calloc // module-wide
index URL

Error: memory allocation request failed

XDCscript usage meta-domain
TaskSupport.E_calloc = Error.Desc {
    msg: "calloc failed"
};
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
start
startup
C SYNOPSIS
TaskSupport_E_calloc
config TaskSupport.E_event // module-wide
index URL

Error: CreateEvent failed

XDCscript usage meta-domain
TaskSupport.E_event = Error.Desc {
    msg: "CreateEvent failed"
};
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
start
startup
C SYNOPSIS
TaskSupport_E_event
config TaskSupport.E_taskState // module-wide
index URL

Error: invalid incoming task state

XDCscript usage meta-domain
TaskSupport.E_taskState = Error.Desc {
    msg: "invalid incoming task state"
};
DETAILS
A task swap was attempted where the incoming task is in an invalid state.
RAISED_IN
swap
C SYNOPSIS
TaskSupport_E_taskState
config TaskSupport.E_thread // module-wide
index URL

Error: CreateThread failed

XDCscript usage meta-domain
TaskSupport.E_thread = Error.Desc {
    msg: "CreateThread failed"
};
DETAILS
A CreateThread call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
C SYNOPSIS
TaskSupport_E_thread
config TaskSupport.E_wait // module-wide
index URL

Error: WaitForSingleObject failed

XDCscript usage meta-domain
TaskSupport.E_wait = Error.Desc {
    msg: "WaitForSingleObject failed"
};
DETAILS
A WaitForSingleObject call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
C SYNOPSIS
TaskSupport_E_wait
metaonly config TaskSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TaskSupport.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:39 GMT


module ti.sysbios.family.windows.Timer
index URL

Timer Peripherals Manager for Windows family

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/family/windows/Timer.xdc
#include <ti/sysbios/family/windows/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
#define | Timer_NUM_TIMER_DEVICES// Emulation supports 2 timers (Int)2
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
Constants
extern const UInt | Timer_anyMask// Available mask to be used when select = TIMER_ANY;
extern const Error_Id | Timer_E_calloc// Error: memory allocation request failed;
extern const Error_Id | Timer_E_cannotSupport// Error: unsupported timer period;
extern const Error_Id | Timer_E_event// Error: CreateEvent failed;
extern const Error_Id | Timer_E_invalidTimer// Error: Invalid timer specified;
extern const Error_Id | Timer_E_noneAvailable// Error: no timers available;
extern const Error_Id | Timer_E_notAvailable// Error: requested timer not available;
extern const Error_Id | Timer_E_notSupported// Error: API not supported on Windows;
extern const Error_Id | Timer_E_thread// Error: CreateThread failed;
extern const Error_Id | Timer_E_wait// Error: WaitForSingleObject failed;
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
const Timer_NUM_TIMER_DEVICES
index URL

Emulation supports 2 timers

C synopsis target-domain
#define Timer_NUM_TIMER_DEVICES (Int)2
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
config Timer_E_calloc // module-wide
index URL

Error: memory allocation request failed

C synopsis target-domain
extern const Error_Id Timer_E_calloc;
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
startup
config Timer_E_cannotSupport // module-wide
index URL

Error: unsupported timer period

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
DETAILS
On Windows, the timer period cannot be less than one millisecond. However, the actual minimum timer period (even when set to one millisecond) is 10 - 15 milliseconds. This latency results from the Windows clock ticking at 10 milliseconds with additional delays in the Windows kernel.
RAISED_IN
startup
config Timer_E_event // module-wide
index URL

Error: CreateEvent failed

C synopsis target-domain
extern const Error_Id Timer_E_event;
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
startup
config Timer_E_invalidTimer // module-wide
index URL

Error: Invalid timer specified

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
DETAILS
An invalid timer id was specified. Timer id must be in the range 0 to (NUM_TIMER_DEVICES - 1). In the create() call, an id of -1 may be used to request any available timer.
RAISED_IN
init
postInit
start
stop
config Timer_E_noneAvailable // module-wide
index URL

Error: no timers available

C synopsis target-domain
extern const Error_Id Timer_E_noneAvailable;
DETAILS
A request was made for any available timer, but there are none available at this time.
RAISED_IN
postInit
config Timer_E_notAvailable // module-wide
index URL

Error: requested timer not available

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
DETAILS
A request was made for a timer, but it is not available at this time. It is currently in use.
RAISED_IN
init
postInit
config Timer_E_notSupported // module-wide
index URL

Error: API not supported on Windows

C synopsis target-domain
extern const Error_Id Timer_E_notSupported;
DETAILS
This timer API is not supported on Windows.
RAISED_IN
trigger
config Timer_E_thread // module-wide
index URL

Error: CreateThread failed

C synopsis target-domain
extern const Error_Id Timer_E_thread;
DETAILS
A CreateThread call into the Win32 API has failed.
RAISED_IN
startup
config Timer_E_wait // module-wide
index URL

Error: WaitForSingleObject failed

C synopsis target-domain
extern const Error_Id Timer_E_wait;
DETAILS
A WaitForSingleObject call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = TIMER_ANY

C synopsis target-domain
extern const UInt Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/family/windows/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.family.windows.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    const Timer.NUM_TIMER_DEVICES// Emulation supports 2 timers = 2;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.E_calloc// Error: memory allocation request failed = Error.Desc {
        msg: "calloc failed"
    };
     Timer.E_cannotSupport// Error: unsupported timer period = Error.Desc {
        msg: "Timer cannot support requested period %d"
    };
     Timer.E_event// Error: CreateEvent failed = Error.Desc {
        msg: "CreateEvent failed"
    };
     Timer.E_invalidTimer// Error: Invalid timer specified = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_noneAvailable// Error: no timers available = Error.Desc {
        msg: "no available timer"
    };
     Timer.E_notAvailable// Error: requested timer not available = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.E_notSupported// Error: API not supported on Windows = Error.Desc {
        msg: "API not supported on Windows"
    };
     Timer.E_thread// Error: CreateThread failed = Error.Desc {
        msg: "CreateThread failed"
    };
     Timer.E_wait// Error: WaitForSingleObject failed = Error.Desc {
        msg: "WaitForSingleObject failed"
    };
     Timer.anyMask// Available mask to be used when select = TIMER_ANY = UInt 0x3;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
const Timer.NUM_TIMER_DEVICES
index URL

Emulation supports 2 timers

XDCscript usage meta-domain
const Timer.NUM_TIMER_DEVICES = 2;
C SYNOPSIS
Timer_NUM_TIMER_DEVICES
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
config Timer.E_calloc // module-wide
index URL

Error: memory allocation request failed

XDCscript usage meta-domain
Timer.E_calloc = Error.Desc {
    msg: "calloc failed"
};
DETAILS
A request into the Windows runtime library for memory has failed.
RAISED_IN
startup
C SYNOPSIS
Timer_E_calloc
config Timer.E_cannotSupport // module-wide
index URL

Error: unsupported timer period

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "Timer cannot support requested period %d"
};
DETAILS
On Windows, the timer period cannot be less than one millisecond. However, the actual minimum timer period (even when set to one millisecond) is 10 - 15 milliseconds. This latency results from the Windows clock ticking at 10 milliseconds with additional delays in the Windows kernel.
RAISED_IN
startup
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_event // module-wide
index URL

Error: CreateEvent failed

XDCscript usage meta-domain
Timer.E_event = Error.Desc {
    msg: "CreateEvent failed"
};
DETAILS
A CreateEvent call into the Win32 API has failed.
RAISED_IN
startup
C SYNOPSIS
Timer_E_event
config Timer.E_invalidTimer // module-wide
index URL

Error: Invalid timer specified

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
DETAILS
An invalid timer id was specified. Timer id must be in the range 0 to (NUM_TIMER_DEVICES - 1). In the create() call, an id of -1 may be used to request any available timer.
RAISED_IN
init
postInit
start
stop
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_noneAvailable // module-wide
index URL

Error: no timers available

XDCscript usage meta-domain
Timer.E_noneAvailable = Error.Desc {
    msg: "no available timer"
};
DETAILS
A request was made for any available timer, but there are none available at this time.
RAISED_IN
postInit
C SYNOPSIS
Timer_E_noneAvailable
config Timer.E_notAvailable // module-wide
index URL

Error: requested timer not available

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
DETAILS
A request was made for a timer, but it is not available at this time. It is currently in use.
RAISED_IN
init
postInit
C SYNOPSIS
Timer_E_notAvailable
config Timer.E_notSupported // module-wide
index URL

Error: API not supported on Windows

XDCscript usage meta-domain
Timer.E_notSupported = Error.Desc {
    msg: "API not supported on Windows"
};
DETAILS
This timer API is not supported on Windows.
RAISED_IN
trigger
C SYNOPSIS
Timer_E_notSupported
config Timer.E_thread // module-wide
index URL

Error: CreateThread failed

XDCscript usage meta-domain
Timer.E_thread = Error.Desc {
    msg: "CreateThread failed"
};
DETAILS
A CreateThread call into the Win32 API has failed.
RAISED_IN
startup
C SYNOPSIS
Timer_E_thread
config Timer.E_wait // module-wide
index URL

Error: WaitForSingleObject failed

XDCscript usage meta-domain
Timer.E_wait = Error.Desc {
    msg: "WaitForSingleObject failed"
};
DETAILS
A WaitForSingleObject call into the Win32 API has failed.
RAISED_IN
processInterrupt
start
C SYNOPSIS
Timer_E_wait
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = TIMER_ANY

XDCscript usage meta-domain
Timer.anyMask = UInt 0x3;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:23:39 GMT


module ti.sysbios.family.windows.TimestampProvider
index URL

TimestampProvider implementation for Windows

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides an implementation on Windows for the xdc.runtime.ITimestampProvider interface. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/family/windows/TimestampProvider.xdc
#include <ti/sysbios/family/windows/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Return the timestamp counter tick rate(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const Error_Id | TimestampProvider_E_processTimes// Error: GetProcessTimes failed;
DETAILS
This module provides an implementation on Windows for the xdc.runtime.ITimestampProvider interface.
On Windows, the timestamp counter value is computed from the accumulated CPU user time spent running the SYS/BIOS application. This emulates a hardware timestamp counter by eliminating all the CPU time spent running the Windows kernel and other Windows applications.
It is important to understand that although Windows uses a real-time counter to accumulate the user time of a process, the accumulated total is updated only once every 10 milliseconds. Therefore, it is quite likely that two consecutive calls to TimestampProvider_get32() or TimestampProvider_get64() or will return the same value. In fact, the returned value will only change the next time Windows updates the accumulated user time.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
config TimestampProvider_E_processTimes // module-wide
index URL

Error: GetProcessTimes failed

C synopsis target-domain
extern const Error_Id TimestampProvider_E_processTimes;
DETAILS
A call to GetProcessTimes in the Win32 API has failed.
RAISED_IN
getTimestampCount64
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
DETAILS
See the details section above for implementation details.
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
DETAILS
See the details section above for implementation details.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Return the timestamp counter tick rate

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
DETAILS
This function returns the rate, specified in hertz, at which the timestamp counter ticks. In other words, it is how many ticks per second the timestamp counter will tick.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/family/windows/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.family.windows.TimestampProvider');
module-wide config parameters
     TimestampProvider.E_processTimes// Error: GetProcessTimes failed = Error.Desc {
        msg: "GetProcessTimes failed: %d"
    };
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.E_processTimes // module-wide
index URL

Error: GetProcessTimes failed

XDCscript usage meta-domain
TimestampProvider.E_processTimes = Error.Desc {
    msg: "GetProcessTimes failed: %d"
};
DETAILS
A call to GetProcessTimes in the Win32 API has failed.
RAISED_IN
getTimestampCount64
C SYNOPSIS
TimestampProvider_E_processTimes
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:23:39 GMT


package ti.sysbios.gates
index URL

Contains modules that inherit from IGatePovider

  • DETAILS
  • RUNTIME EXAMPLE
The xdc.runtime.Gate module is provided by XDCtools, and is documented in the XDCtools help, but SYS/BIOS provides additional implementations in the ti.sysbios.gates package. [ more ... ]
XDCspec declarations sourced in ti/sysbios/gates/package.xdc
requires ti.sysbios.interfaces;
requires ti.sysbios.knl;
package ti.sysbios.gates [2, 0, 0, 0] {
    module GateAll;
    // Hwi, Swi & Task Gate
    module GateHwi;
    // Hardware Interrupt Gate
    module GateMutex;
    // Mutex Gate
    module GateMutexPri;
    // Mutex Gate with priority inheritance
    module GateSwi;
    // Software Interrupt Gate
    module GateTask;
    // Task Gate
}
DETAILS
The xdc.runtime.Gate module is provided by XDCtools, and is documented in the XDCtools help, but SYS/BIOS provides additional implementations in the ti.sysbios.gates package.
A "Gate" is a module that implements the IGateProvider interface. Gates are devices for preventing concurrent accesses to critical regions of code. The various Gate implementations differ in how they attempt to lock the critical regions.
Threads can be preempted by other threads of higher priority, and some sections of code need to be completed by one thread before they can be executed by another thread. Code that modifies a linked list is a common example of a critical region that may need to be protected by a Gate.
Gates generally work by either disabling some level of preemption such as disabling task switching or even hardware interrupts, or by using a binary semaphore.
All Gate implementations support nesting through the use of a "key". For Gates that function by disabling preemption, it is possible that multiple threads would call Gate_enter(), but preemption should not be restored until all of the threads have called Gate_leave(). This functionality is provided through the use of a key. A call to Gate_enter() returns a key that must then be passed back to Gate_leave(). Only the outermost call to Gate_enter() returns the correct key for restoring preemption. (The actual module name for the implementation is used instead of "Gate" in the function name.)
RUNTIME EXAMPLE
The following C code protects a critical region with a Gate. This example uses a GateHwi, which disables and enables interrupts as the locking mechanism.
  UInt gateKey;
  GateHwi_Handle gateHwi;
  GateHwi_Params prms;
  GateHwi_Params_init(&prms);

  gateHwi = GateHwi_create(&prms, NULL);

  // Simultaneous operations on a List by multiple threads could
  // corrupt the List structure, so modifications to the List
  // are protected with a Gate.
  gateKey = GateHwi_enter(gateHwi);
  List_get(myList);
  GateHwi_leave(gateHwi, gateKey);
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateAll
index URL

Hwi, Swi & Task Gate

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateAll uses disabling and enabling of interrupts, Swis and Tasks for the resource locking mechanism. Such a gate guarantees exclusive access to the CPU. This gate can be used whenever the resource is being shared by Tasks, Swis, and/or Hwis. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateAll.xdc
#include <ti/sysbios/gates/GateAll.h>
Functions
Void | GateAll_construct// Initialize a new instance object inside the provided structure(GateAll_Struct *structP, const GateAll_Params *params);
GateAll_Handle | GateAll_create// Allocate and initialize a new instance object and return its handle(const GateAll_Params *params, Error_Block *eb);
Void | GateAll_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateAll_Handle *handleP);
Void | GateAll_destruct// Finalize the instance object inside the provided structure(GateAll_Struct *structP);
Void | GateAll_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateAll_Params *params);
Functions common to all IGateProvider modules
Bool | GateAll_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateAll_handle// Convert this instance structure pointer into an instance handle, GateAll_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateAll_Handle_label// The label associated with this instance object, GateAll_Handle_name// The name of this instance object, GateAll_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateAll_Object_count// The number of statically-created instance objects, GateAll_Object_first// The handle of the first dynamically-created instance object, or NULL, GateAll_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateAll_Object_heap// The heap used to allocate dynamically-created instance objects, GateAll_Object_next// The handle of the next dynamically-created instance object, or NULL, GateAll_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateAll_Module_getMask// Returns the diagnostics mask for this module, GateAll_Module_hasMask// Test whether this module has a diagnostics mask, GateAll_Module_heap// The heap from which this module allocates memory, GateAll_Module_id// Get this module's unique id, GateAll_Module_setMask// Set the diagnostics mask for this module, GateAll_Module_startupDone// Test if this module has completed startup
Defines
#define | GateAll_Q_BLOCKING// Blocking quality (Int)1
#define | GateAll_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateAll_Object * | GateAll_Handle// Client reference to an instance object;
typedef struct | GateAll_Object// Opaque internal representation of an instance object GateAll_Object;
typedef struct | GateAll_Params// Instance config-params structure ...
typedef struct | GateAll_Struct// Opaque client structure large enough to hold an instance object GateAll_Struct;
DETAILS
GateAll uses disabling and enabling of interrupts, Swis and Tasks for the resource locking mechanism. Such a gate guarantees exclusive access to the CPU. This gate can be used whenever the resource is being shared by Tasks, Swis, and/or Hwis.
The duration between the enter and leave should be as short as possible to minimize Hwi latency.
GateAll inherits from xdc.runtime.IGateProvider, therefore supports nesting.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
enter | Y | Y | Y | Y** | Y**
leave | Y | Y | Y | Y** | Y**
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateAll_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateAll_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateAll_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateAll_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateAll_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateAll_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateAll_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateAll_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateAll_Module_id();
// Get this module's unique id
Bool GateAll_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateAll_Module_heap();
// The heap from which this module allocates memory
Bool GateAll_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateAll_Module_getMask();
// Returns the diagnostics mask for this module
Void GateAll_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateAll_Object GateAll_Object;
// Opaque internal representation of an instance object
typedef GateAll_Object *GateAll_Handle;
// Client reference to an instance object
typedef struct GateAll_Struct GateAll_Struct;
// Opaque client structure large enough to hold an instance object
GateAll_Handle GateAll_handle(GateAll_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateAll_Struct *GateAll_struct(GateAll_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateAll_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateAll_Params;
Void GateAll_Params_init(GateAll_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateAll_Handle GateAll_create(const GateAll_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateAll_construct(GateAll_Struct *structP, const GateAll_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateAll_delete(GateAll_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateAll_destruct(GateAll_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateAll_Handle_upCast(GateAll_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateAll_Handle GateAll_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateAll_Object_count();
// The number of statically-created instance objects
GateAll_Handle GateAll_Object_get(GateAll_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateAll_Handle GateAll_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateAll_Handle GateAll_Object_next(GateAll_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateAll_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateAll_Handle_label(GateAll_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateAll_Handle_name(GateAll_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateAll.xdc
var GateAll = xdc.useModule('ti.sysbios.gates.GateAll');
module-wide constants & types
    const GateAll.Q_BLOCKING// Blocking quality = 1;
    const GateAll.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateAll.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateAll.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateAll.Params// Instance config-params object;
per-instance creation
    var inst = GateAll.create// Create an instance-object(params);
const GateAll.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateAll.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateAll_Q_BLOCKING
const GateAll.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateAll.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateAll_Q_PREEMPTING
metaonly config GateAll.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateAll.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateAll.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateAll.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateAll.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateAll.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateAll.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateHwi
index URL

Hardware Interrupt Gate

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateHwi uses disabling and enabling of interrupts as the resource locking mechanism. Such a gate guarantees exclusive access to the CPU. This gate can be used whenever the resource is being shared by Tasks, Swis, and/or Hwis. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateHwi.xdc
#include <ti/sysbios/gates/GateHwi.h>
Functions
Void | GateHwi_construct// Initialize a new instance object inside the provided structure(GateHwi_Struct *structP, const GateHwi_Params *params);
GateHwi_Handle | GateHwi_create// Allocate and initialize a new instance object and return its handle(const GateHwi_Params *params, Error_Block *eb);
Void | GateHwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateHwi_Handle *handleP);
Void | GateHwi_destruct// Finalize the instance object inside the provided structure(GateHwi_Struct *structP);
Void | GateHwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateHwi_Params *params);
Functions common to all IGateProvider modules
Bool | GateHwi_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateHwi_handle// Convert this instance structure pointer into an instance handle, GateHwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateHwi_Handle_label// The label associated with this instance object, GateHwi_Handle_name// The name of this instance object, GateHwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateHwi_Object_count// The number of statically-created instance objects, GateHwi_Object_first// The handle of the first dynamically-created instance object, or NULL, GateHwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateHwi_Object_heap// The heap used to allocate dynamically-created instance objects, GateHwi_Object_next// The handle of the next dynamically-created instance object, or NULL, GateHwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateHwi_Module_getMask// Returns the diagnostics mask for this module, GateHwi_Module_hasMask// Test whether this module has a diagnostics mask, GateHwi_Module_heap// The heap from which this module allocates memory, GateHwi_Module_id// Get this module's unique id, GateHwi_Module_setMask// Set the diagnostics mask for this module, GateHwi_Module_startupDone// Test if this module has completed startup
Defines
#define | GateHwi_Q_BLOCKING// Blocking quality (Int)1
#define | GateHwi_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateHwi_Object * | GateHwi_Handle// Client reference to an instance object;
typedef struct | GateHwi_Object// Opaque internal representation of an instance object GateHwi_Object;
typedef struct | GateHwi_Params// Instance config-params structure ...
typedef struct | GateHwi_Struct// Opaque client structure large enough to hold an instance object GateHwi_Struct;
DETAILS
GateHwi uses disabling and enabling of interrupts as the resource locking mechanism. Such a gate guarantees exclusive access to the CPU. This gate can be used whenever the resource is being shared by Tasks, Swis, and/or Hwis.
The duration between the enter and leave should be as short as possible to minimize Hwi latency.
GateHwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
enter | Y | Y | Y | Y** | Y**
leave | Y | Y | Y | Y** | Y**
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateHwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateHwi_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateHwi_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateHwi_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateHwi_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateHwi_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateHwi_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateHwi_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateHwi_Module_id();
// Get this module's unique id
Bool GateHwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateHwi_Module_heap();
// The heap from which this module allocates memory
Bool GateHwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateHwi_Module_getMask();
// Returns the diagnostics mask for this module
Void GateHwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateHwi_Object GateHwi_Object;
// Opaque internal representation of an instance object
typedef GateHwi_Object *GateHwi_Handle;
// Client reference to an instance object
typedef struct GateHwi_Struct GateHwi_Struct;
// Opaque client structure large enough to hold an instance object
GateHwi_Handle GateHwi_handle(GateHwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateHwi_Struct *GateHwi_struct(GateHwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateHwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateHwi_Params;
Void GateHwi_Params_init(GateHwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateHwi_Handle GateHwi_create(const GateHwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateHwi_construct(GateHwi_Struct *structP, const GateHwi_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateHwi_delete(GateHwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateHwi_destruct(GateHwi_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateHwi_Handle_upCast(GateHwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateHwi_Handle GateHwi_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateHwi_Object_count();
// The number of statically-created instance objects
GateHwi_Handle GateHwi_Object_get(GateHwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateHwi_Handle GateHwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateHwi_Handle GateHwi_Object_next(GateHwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateHwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateHwi_Handle_label(GateHwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateHwi_Handle_name(GateHwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateHwi.xdc
var GateHwi = xdc.useModule('ti.sysbios.gates.GateHwi');
module-wide constants & types
    const GateHwi.Q_BLOCKING// Blocking quality = 1;
    const GateHwi.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateHwi.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateHwi.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateHwi.Params// Instance config-params object;
per-instance creation
    var inst = GateHwi.create// Create an instance-object(params);
const GateHwi.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateHwi.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateHwi_Q_BLOCKING
const GateHwi.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateHwi.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateHwi_Q_PREEMPTING
metaonly config GateHwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateHwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateHwi.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateHwi.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateHwi.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateHwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateHwi.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateMutex
index URL

Mutex Gate

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateMutex uses a Semaphore as the resource locking mechanism. Each GateMutex instance has its own unique Semaphore. This gate can only be used by a Task as a gate can potentially block. This gate cannot be used by a Hwi or Swi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateMutex.xdc
#include <ti/sysbios/gates/GateMutex.h>
Functions
Void | GateMutex_construct// Initialize a new instance object inside the provided structure(GateMutex_Struct *structP, const GateMutex_Params *params);
GateMutex_Handle | GateMutex_create// Allocate and initialize a new instance object and return its handle(const GateMutex_Params *params, Error_Block *eb);
Void | GateMutex_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateMutex_Handle *handleP);
Void | GateMutex_destruct// Finalize the instance object inside the provided structure(GateMutex_Struct *structP);
Void | GateMutex_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateMutex_Params *params);
Functions common to all IGateProvider modules
Bool | GateMutex_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateMutex_handle// Convert this instance structure pointer into an instance handle, GateMutex_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateMutex_Handle_label// The label associated with this instance object, GateMutex_Handle_name// The name of this instance object, GateMutex_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateMutex_Object_count// The number of statically-created instance objects, GateMutex_Object_first// The handle of the first dynamically-created instance object, or NULL, GateMutex_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateMutex_Object_heap// The heap used to allocate dynamically-created instance objects, GateMutex_Object_next// The handle of the next dynamically-created instance object, or NULL, GateMutex_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateMutex_Module_getMask// Returns the diagnostics mask for this module, GateMutex_Module_hasMask// Test whether this module has a diagnostics mask, GateMutex_Module_heap// The heap from which this module allocates memory, GateMutex_Module_id// Get this module's unique id, GateMutex_Module_setMask// Set the diagnostics mask for this module, GateMutex_Module_startupDone// Test if this module has completed startup
Defines
#define | GateMutex_Q_BLOCKING// Blocking quality (Int)1
#define | GateMutex_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateMutex_Object * | GateMutex_Handle// Client reference to an instance object;
typedef struct | GateMutex_Object// Opaque internal representation of an instance object GateMutex_Object;
typedef struct | GateMutex_Params// Instance config-params structure ...
typedef struct | GateMutex_Struct// Opaque client structure large enough to hold an instance object GateMutex_Struct;
Constants
extern const Assert_Id | GateMutex_A_badContext// Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi);
DETAILS
GateMutex uses a Semaphore as the resource locking mechanism. Each GateMutex instance has its own unique Semaphore. This gate can only be used by a Task as a gate can potentially block. This gate cannot be used by a Hwi or Swi.
The task that uses a gate can call enter() any number of times without risk of being blocked, although relinquishing ownership of the gate requires a balanced number of calls to leave().

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | N | N | Y | Y | N
enter | N | N | Y | N | N
leave | N | N | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateMutex_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateMutex_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateMutex_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateMutex_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateMutex_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateMutex_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateMutex_A_badContext // module-wide
index URL

Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi)

C synopsis target-domain
extern const Assert_Id GateMutex_A_badContext;
DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
  • Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
  • Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
  • Use a different type of Gate for BIOS.rtsGateType (ie BIOS.GateHwi or BIOS.GateSwi)
- Calling Memory_alloc() from a Hwi or Swi thread.
  • Use a different Heap manager
GateMutex_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateMutex_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateMutex_Module_id();
// Get this module's unique id
Bool GateMutex_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateMutex_Module_heap();
// The heap from which this module allocates memory
Bool GateMutex_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateMutex_Module_getMask();
// Returns the diagnostics mask for this module
Void GateMutex_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateMutex_Object GateMutex_Object;
// Opaque internal representation of an instance object
typedef GateMutex_Object *GateMutex_Handle;
// Client reference to an instance object
typedef struct GateMutex_Struct GateMutex_Struct;
// Opaque client structure large enough to hold an instance object
GateMutex_Handle GateMutex_handle(GateMutex_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateMutex_Struct *GateMutex_struct(GateMutex_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateMutex_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateMutex_Params;
Void GateMutex_Params_init(GateMutex_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateMutex_Handle GateMutex_create(const GateMutex_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateMutex_construct(GateMutex_Struct *structP, const GateMutex_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateMutex_delete(GateMutex_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateMutex_destruct(GateMutex_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateMutex_Handle_upCast(GateMutex_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateMutex_Handle GateMutex_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateMutex_Object_count();
// The number of statically-created instance objects
GateMutex_Handle GateMutex_Object_get(GateMutex_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateMutex_Handle GateMutex_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateMutex_Handle GateMutex_Object_next(GateMutex_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateMutex_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateMutex_Handle_label(GateMutex_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateMutex_Handle_name(GateMutex_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateMutex.xdc
var GateMutex = xdc.useModule('ti.sysbios.gates.GateMutex');
module-wide constants & types
    const GateMutex.Q_BLOCKING// Blocking quality = 1;
    const GateMutex.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateMutex.A_badContext// Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi) = Assert.Desc {
        msg: "A_badContext: bad calling context. See GateMutex API doc for details."
    };
     GateMutex.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateMutex.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateMutex.Params// Instance config-params object;
per-instance creation
    var inst = GateMutex.create// Create an instance-object(params);
const GateMutex.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateMutex.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateMutex_Q_BLOCKING
const GateMutex.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateMutex.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateMutex_Q_PREEMPTING
config GateMutex.A_badContext // module-wide
index URL

Assert when GateMutex_enter() is not called from correct context. GateMutex_enter() can only be called from main() or Task context (not Hwi or Swi)

XDCscript usage meta-domain
GateMutex.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. See GateMutex API doc for details."
};
DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
  • Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
  • Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
  • Use a different type of Gate for BIOS.rtsGateType (ie BIOS.GateHwi or BIOS.GateSwi)
- Calling Memory_alloc() from a Hwi or Swi thread.
  • Use a different Heap manager
C SYNOPSIS
GateMutex_A_badContext
metaonly config GateMutex.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateMutex.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateMutex.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateMutex.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateMutex.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateMutex.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateMutex.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateMutexPri
index URL

Mutex Gate with priority inheritance

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateMutexPri is a mutex gate (it can only be held by one thread at a time) which implements priority inheritance in order to prevent priority inversion. Priority inversion occurs when a high priority task has its priority effectively 'inverted' because it is waiting on a gate held by a low priority task. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateMutexPri.xdc
#include <ti/sysbios/gates/GateMutexPri.h>
Functions
Void | GateMutexPri_construct// Initialize a new instance object inside the provided structure(GateMutexPri_Struct *structP, const GateMutexPri_Params *params);
GateMutexPri_Handle | GateMutexPri_create// Allocate and initialize a new instance object and return its handle(const GateMutexPri_Params *params, Error_Block *eb);
Void | GateMutexPri_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateMutexPri_Handle *handleP);
Void | GateMutexPri_destruct// Finalize the instance object inside the provided structure(GateMutexPri_Struct *structP);
Void | GateMutexPri_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateMutexPri_Params *params);
Functions common to all IGateProvider modules
Bool | GateMutexPri_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateMutexPri_handle// Convert this instance structure pointer into an instance handle, GateMutexPri_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateMutexPri_Handle_label// The label associated with this instance object, GateMutexPri_Handle_name// The name of this instance object, GateMutexPri_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateMutexPri_Object_count// The number of statically-created instance objects, GateMutexPri_Object_first// The handle of the first dynamically-created instance object, or NULL, GateMutexPri_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateMutexPri_Object_heap// The heap used to allocate dynamically-created instance objects, GateMutexPri_Object_next// The handle of the next dynamically-created instance object, or NULL, GateMutexPri_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateMutexPri_Module_getMask// Returns the diagnostics mask for this module, GateMutexPri_Module_hasMask// Test whether this module has a diagnostics mask, GateMutexPri_Module_heap// The heap from which this module allocates memory, GateMutexPri_Module_id// Get this module's unique id, GateMutexPri_Module_setMask// Set the diagnostics mask for this module, GateMutexPri_Module_startupDone// Test if this module has completed startup
Defines
#define | GateMutexPri_Q_BLOCKING// Blocking quality (Int)1
#define | GateMutexPri_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateMutexPri_Object * | GateMutexPri_Handle// Client reference to an instance object;
typedef struct | GateMutexPri_Object// Opaque internal representation of an instance object GateMutexPri_Object;
typedef struct | GateMutexPri_Params// Instance config-params structure ...
typedef struct | GateMutexPri_Struct// Opaque client structure large enough to hold an instance object GateMutexPri_Struct;
Constants
extern const Assert_Id | GateMutexPri_A_badContext// Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi);
DETAILS
GateMutexPri is a mutex gate (it can only be held by one thread at a time) which implements priority inheritance in order to prevent priority inversion. Priority inversion occurs when a high priority task has its priority effectively 'inverted' because it is waiting on a gate held by a low priority task.
When multiple tasks wait on this gate, they will receive the gate in order of priority (higher priority tasks will receive the gate first). This is because the queue of tasks waiting on a GateMutexPri is sorted by priority, not FIFO.

Problem: Priority Inversion

The following example demonstrates priority inversion. A system has three tasks, Low, Med, and High, each with the priority suggested by its name. Task Low runs first and acquires the gate. Task High is scheduled and preempts Low. Task High tries to acquire the gate, and waits on it. Next, task Med is scheduled and preempts task Low. Now task High must wait for both task Med and task Low to finish before it can continue. In this situation, task Low has in effect lowered task High's priority to that of Low.

Solution: Priority Inheritance

To guard against priority inversion, GateMutexPri implements priority inheritance: when task High tries to acquire a gate that is owned by task Low, task Low's priority will be temporarily raised to that of High, as long as High is waiting on the gate. Task High will "donate" its priority to task Low. When multiple tasks wait on the gate, the gate owner will receive the highest priority of any of the tasks waiting on the gate.

Caveats

Priority inheritance is not a complete guard against priority inversion. Tasks only donate priority on the call to gate, so if a task has its priority raised while waiting on a gate, that priority will not carry through to the gate owner. This can occur in situations involving multiple gates. A system has four tasks: VeryLow, Low, Med, and High, each with the priority suggested by its name. Task VeryLow runs first and acquires gate A. Task Low runs next and acquires gate B, then waits on gate A. Task High runs and waits on gate B. Task High has donated its priority to task Low, but Low is blocked on VeryLow, so priority inversion occurs despite the use of the gate. The solution to this problem is to design around it. If gate A may be needed by a high-priority, time-critical task, then it should be a design rule that no task holds this gate for a long time, or blocks while holding this gate.

Miscellaneous

Calls to enter() may block, so this gate can only be used in the task context. GateMutexPri is non-deterministic on calls to gate because it keeps the queue of waiting tasks sorted by priority.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
enter | N | N | Y | Y** | N
leave | N | N | Y | Y** | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateMutexPri_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateMutexPri_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateMutexPri_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateMutexPri_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateMutexPri_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateMutexPri_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateMutexPri_A_badContext // module-wide
index URL

Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi)

C synopsis target-domain
extern const Assert_Id GateMutexPri_A_badContext;
DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
  • Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
  • Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
  • Use a different type of Gate for BIOS.rtsGateType (ie BIOS.GateHwi or BIOS.GateSwi)
- Calling Memory_alloc() from a Hwi or Swi thread.
  • Use a different Heap manager
GateMutexPri_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateMutexPri_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateMutexPri_Module_id();
// Get this module's unique id
Bool GateMutexPri_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateMutexPri_Module_heap();
// The heap from which this module allocates memory
Bool GateMutexPri_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateMutexPri_Module_getMask();
// Returns the diagnostics mask for this module
Void GateMutexPri_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateMutexPri_Object GateMutexPri_Object;
// Opaque internal representation of an instance object
typedef GateMutexPri_Object *GateMutexPri_Handle;
// Client reference to an instance object
typedef struct GateMutexPri_Struct GateMutexPri_Struct;
// Opaque client structure large enough to hold an instance object
GateMutexPri_Handle GateMutexPri_handle(GateMutexPri_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateMutexPri_Struct *GateMutexPri_struct(GateMutexPri_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateMutexPri_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateMutexPri_Params;
Void GateMutexPri_Params_init(GateMutexPri_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateMutexPri_Handle GateMutexPri_create(const GateMutexPri_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateMutexPri_construct(GateMutexPri_Struct *structP, const GateMutexPri_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateMutexPri_delete(GateMutexPri_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateMutexPri_destruct(GateMutexPri_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateMutexPri_Handle_upCast(GateMutexPri_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateMutexPri_Handle GateMutexPri_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateMutexPri_Object_count();
// The number of statically-created instance objects
GateMutexPri_Handle GateMutexPri_Object_get(GateMutexPri_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateMutexPri_Handle GateMutexPri_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateMutexPri_Handle GateMutexPri_Object_next(GateMutexPri_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateMutexPri_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateMutexPri_Handle_label(GateMutexPri_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateMutexPri_Handle_name(GateMutexPri_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateMutexPri.xdc
var GateMutexPri = xdc.useModule('ti.sysbios.gates.GateMutexPri');
module-wide constants & types
    const GateMutexPri.Q_BLOCKING// Blocking quality = 1;
    const GateMutexPri.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateMutexPri.A_badContext// Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi) = Assert.Desc {
        msg: "A_badContext: bad calling context. See GateMutexPri API doc for details."
    };
     GateMutexPri.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateMutexPri.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateMutexPri.Params// Instance config-params object;
per-instance creation
    var inst = GateMutexPri.create// Create an instance-object(params);
const GateMutexPri.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateMutexPri.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateMutexPri_Q_BLOCKING
const GateMutexPri.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateMutexPri.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateMutexPri_Q_PREEMPTING
config GateMutexPri.A_badContext // module-wide
index URL

Assert when GateMutexPri_enter() is not called from correct context. GateMutexPri_enter() can only be called from main() or Task context (not Hwi or Swi)

XDCscript usage meta-domain
GateMutexPri.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. See GateMutexPri API doc for details."
};
DETAILS
Common causes and workarounds for hitting this Assert:
- Calling printf() from a Hwi or Swi thread.
  • Use xdc.runtime.System_printf (with SysMin) instead.
- Calling System_printf() from a Hwi or Swi thread when using SysStd.
  • Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
  • Use a different type of Gate for BIOS.rtsGateType (ie BIOS.GateHwi or BIOS.GateSwi)
- Calling Memory_alloc() from a Hwi or Swi thread.
  • Use a different Heap manager
C SYNOPSIS
GateMutexPri_A_badContext
metaonly config GateMutexPri.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateMutexPri.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateMutexPri.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateMutexPri.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateMutexPri.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateMutexPri.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateMutexPri.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateSwi
index URL

Software Interrupt Gate

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateSwi uses disabling and enabling of software interrupts as the resource locking mechanism. This gate can be used whenever the resource is being shared by Swis or Tasks. This gate cannot be used by a Hwi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateSwi.xdc
#include <ti/sysbios/gates/GateSwi.h>
Functions
Void | GateSwi_construct// Initialize a new instance object inside the provided structure(GateSwi_Struct *structP, const GateSwi_Params *params);
GateSwi_Handle | GateSwi_create// Allocate and initialize a new instance object and return its handle(const GateSwi_Params *params, Error_Block *eb);
Void | GateSwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateSwi_Handle *handleP);
Void | GateSwi_destruct// Finalize the instance object inside the provided structure(GateSwi_Struct *structP);
Void | GateSwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateSwi_Params *params);
Functions common to all IGateProvider modules
Bool | GateSwi_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateSwi_handle// Convert this instance structure pointer into an instance handle, GateSwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateSwi_Handle_label// The label associated with this instance object, GateSwi_Handle_name// The name of this instance object, GateSwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateSwi_Object_count// The number of statically-created instance objects, GateSwi_Object_first// The handle of the first dynamically-created instance object, or NULL, GateSwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateSwi_Object_heap// The heap used to allocate dynamically-created instance objects, GateSwi_Object_next// The handle of the next dynamically-created instance object, or NULL, GateSwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateSwi_Module_getMask// Returns the diagnostics mask for this module, GateSwi_Module_hasMask// Test whether this module has a diagnostics mask, GateSwi_Module_heap// The heap from which this module allocates memory, GateSwi_Module_id// Get this module's unique id, GateSwi_Module_setMask// Set the diagnostics mask for this module, GateSwi_Module_startupDone// Test if this module has completed startup
Defines
#define | GateSwi_Q_BLOCKING// Blocking quality (Int)1
#define | GateSwi_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateSwi_Object * | GateSwi_Handle// Client reference to an instance object;
typedef struct | GateSwi_Object// Opaque internal representation of an instance object GateSwi_Object;
typedef struct | GateSwi_Params// Instance config-params structure ...
typedef struct | GateSwi_Struct// Opaque client structure large enough to hold an instance object GateSwi_Struct;
Constants
extern const Assert_Id | GateSwi_A_badContext// Asserted when enter or leave is called from a hardware interrupt thread;
DETAILS
GateSwi uses disabling and enabling of software interrupts as the resource locking mechanism. This gate can be used whenever the resource is being shared by Swis or Tasks. This gate cannot be used by a Hwi.
The duration between the enter and leave should be as short as possible to minimize Swi latency.
GateSwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
enter | N | Y | Y | Y** | N
leave | N | Y | Y | Y** | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateSwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateSwi_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateSwi_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateSwi_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateSwi_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateSwi_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateSwi_A_badContext // module-wide
index URL

Asserted when enter or leave is called from a hardware interrupt thread

C synopsis target-domain
extern const Assert_Id GateSwi_A_badContext;
GateSwi_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateSwi_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateSwi_Module_id();
// Get this module's unique id
Bool GateSwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateSwi_Module_heap();
// The heap from which this module allocates memory
Bool GateSwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateSwi_Module_getMask();
// Returns the diagnostics mask for this module
Void GateSwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateSwi_Object GateSwi_Object;
// Opaque internal representation of an instance object
typedef GateSwi_Object *GateSwi_Handle;
// Client reference to an instance object
typedef struct GateSwi_Struct GateSwi_Struct;
// Opaque client structure large enough to hold an instance object
GateSwi_Handle GateSwi_handle(GateSwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateSwi_Struct *GateSwi_struct(GateSwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateSwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateSwi_Params;
Void GateSwi_Params_init(GateSwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateSwi_Handle GateSwi_create(const GateSwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateSwi_construct(GateSwi_Struct *structP, const GateSwi_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateSwi_delete(GateSwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateSwi_destruct(GateSwi_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateSwi_Handle_upCast(GateSwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateSwi_Handle GateSwi_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateSwi_Object_count();
// The number of statically-created instance objects
GateSwi_Handle GateSwi_Object_get(GateSwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateSwi_Handle GateSwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateSwi_Handle GateSwi_Object_next(GateSwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateSwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateSwi_Handle_label(GateSwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateSwi_Handle_name(GateSwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateSwi.xdc
var GateSwi = xdc.useModule('ti.sysbios.gates.GateSwi');
module-wide constants & types
    const GateSwi.Q_BLOCKING// Blocking quality = 1;
    const GateSwi.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateSwi.A_badContext// Asserted when enter or leave is called from a hardware interrupt thread = Assert.Desc {
        msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."
    };
     GateSwi.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateSwi.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateSwi.Params// Instance config-params object;
per-instance creation
    var inst = GateSwi.create// Create an instance-object(params);
const GateSwi.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateSwi.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateSwi_Q_BLOCKING
const GateSwi.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateSwi.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateSwi_Q_PREEMPTING
config GateSwi.A_badContext // module-wide
index URL

Asserted when enter or leave is called from a hardware interrupt thread

XDCscript usage meta-domain
GateSwi.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."
};
C SYNOPSIS
GateSwi_A_badContext
metaonly config GateSwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateSwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateSwi.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateSwi.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateSwi.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateSwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateSwi.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


module ti.sysbios.gates.GateTask
index URL

Task Gate

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
GateTask uses disabling and enabling of tasks as the resource locking mechanism. This gate can be used whenever the resource is being shared by Tasks. This gate cannot be used by a Hwi or Swi. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/gates/GateTask.xdc
#include <ti/sysbios/gates/GateTask.h>
Functions
Void | GateTask_construct// Initialize a new instance object inside the provided structure(GateTask_Struct *structP, const GateTask_Params *params);
GateTask_Handle | GateTask_create// Allocate and initialize a new instance object and return its handle(const GateTask_Params *params, Error_Block *eb);
Void | GateTask_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateTask_Handle *handleP);
Void | GateTask_destruct// Finalize the instance object inside the provided structure(GateTask_Struct *structP);
Void | GateTask_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateTask_Params *params);
Functions common to all IGateProvider modules
Bool | GateTask_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateTask_handle// Convert this instance structure pointer into an instance handle, GateTask_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateTask_Handle_label// The label associated with this instance object, GateTask_Handle_name// The name of this instance object, GateTask_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateTask_Object_count// The number of statically-created instance objects, GateTask_Object_first// The handle of the first dynamically-created instance object, or NULL, GateTask_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateTask_Object_heap// The heap used to allocate dynamically-created instance objects, GateTask_Object_next// The handle of the next dynamically-created instance object, or NULL, GateTask_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateTask_Module_getMask// Returns the diagnostics mask for this module, GateTask_Module_hasMask// Test whether this module has a diagnostics mask, GateTask_Module_heap// The heap from which this module allocates memory, GateTask_Module_id// Get this module's unique id, GateTask_Module_setMask// Set the diagnostics mask for this module, GateTask_Module_startupDone// Test if this module has completed startup
Defines
#define | GateTask_Q_BLOCKING// Blocking quality (Int)1
#define | GateTask_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateTask_Object * | GateTask_Handle// Client reference to an instance object;
typedef struct | GateTask_Object// Opaque internal representation of an instance object GateTask_Object;
typedef struct | GateTask_Params// Instance config-params structure ...
typedef struct | GateTask_Struct// Opaque client structure large enough to hold an instance object GateTask_Struct;
Constants
extern const Assert_Id | GateTask_A_badContext// Asserted when enter is called from a hardware/software interrupt thread;
DETAILS
GateTask uses disabling and enabling of tasks as the resource locking mechanism. This gate can be used whenever the resource is being shared by Tasks. This gate cannot be used by a Hwi or Swi.
The duration between the enter and leave should be as short as possible to minimize Task latency.
GateTask inherits from xdc.runtime.IGateProvider, therefore supports nesting.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
query | Y | Y | Y | Y | Y
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
enter | N | N | Y | Y** | N
leave | N | N | Y | Y** | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. GateTask_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. GateTask_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Must be used in enter/leave pairs.
const GateTask_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateTask_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateTask_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateTask_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateTask_A_badContext // module-wide
index URL

Asserted when enter is called from a hardware/software interrupt thread

C synopsis target-domain
extern const Assert_Id GateTask_A_badContext;
GateTask_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateTask_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateTask_Module_id();
// Get this module's unique id
Bool GateTask_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateTask_Module_heap();
// The heap from which this module allocates memory
Bool GateTask_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateTask_Module_getMask();
// Returns the diagnostics mask for this module
Void GateTask_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateTask_Object GateTask_Object;
// Opaque internal representation of an instance object
typedef GateTask_Object *GateTask_Handle;
// Client reference to an instance object
typedef struct GateTask_Struct GateTask_Struct;
// Opaque client structure large enough to hold an instance object
GateTask_Handle GateTask_handle(GateTask_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateTask_Struct *GateTask_struct(GateTask_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateTask_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateTask_Params;
Void GateTask_Params_init(GateTask_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateTask_Handle GateTask_create(const GateTask_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateTask_construct(GateTask_Struct *structP, const GateTask_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateTask_delete(GateTask_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateTask_destruct(GateTask_Struct *structP);
// Finalize the instance object inside the provided structure
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateTask_Handle_upCast(GateTask_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateTask_Handle GateTask_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateTask_Object_count();
// The number of statically-created instance objects
GateTask_Handle GateTask_Object_get(GateTask_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateTask_Handle GateTask_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateTask_Handle GateTask_Object_next(GateTask_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateTask_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateTask_Handle_label(GateTask_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateTask_Handle_name(GateTask_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/gates/GateTask.xdc
var GateTask = xdc.useModule('ti.sysbios.gates.GateTask');
module-wide constants & types
    const GateTask.Q_BLOCKING// Blocking quality = 1;
    const GateTask.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateTask.A_badContext// Asserted when enter is called from a hardware/software interrupt thread = Assert.Desc {
        msg: "A_badContext: bad calling context. May not be entered from a software or hardware interrupt thread."
    };
     GateTask.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateTask.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateTask.Params// Instance config-params object;
per-instance creation
    var inst = GateTask.create// Create an instance-object(params);
const GateTask.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateTask.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateTask_Q_BLOCKING
const GateTask.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateTask.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateTask_Q_PREEMPTING
config GateTask.A_badContext // module-wide
index URL

Asserted when enter is called from a hardware/software interrupt thread

XDCscript usage meta-domain
GateTask.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. May not be entered from a software or hardware interrupt thread."
};
C SYNOPSIS
GateTask_A_badContext
metaonly config GateTask.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateTask.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateTask.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateTask.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateTask.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateTask.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateTask.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:48 GMT


package ti.sysbios.hal
index URL

Contains Hardware Abstraction Layer (HAL) modules for the SYS/BIOS kernel

SYS/BIOS provides services for configuration and management of interrupts, cache, and timers. Unlike other SYS/BIOS services such as threading, these modules directly program aspects of a device's hardware and are grouped together in the Hardware Abstraction Layer (HAL) package. These modules provide services such as enabling and disabling interrupts, plugging of interrupt vectors, multiplexing of multiple interrupts to a single vector, and cache invalidation or writeback. [ more ... ]
XDCspec declarations sourced in ti/sysbios/hal/package.xdc
requires ti.sysbios.interfaces;
requires ti.sysbios.family;
package ti.sysbios.hal [2, 0, 0, 0] {
    module Cache;
    // Cache Manager Proxy
    module CacheNull;
    // Null Cache module
    module Hwi;
    // Hardware Interrupt Manager Proxy
    module Timer;
    // Timer Manager Proxy
    module TimerNull;
    // Null Timer module
}
DETAILS
SYS/BIOS provides services for configuration and management of interrupts, cache, and timers. Unlike other SYS/BIOS services such as threading, these modules directly program aspects of a device's hardware and are grouped together in the Hardware Abstraction Layer (HAL) package. These modules provide services such as enabling and disabling interrupts, plugging of interrupt vectors, multiplexing of multiple interrupts to a single vector, and cache invalidation or writeback.
The HAL APIs fall into two categories:
  • Generic APIs that are available across all targets and devices.
  • Target/device-specific APIs that are available only for a specific device or ISA family
The generic APIs are designed to cover the great majority of use cases. If you are concerned with easy portability between different TI devices, you should use the generic APIs as much as possible. However, if the generic APIs cannot enable use of a device-specific hardware feature that is advantageous to the software application, you may choose to use the target/device-specific APIs.
The ti.sysbios.hal.Hwi, ti.sysbios.hal.Timer, and ti.sysbios.hal.Cache modules require target/device-specific API implementations to achieve their functionality. To provide a common set of APIs for these modules across all supported families/devices, SYS/BIOS uses the RTSC proxy-delegate module mechanism. That is, each of these modules serves as a proxy for a corresponding target/device-specific module implementation.
During the configuration step of the application build, the modules in the ti.sysbios.hal package locate and bind themselves to appropriate delegate module implementations based on the current target and platform specified in your config.bld file. The delegate binding process is done internally.
For example, if your config.bld file specifies that one of your build targets is the C64P family, the ti.sysbios.hal.Hwi knows to bind itself to the ti.sysbios.family.c64p.Hwi implementation.
generated on Fri, 17 Jun 2011 00:22:35 GMT


module ti.sysbios.hal.Cache
index URL

Cache Manager Proxy

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module is a proxy to the generic Cache module functions as defined in ICache.xdc. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/Cache.xdc
#include <ti/sysbios/hal/Cache.h>
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Cache_Type// Lists of bitmask cache types ...
DETAILS
This module is a proxy to the generic Cache module functions as defined in ICache.xdc.
The actual implementations of the Cache module functions are provided by the Cache module delegates.
Additional, family-specific Cache module APIs may also be provided by the Cache module delegates.
Follow the link below to determine which Cache delegate is used for your Target/Device:
Delegate Mappings

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/hal/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.hal.Cache');
module-wide constants & types
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
module-wide config parameters
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:34 GMT


module ti.sysbios.hal.CacheNull
index URL

Null Cache module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/hal/CacheNull.xdc
#include <ti/sysbios/hal/CacheNull.h>
Functions common to all ICache modules
Void | CacheNull_disable// Disables the 'type' cache(s)(Bits16 type);
Void | CacheNull_enable// Enables all cache(s)(Bits16 type);
Void | CacheNull_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | CacheNull_wait// Wait for a previous cache operation to complete();
Void | CacheNull_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | CacheNull_wbAll// Write back all caches();
Void | CacheNull_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | CacheNull_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | CacheNull_Module_getMask// Returns the diagnostics mask for this module, CacheNull_Module_hasMask// Test whether this module has a diagnostics mask, CacheNull_Module_heap// The heap from which this module allocates memory, CacheNull_Module_id// Get this module's unique id, CacheNull_Module_setMask// Set the diagnostics mask for this module, CacheNull_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | CacheNull_Type// Lists of bitmask cache types ...
enum CacheNull_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum CacheNull_Type {
    CacheNull_Type_L1P,
    // Level 1 Program cache
    CacheNull_Type_L1D,
    // Level 1 Data cache
    CacheNull_Type_L1,
    // Level 1 caches
    CacheNull_Type_L2P,
    // Level 2 Program cache
    CacheNull_Type_L2D,
    // Level 2 Data cache
    CacheNull_Type_L2,
    // Level 2 caches
    CacheNull_Type_ALLP,
    // All Program caches
    CacheNull_Type_ALLD,
    // All Data caches
    CacheNull_Type_ALL
    // All caches
} CacheNull_Type;
CacheNull_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void CacheNull_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
CacheNull_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void CacheNull_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
CacheNull_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void CacheNull_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
CacheNull_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void CacheNull_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
CacheNull_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void CacheNull_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
CacheNull_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void CacheNull_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
CacheNull_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void CacheNull_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
CacheNull_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void CacheNull_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId CacheNull_Module_id();
// Get this module's unique id
Bool CacheNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle CacheNull_Module_heap();
// The heap from which this module allocates memory
Bool CacheNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 CacheNull_Module_getMask();
// Returns the diagnostics mask for this module
Void CacheNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/hal/CacheNull.xdc
var CacheNull = xdc.useModule('ti.sysbios.hal.CacheNull');
module-wide constants & types
    values of type CacheNull.Type// Lists of bitmask cache types
        const CacheNull.Type_L1P// Level 1 Program cache;
        const CacheNull.Type_L1D// Level 1 Data cache;
        const CacheNull.Type_L1// Level 1 caches;
        const CacheNull.Type_L2P// Level 2 Program cache;
        const CacheNull.Type_L2D// Level 2 Data cache;
        const CacheNull.Type_L2// Level 2 caches;
        const CacheNull.Type_ALLP// All Program caches;
        const CacheNull.Type_ALLD// All Data caches;
        const CacheNull.Type_ALL// All caches;
module-wide config parameters
     CacheNull.common$// Common module configuration parameters = Types.Common$ undefined;
enum CacheNull.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type CacheNull.Type
    const CacheNull.Type_L1P;
    // Level 1 Program cache
    const CacheNull.Type_L1D;
    // Level 1 Data cache
    const CacheNull.Type_L1;
    // Level 1 caches
    const CacheNull.Type_L2P;
    // Level 2 Program cache
    const CacheNull.Type_L2D;
    // Level 2 Data cache
    const CacheNull.Type_L2;
    // Level 2 caches
    const CacheNull.Type_ALLP;
    // All Program caches
    const CacheNull.Type_ALLD;
    // All Data caches
    const CacheNull.Type_ALL;
    // All caches
C SYNOPSIS
CacheNull_Type
metaonly config CacheNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
CacheNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:34 GMT


module ti.sysbios.hal.Hwi
index URL

Hardware Interrupt Manager Proxy

  • C synopsis
  • Individual elements
  • DETAILS
  • RUNTIME HWI CREATION
  • HOOK FUNCTIONS
  • XDCscript usage
  • Individual elements
This module provides APIs for managing hardware interrupts. These APIs are generic across all supported targets and devices and should provide sufficient functionality for most applications. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/Hwi.xdc
#include <ti/sysbios/hal/Hwi.h>
Functions
Void | Hwi_construct// Initialize a new instance object inside the provided structure(Hwi_Struct *structP, Int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Hwi_Handle | Hwi_create// Allocate and initialize a new instance object and return its handle(Int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
Void | Hwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Hwi_Handle *handleP);
Void | Hwi_destruct// Finalize the instance object inside the provided structure(Hwi_Struct *structP);
Void | Hwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Hwi_Params *params);
Functions common to all IHwi modules
Void | Hwi_clearInterrupt// Clear a specific interrupt(UInt intNum);
macro UInt | Hwi_disable// Globally disable interrupts();
UInt | Hwi_disableInterrupt// Disable a specific interrupt(UInt intNum);
macro UInt | Hwi_enable// Globally enable interrupts();
UInt | Hwi_enableInterrupt// Enable a specific interrupt(UInt intNum);
IHwi_FuncPtr | Hwi_getFunc// Get Hwi function and arg(Hwi_Handle handle, UArg *arg);
Ptr | Hwi_getHookContext// Get hook instance's context for a Hwi(Hwi_Handle handle, Int id);
IHwi_Irp | Hwi_getIrp// Get address of interrupted instruction(Hwi_Handle handle);
macro Void | Hwi_restore// Globally restore interrupts(UInt key);
Void | Hwi_restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
Void | Hwi_setFunc// Overwrite Hwi function and arg(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
Void | Hwi_setHookContext// Set hook instance's context for a Hwi(Hwi_Handle handle, Int id, Ptr hookContext);
Void | Hwi_startup// Initially enable interrupts();
Functions common to all target instances
 | Hwi_handle// Convert this instance structure pointer into an instance handle, Hwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Hwi_Handle_label// The label associated with this instance object, Hwi_Handle_name// The name of this instance object, Hwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Hwi_Object_count// The number of statically-created instance objects, Hwi_Object_first// The handle of the first dynamically-created instance object, or NULL, Hwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Hwi_Object_heap// The heap used to allocate dynamically-created instance objects, Hwi_Object_next// The handle of the next dynamically-created instance object, or NULL, Hwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Hwi_Module_getMask// Returns the diagnostics mask for this module, Hwi_Module_hasMask// Test whether this module has a diagnostics mask, Hwi_Module_heap// The heap from which this module allocates memory, Hwi_Module_id// Get this module's unique id, Hwi_Module_setMask// Set the diagnostics mask for this module, Hwi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Hwi_FuncPtr// Hwi create function type definition)(UArg);
typedef Hwi_Object * | Hwi_Handle// Client reference to an instance object;
typedef struct | Hwi_HookSet// Hwi hook set type definition ...
typedef UArg | Hwi_Irp// Interrupt Return Pointer;
typedef enum | Hwi_MaskingOption// Shorthand interrupt masking options ...
typedef struct | Hwi_Object// Opaque internal representation of an instance object Hwi_Object;
typedef struct | Hwi_Params// Instance config-params structure ...
typedef struct | Hwi_Struct// Opaque client structure large enough to hold an instance object Hwi_Struct;
Constants
extern const Bool | Hwi_dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address;
extern const Bool | Hwi_dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
extern const Bool | Hwi_dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
extern const Error_Id | Hwi_E_stackOverflow// Error raised when a stack overflow (or corruption) is detected;
DETAILS
This module provides APIs for managing hardware interrupts. These APIs are generic across all supported targets and devices and should provide sufficient functionality for most applications.
The actual implementations of the Hwi module APIs are provided by the Hwi module delegates. Additional, family-specific Hwi module APIs may also be provided by the Hwi module delegates. See the list of Delegate Mappings to determine which Hwi delegate is used for your target/device.
You can statically or dynamically assign functions that run when specific hardware interrupts occur. Dynamic assignment of Hwi functions to interrupts at run-time is done using the Hwi_create function.
Interrupt routines can be written completely in C, completely in assembly, or in a mix of C and assembly. In order to support interrupt routines written completely in C, an interrupt dispatcher is provided that performs the requisite prolog and epilog for an interrupt routine.
Some routines are assigned to interrupts by the other SYS/BIOS modules. For example, the {@line ti.sysbios.knl.Clock} module configures its own timer interrupt handler.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
clearInterrupt | Y | Y | Y | Y | Y
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | Y
disableInterrupt | Y | Y | Y | Y | N
enable | Y | Y | Y | N | N
enableInterrupt | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | Y
restoreInterrupt | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).
RUNTIME HWI CREATION
Below is an example that configures an interrupt at runtime. Typically such code would be placed in main().
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/hal/Hwi.h>

  Hwi_Handle myHwi;

  Int main(Int argc, char* argv[])
  {
      Hwi_Params hwiParams;
      Error_Block eb;

      Hwi_Params_init(&hwiParams);
      Error_init(&eb);

      // set the argument you want passed to your ISR function
      hwiParams.arg = 1;

      // set the event id of the peripheral assigned to this interrupt
      hwiParams.eventId = 10;

      // don't allow this interrupt to nest itself
      hwiParams.maskSetting = Hwi_MaskingOption_SELF;

      //
      // Configure interrupt 5 to invoke "myIsr".
      // Automatically enables interrupt 5 by default
      // set params.enableInt = FALSE if you want to control
      // when the interrupt is enabled using Hwi_enableInterrupt()
      //

      myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);

      if (Error_check(&eb)) {
          // handle the error
      }
  }

  Void myIsr(UArg arg)
  {
      // this runs when interrupt #5 goes off
  }
HOOK FUNCTIONS
Sets of hook functions can be specified for the Hwi module using the configuration tool. Each set contains these hook functions:
  • Register: A function called before any statically-created Hwis are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
  • Create: A function that is called when a Hwi is created. This includes hwis that are created statically and those created dynamically using Hwi_create.
  • Begin: A function that is called just prior to running a Hwi.
  • End: A function that is called just after a Hwi finishes.
  • Delete: A function that is called when a Hwi is deleted at run-time with Hwi_delete.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Hwi_setHookContext and Hwi_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Hwi_setHookContext or Hwi_getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete Functions
The create and delete functions are called whenever a Hwi is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).
  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);

  Void myDeleteFxn(Hwi_Handle hwi);
Begin and End Functions
The beginFxn and endFxn function hooks are called with interrupts globally disabled, therefore any hook processing function will contribute to the overall system interrupt response latency. In order to minimize this impact, carefully consider the processing time spent in an Hwi beginFxn or endFxn function hook.
  Void myBeginFxn(Hwi_Handle hwi);

  Void myEndFxn(Hwi_Handle hwi);
Hook functions can only be configured statically.
enum Hwi_MaskingOption
index URL

Shorthand interrupt masking options

C synopsis target-domain
typedef enum Hwi_MaskingOption {
    Hwi_MaskingOption_NONE,
    Hwi_MaskingOption_ALL,
    Hwi_MaskingOption_SELF,
    Hwi_MaskingOption_BITMASK,
    Hwi_MaskingOption_LOWER
} Hwi_MaskingOption;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef Hwi_FuncPtr
index URL

Hwi create function type definition

C synopsis target-domain
typedef Void (*Hwi_FuncPtr)(UArg);
typedef Hwi_Irp
index URL

Interrupt Return Pointer

C synopsis target-domain
typedef UArg Hwi_Irp;
DETAILS
This is the address of the interrupted instruction.
struct Hwi_HookSet
index URL

Hwi hook set type definition

C synopsis target-domain
typedef struct Hwi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi_Handle,Error_Block*);
    Void (*beginFxn)(IHwi_Handle);
    Void (*endFxn)(IHwi_Handle);
    Void (*deleteFxn)(IHwi_Handle);
} Hwi_HookSet;
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config Hwi_E_stackOverflow // module-wide
index URL

Error raised when a stack overflow (or corruption) is detected

C synopsis target-domain
extern const Error_Id Hwi_E_stackOverflow;
DETAILS
This error is raised by kernel's stack checking function. This function checks the stacks before every task switch to make sure that reserved word at top of stack has not been modified.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stacks.
config Hwi_dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherAutoNestingSupport;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config Hwi_dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

C synopsis target-domain
extern const Bool Hwi_dispatcherIrpTrackingSupport;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config Hwi_dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config Hwi_dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

C synopsis target-domain
extern const Bool Hwi_dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
Hwi_clearInterrupt() // module-wide
index URL

Clear a specific interrupt

C synopsis target-domain
Void Hwi_clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
Hwi_disable() // module-wide
index URL

Globally disable interrupts

C synopsis target-domain
macro UInt Hwi_disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
Hwi_disableInterrupt() // module-wide
index URL

Disable a specific interrupt

C synopsis target-domain
UInt Hwi_disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
Hwi_enable() // module-wide
index URL

Globally enable interrupts

C synopsis target-domain
macro UInt Hwi_enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
Hwi_enableInterrupt() // module-wide
index URL

Enable a specific interrupt

C synopsis target-domain
UInt Hwi_enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
Hwi_restore() // module-wide
index URL

Globally restore interrupts

C synopsis target-domain
macro Void Hwi_restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
Hwi_restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

C synopsis target-domain
Void Hwi_restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
Hwi_startup() // module-wide
index URL

Initially enable interrupts

C synopsis target-domain
Void Hwi_startup();
DETAILS
Called within BIOS_start
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Hwi_Module_id();
// Get this module's unique id
Bool Hwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Hwi_Module_heap();
// The heap from which this module allocates memory
Bool Hwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Hwi_Module_getMask();
// Returns the diagnostics mask for this module
Void Hwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Hwi_Object Hwi_Object;
// Opaque internal representation of an instance object
typedef Hwi_Object *Hwi_Handle;
// Client reference to an instance object
typedef struct Hwi_Struct Hwi_Struct;
// Opaque client structure large enough to hold an instance object
Hwi_Handle Hwi_handle(Hwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Hwi_Struct *Hwi_struct(Hwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Hwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // ISR function argument. Default is 0
    Bool enableInt;
    // Enable this interrupt now? Default is true
    Int eventId;
    // Interrupt event ID (Interrupt Selection Number)
     IHwi_MaskingOption maskSetting;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    Int priority;
    // Interrupt priority
} Hwi_Params;
Void Hwi_Params_init(Hwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Hwi_arg // instance
index URL

ISR function argument. Default is 0

C synopsis target-domain
struct Hwi_Params {
     ...
    UArg arg;
config Hwi_enableInt // instance
index URL

Enable this interrupt now? Default is true

C synopsis target-domain
struct Hwi_Params {
     ...
    Bool enableInt;
config Hwi_eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

C synopsis target-domain
struct Hwi_Params {
     ...
    Int eventId;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config Hwi_maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

C synopsis target-domain
struct Hwi_Params {
     ...
     IHwi_MaskingOption maskSetting;
config Hwi_priority // instance
index URL

Interrupt priority

C synopsis target-domain
struct Hwi_Params {
     ...
    Int priority;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Instance Creation
index URL

C synopsis target-domain
Hwi_Handle Hwi_create(Int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Hwi_construct(Hwi_Struct *structP, Int intNum, Hwi_FuncPtr hwiFxn, const Hwi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
To cause a C function to run in response to a particular system interrupt, you create a Hwi object that encapsulates information regarding the interrupt required by the Hwi module.
The standard static and dynamic forms of the "create" function are supported by the ti.sysbios.hal.Hwi module. The following C code configures interrupt 5 with the "myIsr" C function.
  #include <ti/sysbios/hal/Hwi>

  Hwi_create(5, myIsr, NULL, NULL);
The NULL, NULL arguments are used when the default instance parameters and generic error handling is satisfactory for creating a Hwi object.
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
Instance Deletion
index URL

C synopsis target-domain
Void Hwi_delete(Hwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Hwi_destruct(Hwi_Struct *structP);
// Finalize the instance object inside the provided structure
Hwi_getFunc() // instance
index URL

Get Hwi function and arg

C synopsis target-domain
IHwi_FuncPtr Hwi_getFunc(Hwi_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
Hwi_getHookContext() // instance
index URL

Get hook instance's context for a Hwi

C synopsis target-domain
Ptr Hwi_getHookContext(Hwi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
hook instance's context for hwi
hook instance's context for hwi
DETAILS
The Handle passed to this API must be the handle passed to any of the Hook functions, not the one returned by Hwi_create.
Hwi_getIrp() // instance
index URL

Get address of interrupted instruction

C synopsis target-domain
IHwi_Irp Hwi_getIrp(Hwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
RETURNS
most current IRP of a Hwi
Hwi_setFunc() // instance
index URL

Overwrite Hwi function and arg

C synopsis target-domain
Void Hwi_setFunc(Hwi_Handle handle, IHwi_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
Hwi_setHookContext() // instance
index URL

Set hook instance's context for a Hwi

C synopsis target-domain
Void Hwi_setHookContext(Hwi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Hwi instance object
id — hook instance's ID
hook instance's ID
hookContext — value to write to context
value to write to context
DETAILS
The Handle passed to this API must be the handle passed to any of the Hook functions, not the one returned by Hwi_create.
Instance Convertors
index URL

C synopsis target-domain
IHwi_Handle Hwi_Handle_upCast(Hwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Hwi_Handle Hwi_Handle_downCast(IHwi_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Hwi_Object_count();
// The number of statically-created instance objects
Hwi_Handle Hwi_Object_get(Hwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Hwi_Handle Hwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Hwi_Handle Hwi_Object_next(Hwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Hwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Hwi_Handle_label(Hwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Hwi_Handle_name(Hwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/hal/Hwi.xdc
var Hwi = xdc.useModule('ti.sysbios.hal.Hwi');
module-wide constants & types
    values of type Hwi.MaskingOption// Shorthand interrupt masking options
        const Hwi.MaskingOption_NONE;
        const Hwi.MaskingOption_ALL;
        const Hwi.MaskingOption_SELF;
        const Hwi.MaskingOption_BITMASK;
        const Hwi.MaskingOption_LOWER;
    var obj = new Hwi.HookSet// Hwi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
        obj.beginFxn = Void(*)(IHwi.Handle) ...
        obj.endFxn = Void(*)(IHwi.Handle) ...
        obj.deleteFxn = Void(*)(IHwi.Handle) ...
module-wide config parameters
     Hwi.E_stackOverflow// Error raised when a stack overflow (or corruption) is detected = Error.Desc {
        msg: "E_stackOverflow: ISR stack overflow."
    };
     Hwi.dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = Bool true;
     Hwi.dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = Bool true;
     Hwi.dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher? = Bool undefined;
     Hwi.checkStackFlag// Check for Hwi stack overrun during Idle loop = Bool true;
     Hwi.common$// Common module configuration parameters = Types.Common$ undefined;
     Hwi.initStackFlag// Initialize ISR stack with known value for stack checking at runtime = Bool true;
module-wide functions
     Hwi.addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook) returns Void
per-instance config parameters
    var params = new Hwi.Params// Instance config-params object;
        params.arg// ISR function argument. Default is 0 = UArg 0;
        params.enableInt// Enable this interrupt now? Default is true = Bool true;
        params.eventId// Interrupt event ID (Interrupt Selection Number) = Int -1;
        params.maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption IHwi.MaskingOption_SELF;
        params.priority// Interrupt priority = Int -1;
per-instance creation
    var inst = Hwi.create// Create an instance-object(Int intNum, Void(*)(UArg) hwiFxn, params);
enum Hwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCscript usage meta-domain
values of type Hwi.MaskingOption
    const Hwi.MaskingOption_NONE;
    const Hwi.MaskingOption_ALL;
    const Hwi.MaskingOption_SELF;
    const Hwi.MaskingOption_BITMASK;
    const Hwi.MaskingOption_LOWER;
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
C SYNOPSIS
Hwi_MaskingOption
struct Hwi.HookSet
index URL

Hwi hook set type definition

XDCscript usage meta-domain
var obj = new Hwi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(IHwi.Handle,Error.Block*) ...
    obj.beginFxn = Void(*)(IHwi.Handle) ...
    obj.endFxn = Void(*)(IHwi.Handle) ...
    obj.deleteFxn = Void(*)(IHwi.Handle) ...
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
C SYNOPSIS
Hwi_HookSet
config Hwi.E_stackOverflow // module-wide
index URL

Error raised when a stack overflow (or corruption) is detected

XDCscript usage meta-domain
Hwi.E_stackOverflow = Error.Desc {
    msg: "E_stackOverflow: ISR stack overflow."
};
DETAILS
This error is raised by kernel's stack checking function. This function checks the stacks before every task switch to make sure that reserved word at top of stack has not been modified.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stacks.
C SYNOPSIS
Hwi_E_stackOverflow
config Hwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherAutoNestingSupport = Bool true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
C SYNOPSIS
Hwi_dispatcherAutoNestingSupport
config Hwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCscript usage meta-domain
Hwi.dispatcherIrpTrackingSupport = Bool true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
C SYNOPSIS
Hwi_dispatcherIrpTrackingSupport
config Hwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherSwiSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherSwiSupport
config Hwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCscript usage meta-domain
Hwi.dispatcherTaskSupport = Bool undefined;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
C SYNOPSIS
Hwi_dispatcherTaskSupport
metaonly config Hwi.checkStackFlag // module-wide
index URL

Check for Hwi stack overrun during Idle loop

XDCscript usage meta-domain
Hwi.checkStackFlag = Bool true;
DETAILS
If true, then an idle function is added to the idle loop that checks for a Hwi stack overrun condition and raises an Error if one is detected.
The check consists of testing the top of stack value against its initial value (see initStackFlag). If it is no longer at this value, the assumption is that the ISR stack has been overrun. If the test fails, then the E_stackOverflow error is raised.
Runtime stack checking is only performed if initStackFlag is also true.
Default is true. (see initStackFlag).
To enable or disable full stack checking, you should set both this flag and the ti.sysbios.knl.Task.checkStackFlag.
metaonly config Hwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Hwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Hwi.initStackFlag // module-wide
index URL

Initialize ISR stack with known value for stack checking at runtime

XDCscript usage meta-domain
Hwi.initStackFlag = Bool true;
DETAILS
This is also useful for inspection of stack in debugger or core dump utilities.
Default is true. (see checkStackFlag).
metaonly Hwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCscript usage meta-domain
Hwi.addHookSet(IHwi.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Instance config-params object
    params.arg = UArg 0;
    // ISR function argument. Default is 0
    params.enableInt = Bool true;
    // Enable this interrupt now? Default is true
    params.eventId = Int -1;
    // Interrupt event ID (Interrupt Selection Number)
    params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
    // maskSetting. Default is Hwi_MaskingOption_SELF
    params.priority = Int -1;
    // Interrupt priority
config Hwi.arg // instance
index URL

ISR function argument. Default is 0

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.arg = UArg 0;
C SYNOPSIS
null
config Hwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.enableInt = Bool true;
C SYNOPSIS
null
config Hwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.eventId = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
config Hwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.maskSetting = IHwi.MaskingOption IHwi.MaskingOption_SELF;
C SYNOPSIS
null
config Hwi.priority // instance
index URL

Interrupt priority

XDCscript usage meta-domain
var params = new Hwi.Params;
...
params.priority = Int -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Hwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Hwi.create(Int intNum, Void(*)(UArg) hwiFxn, params);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
To cause a C function to run in response to a particular system interrupt, you create a Hwi object that encapsulates information regarding the interrupt required by the Hwi module.
The standard static and dynamic forms of the "create" function are supported by the ti.sysbios.hal.Hwi module. The following C code configures interrupt 5 with the "myIsr" C function.
  #include <ti/sysbios/hal/Hwi>

  Hwi_create(5, myIsr, NULL, NULL);
The NULL, NULL arguments are used when the default instance parameters and generic error handling is satisfactory for creating a Hwi object.
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
generated on Fri, 17 Jun 2011 00:22:34 GMT


module ti.sysbios.hal.Timer
index URL

Timer Manager Proxy

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The ti.sysbios.hal.Timer module presents a standard interface for using the timer peripherals. This module is part of the Hardware Abstraction Layer (HAL) package, which hides target/device-specific characteristics of the hardware. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/Timer.xdc
#include <ti/sysbios/hal/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, Timer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, Timer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
DETAILS
The ti.sysbios.hal.Timer module presents a standard interface for using the timer peripherals. This module is part of the Hardware Abstraction Layer (HAL) package, which hides target/device-specific characteristics of the hardware.
You can use this module to create a timer (that is, to mark a timer for use) and configure it to call a tickFxn when the timer expires. Use this module only if you do not need to do any custom configuration of the timer peripheral.
The timer can be configured as a one-shot or a continuous mode timer. The period can be specified in timer counts or microseconds.
The timer interrupt always uses the Hwi dispatcher. The Timer tickFxn runs in the context of a Hwi thread. The Timer module automatically creates a Hwi instance for the timer interrupt.
The actual implementations of the Timer module functions are provided by device/family-specific Timer modules. Additional, family-specific Timer module APIs may also be provided by your Timer module implementation. Follow the link below to determine which Timer implementation is used for your target:
Delegate Mappings

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, Timer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, Timer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/hal/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.hal.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
module-wide config parameters
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:35 GMT


module ti.sysbios.hal.TimerNull
index URL

Null Timer module

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/hal/TimerNull.xdc
#include <ti/sysbios/hal/TimerNull.h>
Functions
Void | TimerNull_construct// Initialize a new instance object inside the provided structure(TimerNull_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const TimerNull_Params *params);
TimerNull_Handle | TimerNull_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const TimerNull_Params *params, Error_Block *eb);
Void | TimerNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(TimerNull_Handle *handleP);
Void | TimerNull_destruct// Finalize the instance object inside the provided structure(TimerNull_Struct *structP);
Void | TimerNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(TimerNull_Params *params);
Functions common to all ITimer modules
UInt32 | TimerNull_getCount// Read timer counter register(TimerNull_Handle handle);
Void | TimerNull_getFreq// Return timer frequency in Hz(TimerNull_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | TimerNull_getFunc// Get Timer function and arg(TimerNull_Handle handle, UArg *arg);
UInt | TimerNull_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | TimerNull_getPeriod// Get timer period in timer counts(TimerNull_Handle handle);
ITimer_Status | TimerNull_getStatus// Returns timer status (free or in use)(UInt id);
Void | TimerNull_setFunc// Overwrite Timer function and arg(TimerNull_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | TimerNull_setPeriod// Set timer period specified in timer counts(TimerNull_Handle handle, UInt32 period);
Bool | TimerNull_setPeriodMicroSecs// Set timer period specified in microseconds(TimerNull_Handle handle, UInt32 microsecs);
Void | TimerNull_start// Reload and start the timer(TimerNull_Handle handle);
Void | TimerNull_stop// Stop the timer(TimerNull_Handle handle);
Functions common to all target instances
 | TimerNull_handle// Convert this instance structure pointer into an instance handle, TimerNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, TimerNull_Handle_label// The label associated with this instance object, TimerNull_Handle_name// The name of this instance object, TimerNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, TimerNull_Object_count// The number of statically-created instance objects, TimerNull_Object_first// The handle of the first dynamically-created instance object, or NULL, TimerNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), TimerNull_Object_heap// The heap used to allocate dynamically-created instance objects, TimerNull_Object_next// The handle of the next dynamically-created instance object, or NULL, TimerNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | TimerNull_Module_getMask// Returns the diagnostics mask for this module, TimerNull_Module_hasMask// Test whether this module has a diagnostics mask, TimerNull_Module_heap// The heap from which this module allocates memory, TimerNull_Module_id// Get this module's unique id, TimerNull_Module_setMask// Set the diagnostics mask for this module, TimerNull_Module_startupDone// Test if this module has completed startup
Defines
#define | TimerNull_ANY// Const used to specify any timer (UInt)~0
Typedefs
typedef Void | (*TimerNull_FuncPtr// Timer tick function prototype)(UArg);
typedef TimerNull_Object * | TimerNull_Handle// Client reference to an instance object;
typedef struct | TimerNull_Object// Opaque internal representation of an instance object TimerNull_Object;
typedef struct | TimerNull_Params// Instance config-params structure ...
typedef enum | TimerNull_PeriodType// Timer period units ...
typedef enum | TimerNull_RunMode// Timer Run Modes ...
typedef enum | TimerNull_StartMode// Timer Start Modes ...
typedef enum | TimerNull_Status// Timer Status ...
typedef struct | TimerNull_Struct// Opaque client structure large enough to hold an instance object TimerNull_Struct;
const TimerNull_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define TimerNull_ANY (UInt)~0
enum TimerNull_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum TimerNull_PeriodType {
    TimerNull_PeriodType_MICROSECS,
    // period in microsecs
    TimerNull_PeriodType_COUNTS
    // period in counts
} TimerNull_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum TimerNull_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum TimerNull_RunMode {
    TimerNull_RunMode_CONTINUOUS,
    // periodic and continuous
    TimerNull_RunMode_ONESHOT,
    // one-shot
    TimerNull_RunMode_DYNAMIC
    // dynamically reprogrammed
} TimerNull_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum TimerNull_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum TimerNull_StartMode {
    TimerNull_StartMode_AUTO,
    // timer starts automatically
    TimerNull_StartMode_USER
    // timer will be started by user
} TimerNull_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum TimerNull_Status
index URL

Timer Status

C synopsis target-domain
typedef enum TimerNull_Status {
    TimerNull_Status_INUSE,
    // timer in use
    TimerNull_Status_FREE
    // timer is free
} TimerNull_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef TimerNull_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*TimerNull_FuncPtr)(UArg);
TimerNull_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt TimerNull_getNumTimers();
RETURNS
Number of timer peripherals.
TimerNull_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status TimerNull_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimerNull_Module_id();
// Get this module's unique id
Bool TimerNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimerNull_Module_heap();
// The heap from which this module allocates memory
Bool TimerNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimerNull_Module_getMask();
// Returns the diagnostics mask for this module
Void TimerNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct TimerNull_Object TimerNull_Object;
// Opaque internal representation of an instance object
typedef TimerNull_Object *TimerNull_Handle;
// Client reference to an instance object
typedef struct TimerNull_Struct TimerNull_Struct;
// Opaque client structure large enough to hold an instance object
TimerNull_Handle TimerNull_handle(TimerNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
TimerNull_Struct *TimerNull_struct(TimerNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct TimerNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} TimerNull_Params;
Void TimerNull_Params_init(TimerNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config TimerNull_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct TimerNull_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config TimerNull_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct TimerNull_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config TimerNull_period // instance
index URL

Period of a tick

C synopsis target-domain
struct TimerNull_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config TimerNull_periodType // instance
index URL

Period type

C synopsis target-domain
struct TimerNull_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config TimerNull_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct TimerNull_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config TimerNull_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct TimerNull_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
TimerNull_Handle TimerNull_create(Int id, ITimer_FuncPtr tickFxn, const TimerNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void TimerNull_construct(TimerNull_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const TimerNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void TimerNull_delete(TimerNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void TimerNull_destruct(TimerNull_Struct *structP);
// Finalize the instance object inside the provided structure
TimerNull_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 TimerNull_getCount(TimerNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
RETURNS
timer counter value
TimerNull_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void TimerNull_getFreq(TimerNull_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
TimerNull_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr TimerNull_getFunc(TimerNull_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
TimerNull_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 TimerNull_getPeriod(TimerNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
RETURNS
period in timer counts
TimerNull_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void TimerNull_setFunc(TimerNull_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
TimerNull_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void TimerNull_setPeriod(TimerNull_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
TimerNull_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool TimerNull_setPeriodMicroSecs(TimerNull_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
TimerNull_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void TimerNull_start(TimerNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
TimerNull_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void TimerNull_stop(TimerNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created TimerNull instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle TimerNull_Handle_upCast(TimerNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
TimerNull_Handle TimerNull_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int TimerNull_Object_count();
// The number of statically-created instance objects
TimerNull_Handle TimerNull_Object_get(TimerNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
TimerNull_Handle TimerNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
TimerNull_Handle TimerNull_Object_next(TimerNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle TimerNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *TimerNull_Handle_label(TimerNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String TimerNull_Handle_name(TimerNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/hal/TimerNull.xdc
var TimerNull = xdc.useModule('ti.sysbios.hal.TimerNull');
module-wide constants & types
    const TimerNull.ANY// Const used to specify any timer = ~0;
    values of type TimerNull.PeriodType// Timer period units
        const TimerNull.PeriodType_MICROSECS// period in microsecs;
        const TimerNull.PeriodType_COUNTS// period in counts;
    values of type TimerNull.RunMode// Timer Run Modes
        const TimerNull.RunMode_CONTINUOUS// periodic and continuous;
        const TimerNull.RunMode_ONESHOT// one-shot;
        const TimerNull.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type TimerNull.StartMode// Timer Start Modes
        const TimerNull.StartMode_AUTO// timer starts automatically;
        const TimerNull.StartMode_USER// timer will be started by user;
    values of type TimerNull.Status// Timer Status
        const TimerNull.Status_INUSE// timer in use;
        const TimerNull.Status_FREE// timer is free;
module-wide config parameters
     TimerNull.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new TimerNull.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = TimerNull.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const TimerNull.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const TimerNull.ANY = ~0;
C SYNOPSIS
TimerNull_ANY
enum TimerNull.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type TimerNull.PeriodType
    const TimerNull.PeriodType_MICROSECS;
    // period in microsecs
    const TimerNull.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
TimerNull_PeriodType
enum TimerNull.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type TimerNull.RunMode
    const TimerNull.RunMode_CONTINUOUS;
    // periodic and continuous
    const TimerNull.RunMode_ONESHOT;
    // one-shot
    const TimerNull.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
TimerNull_RunMode
enum TimerNull.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type TimerNull.StartMode
    const TimerNull.StartMode_AUTO;
    // timer starts automatically
    const TimerNull.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
TimerNull_StartMode
enum TimerNull.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type TimerNull.Status
    const TimerNull.Status_INUSE;
    // timer in use
    const TimerNull.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
TimerNull_Status
metaonly config TimerNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimerNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new TimerNull.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config TimerNull.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config TimerNull.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config TimerNull.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config TimerNull.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config TimerNull.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config TimerNull.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new TimerNull.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new TimerNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = TimerNull.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:35 GMT


package ti.sysbios.hal.ammu
index URL

Contains the AMMU module

Designed for initial use in the omap4 Ducati and Tesla cpu domains.
XDCspec declarations sourced in ti/sysbios/hal/ammu/package.xdc
package ti.sysbios.hal.ammu [2, 0, 0, 0] {
    module AMMU;
    // Attribute MMU configuration module
}
generated on Fri, 17 Jun 2011 00:22:31 GMT


module ti.sysbios.hal.ammu.AMMU
index URL

Attribute MMU configuration module

  • C synopsis
  • Individual elements
  • DETAILS
  • RESTRICTIONS
  • XDCscript usage
  • Individual elements
Responsible for initializing the Attribute MMU [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/ammu/AMMU.xdc
#include <ti/sysbios/hal/ammu/AMMU.h>
Functions
Void | AMMU_invAll// Invalidate entire L1 and L2 caches Waits for completion();
Functions common to all target modules
 | AMMU_Module_getMask// Returns the diagnostics mask for this module, AMMU_Module_hasMask// Test whether this module has a diagnostics mask, AMMU_Module_heap// The heap from which this module allocates memory, AMMU_Module_id// Get this module's unique id, AMMU_Module_setMask// Set the diagnostics mask for this module, AMMU_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | AMMU_MMU// ...
Constants
extern const Bool | AMMU_configureAmmu// By default the AMMU module will configure the AMMU at startup;
DETAILS
Responsible for initializing the Attribute MMU
RESTRICTIONS
When used within a dual M3 core (Ducati) arrangement, care must be taken when initializing this shared resource. The "Shared Resources" note provided in the ducati package discusses the management of the various hardware and software resources shared by the two M3 cores.
As the AMMU is shared between the two M3 cores, it should only be initialized and enabled once. It is intended that Core 0 will configure the AMMU at startup.
struct AMMU_MMU
index URL
C synopsis target-domain
typedef struct AMMU_MMU {
    Char *LARGE_ADDR[8];
    Char *LARGE_XLTE[8];
    UInt32 LARGE_POLICY[8];
    Char *MEDIUM_ADDR[16];
    Char *MEDIUM_XLTE[16];
    UInt32 MEDIUM_POLICY[16];
    Char *SMALL_ADDR[32];
    Char *SMALL_XLTE[32];
    UInt32 SMALL_POLICY[32];
    UInt32 SMALL_MAINT[32];
    Char *LINE_ADDR[32];
    Char *LINE_XLTE[32];
    UInt32 LINE_POLICY[32];
    Char *DEBUG_XLTE;
    UInt32 DEBUG_POLICY;
    UInt32 MAINT;
    Char *MSTART;
    Char *MEND;
    UInt32 MSTAT;
} AMMU_MMU;
config AMMU_configureAmmu // module-wide
index URL

By default the AMMU module will configure the AMMU at startup

C synopsis target-domain
extern const Bool AMMU_configureAmmu;
DETAILS
By setting this flag to false (ie for Ducati core1), the AMMU module APIs are available but the initialization step is suppressed.
AMMU_invAll() // module-wide
index URL

Invalidate entire L1 and L2 caches Waits for completion

C synopsis target-domain
Void AMMU_invAll();
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId AMMU_Module_id();
// Get this module's unique id
Bool AMMU_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle AMMU_Module_heap();
// The heap from which this module allocates memory
Bool AMMU_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 AMMU_Module_getMask();
// Returns the diagnostics mask for this module
Void AMMU_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/hal/ammu/AMMU.xdc
var AMMU = xdc.useModule('ti.sysbios.hal.ammu.AMMU');
module-wide constants & types
    values of type AMMU.AllocatePolicy//
        const AMMU.AllocatePolicy_NON_ALLOCATE;
        const AMMU.AllocatePolicy_ALLOCATE;
    values of type AMMU.CachePolicy//
        const AMMU.CachePolicy_NON_CACHEABLE;
        const AMMU.CachePolicy_CACHEABLE;
    values of type AMMU.Clean//
        const AMMU.DO_NOT_CLEAN;
        const AMMU.CLEAN;
    values of type AMMU.Enable//
        const AMMU.Enable_NO;
        const AMMU.Enable_YES;
    values of type AMMU.Invalidate//
        const AMMU.DO_NOT_INVALIDATE;
        const AMMU.INVALIDATE;
    values of type AMMU.Large//
        const AMMU.Large_2M;
        const AMMU.Large_4M;
        const AMMU.Large_8M;
        const AMMU.Large_16M;
        const AMMU.Large_32M;
        const AMMU.Large_64M;
        const AMMU.Large_128M;
        const AMMU.Large_256M;
        const AMMU.Large_512M;
    values of type AMMU.Lock//
        const AMMU.DO_NOT_LOCK;
        const AMMU.LOCK;
    values of type AMMU.Maintenance//
        const AMMU.DO_NOT_PERFORM;
        const AMMU.PERFORM;
    values of type AMMU.Medium//
        const AMMU.Medium_128K;
        const AMMU.Medium_256K;
        const AMMU.Medium_512K;
        const AMMU.Medium_1M;
    values of type AMMU.PostedPolicy//
        const AMMU.PostedPolicy_NON_POSTED;
        const AMMU.PostedPolicy_POSTED;
    values of type AMMU.Small//
        const AMMU.Small_4K;
        const AMMU.Small_8K;
        const AMMU.Small_16K;
        const AMMU.Small_32K;
    values of type AMMU.Unlock//
        const AMMU.DO_NOT_UNLOCK;
        const AMMU.UNLOCK;
    values of type AMMU.Volatile//
        const AMMU.Volatile_DO_NOT_FOLLOW;
        const AMMU.Volatile_FOLLOW;
    values of type AMMU.WritePolicy//
        const AMMU.WritePolicy_WRITE_THROUGH;
        const AMMU.WritePolicy_WRITE_BACK;
    var obj = new AMMU.DebugPage// ;
        obj.pageEnabled = AMMU.Enable ...
        obj.translationEnabled = AMMU.Enable ...
        obj.translatedAddress = Ptr ...
    var obj = new AMMU.LargePage// ;
        obj.pageEnabled = AMMU.Enable ...
        obj.logicalAddress = Ptr ...
        obj.translationEnabled = AMMU.Enable ...
        obj.translatedAddress = Ptr ...
        obj.size = AMMU.Large ...
        obj.volatileQualifier = AMMU.Volatile ...
        obj.executeOnly = AMMU.Enable ...
        obj.readOnly = AMMU.Enable ...
        obj.prefetch = AMMU.Enable ...
        obj.exclusion = AMMU.Enable ...
        obj.L1_cacheable = AMMU.CachePolicy ...
        obj.L1_posted = AMMU.PostedPolicy ...
        obj.L1_allocate = AMMU.AllocatePolicy ...
        obj.L1_writePolicy = AMMU.WritePolicy ...
        obj.L2_cacheable = AMMU.CachePolicy ...
        obj.L2_posted = AMMU.PostedPolicy ...
        obj.L2_allocate = AMMU.AllocatePolicy ...
        obj.L2_writePolicy = AMMU.WritePolicy ...
    var obj = new AMMU.LinePage// ;
        obj.pageEnabled = AMMU.Enable ...
        obj.logicalAddress = Ptr ...
        obj.translationEnabled = AMMU.Enable ...
        obj.translatedAddress = Ptr ...
    var obj = new AMMU.MMU// ;
        obj.LARGE_ADDR = Char*[8] ...
        obj.LARGE_XLTE = Char*[8] ...
        obj.LARGE_POLICY = UInt32[8] ...
        obj.MEDIUM_ADDR = Char*[16] ...
        obj.MEDIUM_XLTE = Char*[16] ...
        obj.MEDIUM_POLICY = UInt32[16] ...
        obj.SMALL_ADDR = Char*[32] ...
        obj.SMALL_XLTE = Char*[32] ...
        obj.SMALL_POLICY = UInt32[32] ...
        obj.SMALL_MAINT = UInt32[32] ...
        obj.LINE_ADDR = Char*[32] ...
        obj.LINE_XLTE = Char*[32] ...
        obj.LINE_POLICY = UInt32[32] ...
        obj.DEBUG_XLTE = Char* ...
        obj.DEBUG_POLICY = UInt32 ...
        obj.MAINT = UInt32 ...
        obj.MSTART = Char* ...
        obj.MEND = Char* ...
        obj.MSTAT = UInt32 ...
    var obj = new AMMU.MediumPage// ;
        obj.pageEnabled = AMMU.Enable ...
        obj.logicalAddress = Ptr ...
        obj.translationEnabled = AMMU.Enable ...
        obj.translatedAddress = Ptr ...
        obj.size = AMMU.Medium ...
        obj.volatileQualifier = AMMU.Volatile ...
        obj.executeOnly = AMMU.Enable ...
        obj.readOnly = AMMU.Enable ...
        obj.prefetch = AMMU.Enable ...
        obj.exclusion = AMMU.Enable ...
        obj.L1_cacheable = AMMU.CachePolicy ...
        obj.L1_posted = AMMU.PostedPolicy ...
        obj.L1_allocate = AMMU.AllocatePolicy ...
        obj.L1_writePolicy = AMMU.WritePolicy ...
        obj.L2_cacheable = AMMU.CachePolicy ...
        obj.L2_posted = AMMU.PostedPolicy ...
        obj.L2_allocate = AMMU.AllocatePolicy ...
        obj.L2_writePolicy = AMMU.WritePolicy ...
    var obj = new AMMU.SmallPage// ;
        obj.pageEnabled = AMMU.Enable ...
        obj.logicalAddress = Ptr ...
        obj.translationEnabled = AMMU.Enable ...
        obj.translatedAddress = Ptr ...
        obj.size = AMMU.Small ...
        obj.volatileQualifier = AMMU.Volatile ...
        obj.executeOnly = AMMU.Enable ...
        obj.readOnly = AMMU.Enable ...
        obj.prefetch = AMMU.Enable ...
        obj.exclusion = AMMU.Enable ...
        obj.L1_cacheable = AMMU.CachePolicy ...
        obj.L1_posted = AMMU.PostedPolicy ...
        obj.L1_allocate = AMMU.AllocatePolicy ...
        obj.L1_writePolicy = AMMU.WritePolicy ...
        obj.L2_cacheable = AMMU.CachePolicy ...
        obj.L2_posted = AMMU.PostedPolicy ...
        obj.L2_allocate = AMMU.AllocatePolicy ...
        obj.L2_writePolicy = AMMU.WritePolicy ...
    var obj = new AMMU.SmallPageMaintenance// ;
        obj.maintL2Cache = AMMU.Maintenance ...
        obj.maintL1Cache2 = AMMU.Maintenance ...
        obj.maintL1Cache1 = AMMU.Maintenance ...
        obj.cpuInterrupt = AMMU.Enable ...
        obj.hostInterrupt = AMMU.Enable ...
        obj.invalidate = AMMU.Invalidate ...
        obj.clean = AMMU.Clean ...
        obj.unlock = AMMU.Unlock ...
        obj.lock = AMMU.Lock ...
        obj.preload = AMMU.Enable ...
module-wide config parameters
     AMMU.configureAmmu// By default the AMMU module will configure the AMMU at startup = Bool true;
     AMMU.common$// Common module configuration parameters = Types.Common$ undefined;
     AMMU.debugPage// = AMMU.DebugPage undefined;
     AMMU.largePages// The number of Large Page Desciptors is target/device specific = AMMU.LargePage[] [ ];
     AMMU.linePages// The number of Line Page Desciptors is target/device specific = AMMU.LinePage[] [ ];
     AMMU.mediumPages// The number of Medium Page Desciptors is target/device specific = AMMU.MediumPage[] [ ];
     AMMU.smallPages// The number of Small Page Desciptors is target/device specific = AMMU.SmallPage[] [ ];
metaonly enum AMMU.AllocatePolicy
index URL
XDCscript usage meta-domain
values of type AMMU.AllocatePolicy
    const AMMU.AllocatePolicy_NON_ALLOCATE;
    const AMMU.AllocatePolicy_ALLOCATE;
metaonly enum AMMU.CachePolicy
index URL
XDCscript usage meta-domain
values of type AMMU.CachePolicy
    const AMMU.CachePolicy_NON_CACHEABLE;
    const AMMU.CachePolicy_CACHEABLE;
metaonly enum AMMU.Clean
index URL
XDCscript usage meta-domain
values of type AMMU.Clean
    const AMMU.DO_NOT_CLEAN;
    const AMMU.CLEAN;
metaonly enum AMMU.Enable
index URL
XDCscript usage meta-domain
values of type AMMU.Enable
    const AMMU.Enable_NO;
    const AMMU.Enable_YES;
metaonly enum AMMU.Invalidate
index URL
XDCscript usage meta-domain
values of type AMMU.Invalidate
    const AMMU.DO_NOT_INVALIDATE;
    const AMMU.INVALIDATE;
metaonly enum AMMU.Large
index URL
XDCscript usage meta-domain
values of type AMMU.Large
    const AMMU.Large_2M;
    const AMMU.Large_4M;
    const AMMU.Large_8M;
    const AMMU.Large_16M;
    const AMMU.Large_32M;
    const AMMU.Large_64M;
    const AMMU.Large_128M;
    const AMMU.Large_256M;
    const AMMU.Large_512M;
metaonly enum AMMU.Lock
index URL
XDCscript usage meta-domain
values of type AMMU.Lock
    const AMMU.DO_NOT_LOCK;
    const AMMU.LOCK;
metaonly enum AMMU.Maintenance
index URL
XDCscript usage meta-domain
values of type AMMU.Maintenance
    const AMMU.DO_NOT_PERFORM;
    const AMMU.PERFORM;
metaonly enum AMMU.Medium
index URL
XDCscript usage meta-domain
values of type AMMU.Medium
    const AMMU.Medium_128K;
    const AMMU.Medium_256K;
    const AMMU.Medium_512K;
    const AMMU.Medium_1M;
metaonly enum AMMU.PostedPolicy
index URL
XDCscript usage meta-domain
values of type AMMU.PostedPolicy
    const AMMU.PostedPolicy_NON_POSTED;
    const AMMU.PostedPolicy_POSTED;
metaonly enum AMMU.Small
index URL
XDCscript usage meta-domain
values of type AMMU.Small
    const AMMU.Small_4K;
    const AMMU.Small_8K;
    const AMMU.Small_16K;
    const AMMU.Small_32K;
metaonly enum AMMU.Unlock
index URL
XDCscript usage meta-domain
values of type AMMU.Unlock
    const AMMU.DO_NOT_UNLOCK;
    const AMMU.UNLOCK;
metaonly enum AMMU.Volatile
index URL
XDCscript usage meta-domain
values of type AMMU.Volatile
    const AMMU.Volatile_DO_NOT_FOLLOW;
    const AMMU.Volatile_FOLLOW;
metaonly enum AMMU.WritePolicy
index URL
XDCscript usage meta-domain
values of type AMMU.WritePolicy
    const AMMU.WritePolicy_WRITE_THROUGH;
    const AMMU.WritePolicy_WRITE_BACK;
metaonly struct AMMU.DebugPage
index URL
XDCscript usage meta-domain
var obj = new AMMU.DebugPage;
    obj.pageEnabled = AMMU.Enable ...
    obj.translationEnabled = AMMU.Enable ...
    obj.translatedAddress = Ptr ...
metaonly struct AMMU.LargePage
index URL
XDCscript usage meta-domain
var obj = new AMMU.LargePage;
    obj.pageEnabled = AMMU.Enable ...
    obj.logicalAddress = Ptr ...
    obj.translationEnabled = AMMU.Enable ...
    obj.translatedAddress = Ptr ...
    obj.size = AMMU.Large ...
    obj.volatileQualifier = AMMU.Volatile ...
    obj.executeOnly = AMMU.Enable ...
    obj.readOnly = AMMU.Enable ...
    obj.prefetch = AMMU.Enable ...
    obj.exclusion = AMMU.Enable ...
    obj.L1_cacheable = AMMU.CachePolicy ...
    obj.L1_posted = AMMU.PostedPolicy ...
    obj.L1_allocate = AMMU.AllocatePolicy ...
    obj.L1_writePolicy = AMMU.WritePolicy ...
    obj.L2_cacheable = AMMU.CachePolicy ...
    obj.L2_posted = AMMU.PostedPolicy ...
    obj.L2_allocate = AMMU.AllocatePolicy ...
    obj.L2_writePolicy = AMMU.WritePolicy ...
metaonly struct AMMU.LinePage
index URL
XDCscript usage meta-domain
var obj = new AMMU.LinePage;
    obj.pageEnabled = AMMU.Enable ...
    obj.logicalAddress = Ptr ...
    obj.translationEnabled = AMMU.Enable ...
    obj.translatedAddress = Ptr ...
struct AMMU.MMU
index URL
XDCscript usage meta-domain
var obj = new AMMU.MMU;
    obj.LARGE_ADDR = Char*[8] ...
    obj.LARGE_XLTE = Char*[8] ...
    obj.LARGE_POLICY = UInt32[8] ...
    obj.MEDIUM_ADDR = Char*[16] ...
    obj.MEDIUM_XLTE = Char*[16] ...
    obj.MEDIUM_POLICY = UInt32[16] ...
    obj.SMALL_ADDR = Char*[32] ...
    obj.SMALL_XLTE = Char*[32] ...
    obj.SMALL_POLICY = UInt32[32] ...
    obj.SMALL_MAINT = UInt32[32] ...
    obj.LINE_ADDR = Char*[32] ...
    obj.LINE_XLTE = Char*[32] ...
    obj.LINE_POLICY = UInt32[32] ...
    obj.DEBUG_XLTE = Char* ...
    obj.DEBUG_POLICY = UInt32 ...
    obj.MAINT = UInt32 ...
    obj.MSTART = Char* ...
    obj.MEND = Char* ...
    obj.MSTAT = UInt32 ...
C SYNOPSIS
AMMU_MMU
metaonly struct AMMU.MediumPage
index URL
XDCscript usage meta-domain
var obj = new AMMU.MediumPage;
    obj.pageEnabled = AMMU.Enable ...
    obj.logicalAddress = Ptr ...
    obj.translationEnabled = AMMU.Enable ...
    obj.translatedAddress = Ptr ...
    obj.size = AMMU.Medium ...
    obj.volatileQualifier = AMMU.Volatile ...
    obj.executeOnly = AMMU.Enable ...
    obj.readOnly = AMMU.Enable ...
    obj.prefetch = AMMU.Enable ...
    obj.exclusion = AMMU.Enable ...
    obj.L1_cacheable = AMMU.CachePolicy ...
    obj.L1_posted = AMMU.PostedPolicy ...
    obj.L1_allocate = AMMU.AllocatePolicy ...
    obj.L1_writePolicy = AMMU.WritePolicy ...
    obj.L2_cacheable = AMMU.CachePolicy ...
    obj.L2_posted = AMMU.PostedPolicy ...
    obj.L2_allocate = AMMU.AllocatePolicy ...
    obj.L2_writePolicy = AMMU.WritePolicy ...
metaonly struct AMMU.SmallPage
index URL
XDCscript usage meta-domain
var obj = new AMMU.SmallPage;
    obj.pageEnabled = AMMU.Enable ...
    obj.logicalAddress = Ptr ...
    obj.translationEnabled = AMMU.Enable ...
    obj.translatedAddress = Ptr ...
    obj.size = AMMU.Small ...
    obj.volatileQualifier = AMMU.Volatile ...
    obj.executeOnly = AMMU.Enable ...
    obj.readOnly = AMMU.Enable ...
    obj.prefetch = AMMU.Enable ...
    obj.exclusion = AMMU.Enable ...
    obj.L1_cacheable = AMMU.CachePolicy ...
    obj.L1_posted = AMMU.PostedPolicy ...
    obj.L1_allocate = AMMU.AllocatePolicy ...
    obj.L1_writePolicy = AMMU.WritePolicy ...
    obj.L2_cacheable = AMMU.CachePolicy ...
    obj.L2_posted = AMMU.PostedPolicy ...
    obj.L2_allocate = AMMU.AllocatePolicy ...
    obj.L2_writePolicy = AMMU.WritePolicy ...
metaonly struct AMMU.SmallPageMaintenance
index URL
XDCscript usage meta-domain
var obj = new AMMU.SmallPageMaintenance;
    obj.maintL2Cache = AMMU.Maintenance ...
    obj.maintL1Cache2 = AMMU.Maintenance ...
    obj.maintL1Cache1 = AMMU.Maintenance ...
    obj.cpuInterrupt = AMMU.Enable ...
    obj.hostInterrupt = AMMU.Enable ...
    obj.invalidate = AMMU.Invalidate ...
    obj.clean = AMMU.Clean ...
    obj.unlock = AMMU.Unlock ...
    obj.lock = AMMU.Lock ...
    obj.preload = AMMU.Enable ...
config AMMU.configureAmmu // module-wide
index URL

By default the AMMU module will configure the AMMU at startup

XDCscript usage meta-domain
AMMU.configureAmmu = Bool true;
DETAILS
By setting this flag to false (ie for Ducati core1), the AMMU module APIs are available but the initialization step is suppressed.
C SYNOPSIS
AMMU_configureAmmu
metaonly config AMMU.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
AMMU.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config AMMU.debugPage // module-wide
index URL
XDCscript usage meta-domain
AMMU.debugPage = AMMU.DebugPage undefined;
metaonly config AMMU.largePages // module-wide
index URL

The number of Large Page Desciptors is target/device specific

XDCscript usage meta-domain
AMMU.largePages = AMMU.LargePage[] [ ];
metaonly config AMMU.linePages // module-wide
index URL

The number of Line Page Desciptors is target/device specific

XDCscript usage meta-domain
AMMU.linePages = AMMU.LinePage[] [ ];
metaonly config AMMU.mediumPages // module-wide
index URL

The number of Medium Page Desciptors is target/device specific

XDCscript usage meta-domain
AMMU.mediumPages = AMMU.MediumPage[] [ ];
metaonly config AMMU.smallPages // module-wide
index URL

The number of Small Page Desciptors is target/device specific

XDCscript usage meta-domain
AMMU.smallPages = AMMU.SmallPage[] [ ];
generated on Fri, 17 Jun 2011 00:22:31 GMT


package ti.sysbios.hal.unicache
index URL

Contains the unicache Cache module

Designed for initial use in the omap4 Ducati and Tesla cpu domains.
XDCspec declarations sourced in ti/sysbios/hal/unicache/package.xdc
package ti.sysbios.hal.unicache [2, 0, 0, 0] {
    module Cache;
    // The unicache Cache module used by the omap4 Tesla and Ducati cores
}
generated on Fri, 17 Jun 2011 00:22:32 GMT


module ti.sysbios.hal.unicache.Cache
index URL

The unicache Cache module used by the omap4 Tesla and Ducati cores

  • C synopsis
  • Individual elements
  • DETAILS
  • RESTRICTIONS
  • XDCscript usage
  • Individual elements
The Tesla and Ducati UniCaches do not support separate program and data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D operations can be precisely supported. The APIs in this module ignore the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P is functionally equivalent to Cache_Type_L1D and Cache_Type_L1). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/hal/unicache/Cache.xdc
#include <ti/sysbios/hal/unicache/Cache.h>
Functions
Void | Cache_invAll// Invalidate all caches();
Void | Cache_lock// Locks a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_preload// Loads a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_preloadLock// Loads and locks a memory block into the cache(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_read// Read a block of memory from the cache. Only whole numbers of 32 bit words are transferred. byteCnt is divided by 4 to convert to number of words(Ptr blockPtr, SizeT byteCnt, Bits16 type, Ptr destBuf);
Void | Cache_unlock// Unlocks a cached memory block(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Functions common to all ICache modules
Void | Cache_disable// Disables the 'type' cache(s)(Bits16 type);
Void | Cache_enable// Enables all cache(s)(Bits16 type);
Void | Cache_inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wait// Wait for a previous cache operation to complete();
Void | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbAll// Write back all caches();
Void | Cache_wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
Void | Cache_wbInvAll// Write back invalidate all caches();
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | Cache_CACHE// Runtime representation of the Cache registers ...
typedef struct | Cache_OCPConfig// OCP Interface Configuration Register Settings ...
typedef struct | Cache_SecurityConfig// CONFIG Configuration Register Settings ...
typedef enum | Cache_Type// Lists of bitmask cache types ...
Constants
extern const Bool | Cache_configureCache// Configure cache at startup?;
extern const Bool | Cache_enableCache// Enable cache at startup?;
extern const Error_Id | Cache_E_exception// Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register;
extern const SizeT | Cache_maxLineModeBufSize// Maximum buffer size to use discrete cache line operations with;
DETAILS
The Tesla and Ducati UniCaches do not support separate program and data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D operations can be precisely supported. The APIs in this module ignore the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P is functionally equivalent to Cache_Type_L1D and Cache_Type_L1).
RESTRICTIONS
When used within a dual M3 core (Ducati arrangement), care must be taken when initializing this shared resource. The "Shared Resources" note provided in the ducati package discusses the management of the various hardware and software resources shared by the two M3 cores.
As the unicache is shared between the two M3 cores, it should only be initialized and enabled once. It is intended that Core 0 will configure the unicache at startup and then either enable it at that time or later on by manually invoking Cache_enable().
The unicache Cache module is a Gated module. In a dual M3 core (Ducati) environment, the unicache Cache module employs a GateDualCore gate to arbitrate the usage of the shared unicache registers. In a non shared environment such as the C64T core in an OMAP4 device, a GateHwi gate is used to avoid multi thread conflicts.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
disable | Y | Y | Y | Y | Y
enable | Y | Y | Y | Y | Y
inv | Y | Y | Y | Y | Y
wb | Y | Y | Y | Y | Y
wbInv | Y | Y | Y | Y | Y
wait | Y | Y | Y | Y | Y
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).
enum Cache_Type
index URL

Lists of bitmask cache types

C synopsis target-domain
typedef enum Cache_Type {
    Cache_Type_L1P,
    // Level 1 Program cache
    Cache_Type_L1D,
    // Level 1 Data cache
    Cache_Type_L1,
    // Level 1 caches
    Cache_Type_L2P,
    // Level 2 Program cache
    Cache_Type_L2D,
    // Level 2 Data cache
    Cache_Type_L2,
    // Level 2 caches
    Cache_Type_ALLP,
    // All Program caches
    Cache_Type_ALLD,
    // All Data caches
    Cache_Type_ALL
    // All caches
} Cache_Type;
struct Cache_CACHE
index URL

Runtime representation of the Cache registers

C synopsis target-domain
typedef struct Cache_CACHE {
    UInt32 L1_INFO;
    UInt32 L1_CONFIG;
    UInt32 L1_INT;
    UInt32 L1_OCP;
    UInt32 L1_MAINT;
    Ptr L1_MTSTART;
    Ptr L1_MTEND;
    Ptr L1_CTADDR;
    UInt32 L1_CTDATA;
    UInt32 Reserved[0x77];
    UInt32 L2_INFO;
    UInt32 L2_CONFIG;
    UInt32 L2_INT;
    UInt32 L2_OCP;
    UInt32 L2_MAINT;
    Ptr L2_MTSTART;
    Ptr L2_MTEND;
    Ptr L2_CTADDR;
    UInt32 L2_CTDATA;
} Cache_CACHE;
struct Cache_OCPConfig
index URL

OCP Interface Configuration Register Settings

C synopsis target-domain
typedef struct Cache_OCPConfig {
    UInt8 wrap;
    UInt8 wrbuffer;
    UInt8 prefetch;
    UInt8 cleanbuf;
} Cache_OCPConfig;
struct Cache_SecurityConfig
index URL

CONFIG Configuration Register Settings

C synopsis target-domain
typedef struct Cache_SecurityConfig {
    UInt8 secure;
    UInt8 nbypass;
    UInt8 secint;
    UInt8 secport;
    UInt8 secmain;
} Cache_SecurityConfig;
config Cache_E_exception // module-wide
index URL

Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register

C synopsis target-domain
extern const Error_Id Cache_E_exception;
config Cache_configureCache // module-wide
index URL

Configure cache at startup?

C synopsis target-domain
extern const Bool Cache_configureCache;
DETAILS
It is possible to configure the Cache at startup and not enable it. However, it is not possible to enable the Cache at startup without configuring it.
Enabling the Cache will automatically enable configuring the Cache.
config Cache_enableCache // module-wide
index URL

Enable cache at startup?

C synopsis target-domain
extern const Bool Cache_enableCache;
DETAILS
Enabling the Cache at startup will force configuring the Cache at startup.
config Cache_maxLineModeBufSize // module-wide
index URL

Maximum buffer size to use discrete cache line operations with

C synopsis target-domain
extern const SizeT Cache_maxLineModeBufSize;
DETAILS
For buffers below a certain size, cache maintenance operations are more efficient if performed on single cache lines at a time rather than on an entire region.
For buffer sizes equal to or less than this setting, the inv, wb, and wbInv APIs will use a series of individual cache line operations. For buffer sizes large than this setting, a a single block mode operation will be performed.
For M3 cores, the default setting is 1024 bytes. For 64T cores, the default setting is 4096 bytes.
Cache_disable() // module-wide
index URL

Disables the 'type' cache(s)

C synopsis target-domain
Void Cache_disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_enable() // module-wide
index URL

Enables all cache(s)

C synopsis target-domain
Void Cache_enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
Cache_inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

C synopsis target-domain
Void Cache_inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_invAll() // module-wide
index URL

Invalidate all caches

C synopsis target-domain
Void Cache_invAll();
DETAILS
Perform a global invalidate. All cache lines are invalidated in L1 and L2 caches. Waits for completion.
Cache_lock() // module-wide
index URL

Locks a memory block into the cache

C synopsis target-domain
Void Cache_lock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be locked
byteCnt — number of bytes to be locked
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_preload() // module-wide
index URL

Loads a memory block into the cache

C synopsis target-domain
Void Cache_preload(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be loaded
byteCnt — number of bytes to be loaded
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_preloadLock() // module-wide
index URL

Loads and locks a memory block into the cache

C synopsis target-domain
Void Cache_preloadLock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be loaded
byteCnt — number of bytes to be loaded
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_read() // module-wide
index URL

Read a block of memory from the cache. Only whole numbers of 32 bit words are transferred. byteCnt is divided by 4 to convert to number of words

C synopsis target-domain
Void Cache_read(Ptr blockPtr, SizeT byteCnt, Bits16 type, Ptr destBuf);
ARGUMENTS
blockPtr — start address of range to be loaded
byteCnt — number of bytes to be loaded
type — bit mask of Cache type
destBuf — address of destination buffer
Cache_unlock() // module-wide
index URL

Unlocks a cached memory block

C synopsis target-domain
Void Cache_unlock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be locked
byteCnt — number of bytes to be locked
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Void Cache_wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Void Cache_wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
Cache_wbAll() // module-wide
index URL

Write back all caches

C synopsis target-domain
Void Cache_wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
Perform a global write back. All cache lines are left valid in L1 and L2 caches and the data in L1 cache is written back to L2 or external. All cache lines are left valid in L2 cache and the data in L2 cache is written back to external. Waits for completion.
Cache_wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

C synopsis target-domain
Void Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
Cache_wbInvAll() // module-wide
index URL

Write back invalidate all caches

C synopsis target-domain
Void Cache_wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
Perform a global write back. Then perform a global invalidate. All cache lines are invalidated in L1 and L2 caches. Waits for completion.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/hal/unicache/Cache.xdc
var Cache = xdc.useModule('ti.sysbios.hal.unicache.Cache');
module-wide constants & types
    values of type Cache.Type// Lists of bitmask cache types
        const Cache.Type_L1P// Level 1 Program cache;
        const Cache.Type_L1D// Level 1 Data cache;
        const Cache.Type_L1// Level 1 caches;
        const Cache.Type_L2P// Level 2 Program cache;
        const Cache.Type_L2D// Level 2 Data cache;
        const Cache.Type_L2// Level 2 caches;
        const Cache.Type_ALLP// All Program caches;
        const Cache.Type_ALLD// All Data caches;
        const Cache.Type_ALL// All caches;
    var obj = new Cache.CACHE// Runtime representation of the Cache registers;
        obj.L1_INFO = UInt32 ...
        obj.L1_CONFIG = UInt32 ...
        obj.L1_INT = UInt32 ...
        obj.L1_OCP = UInt32 ...
        obj.L1_MAINT = UInt32 ...
        obj.L1_MTSTART = Ptr ...
        obj.L1_MTEND = Ptr ...
        obj.L1_CTADDR = Ptr ...
        obj.L1_CTDATA = UInt32 ...
        obj.Reserved = UInt32[0x77] ...
        obj.L2_INFO = UInt32 ...
        obj.L2_CONFIG = UInt32 ...
        obj.L2_INT = UInt32 ...
        obj.L2_OCP = UInt32 ...
        obj.L2_MAINT = UInt32 ...
        obj.L2_MTSTART = Ptr ...
        obj.L2_MTEND = Ptr ...
        obj.L2_CTADDR = Ptr ...
        obj.L2_CTDATA = UInt32 ...
    var obj = new Cache.OCPConfig// OCP Interface Configuration Register Settings;
        obj.wrap = UInt8 ...
        obj.wrbuffer = UInt8 ...
        obj.prefetch = UInt8 ...
        obj.cleanbuf = UInt8 ...
    var obj = new Cache.SecurityConfig// CONFIG Configuration Register Settings;
        obj.secure = UInt8 ...
        obj.nbypass = UInt8 ...
        obj.secint = UInt8 ...
        obj.secport = UInt8 ...
        obj.secmain = UInt8 ...
module-wide config parameters
     Cache.E_exception// Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register = Error.Desc {
        msg: "E_exception: L%d reason: 0x%x"
    };
     Cache.configureCache// Configure cache at startup? = Bool false;
     Cache.enableCache// Enable cache at startup? = Bool false;
     Cache.maxLineModeBufSize// Maximum buffer size to use discrete cache line operations with = SizeT undefined;
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
     Cache.configL1// L1_CONFIG register settings = Cache.SecurityConfig {
        secure: 0,
        nbypass: 0,
        secint: 1,
        secport: 1,
        secmain: 1
    };
     Cache.configL2// L2_CONFIG register settings = Cache.SecurityConfig {
        secure: 0,
        nbypass: 0,
        secint: 1,
        secport: 1,
        secmain: 1
    };
     Cache.l1InterruptHandler// L1 Interrupt Handler. Default is set to an internal L1 interrupt handler = Void(*)(UArg) undefined;
     Cache.l1InterruptNumber// L1 Interrupt number. Default is device unique but can be set in the user config file = UInt undefined;
     Cache.l1InterruptPriority// L1 Interrupt priority. Default is device unique but can be set in the user config file = UInt undefined;
     Cache.l2InterruptHandler// L2 Interrupt Handler. Default is set to an internal L2 interrupt handler = Void(*)(UArg) undefined;
     Cache.l2InterruptNumber// L2 Interrupt number. Default is device unique but can be set in the user config file = UInt undefined;
     Cache.l2InterruptPriority// L2 Interrupt priority. Default is device unique but can be set in the user config file = UInt undefined;
     Cache.ocpL1// L1_OCP register settings = Cache.OCPConfig {
        wrap: 0,
        wrbuffer: 0,
        prefetch: 0
    };
     Cache.ocpL2// L2_OCP register settings = Cache.OCPConfig {
        wrap: 0,
        wrbuffer: 0,
        prefetch: 0,
        cleanbuf: 0
    };
enum Cache.Type
index URL

Lists of bitmask cache types

XDCscript usage meta-domain
values of type Cache.Type
    const Cache.Type_L1P;
    // Level 1 Program cache
    const Cache.Type_L1D;
    // Level 1 Data cache
    const Cache.Type_L1;
    // Level 1 caches
    const Cache.Type_L2P;
    // Level 2 Program cache
    const Cache.Type_L2D;
    // Level 2 Data cache
    const Cache.Type_L2;
    // Level 2 caches
    const Cache.Type_ALLP;
    // All Program caches
    const Cache.Type_ALLD;
    // All Data caches
    const Cache.Type_ALL;
    // All caches
C SYNOPSIS
Cache_Type
struct Cache.CACHE
index URL

Runtime representation of the Cache registers

XDCscript usage meta-domain
var obj = new Cache.CACHE;
    obj.L1_INFO = UInt32 ...
    obj.L1_CONFIG = UInt32 ...
    obj.L1_INT = UInt32 ...
    obj.L1_OCP = UInt32 ...
    obj.L1_MAINT = UInt32 ...
    obj.L1_MTSTART = Ptr ...
    obj.L1_MTEND = Ptr ...
    obj.L1_CTADDR = Ptr ...
    obj.L1_CTDATA = UInt32 ...
    obj.Reserved = UInt32[0x77] ...
    obj.L2_INFO = UInt32 ...
    obj.L2_CONFIG = UInt32 ...
    obj.L2_INT = UInt32 ...
    obj.L2_OCP = UInt32 ...
    obj.L2_MAINT = UInt32 ...
    obj.L2_MTSTART = Ptr ...
    obj.L2_MTEND = Ptr ...
    obj.L2_CTADDR = Ptr ...
    obj.L2_CTDATA = UInt32 ...
C SYNOPSIS
Cache_CACHE
struct Cache.OCPConfig
index URL

OCP Interface Configuration Register Settings

XDCscript usage meta-domain
var obj = new Cache.OCPConfig;
    obj.wrap = UInt8 ...
    obj.wrbuffer = UInt8 ...
    obj.prefetch = UInt8 ...
    obj.cleanbuf = UInt8 ...
C SYNOPSIS
Cache_OCPConfig
struct Cache.SecurityConfig
index URL

CONFIG Configuration Register Settings

XDCscript usage meta-domain
var obj = new Cache.SecurityConfig;
    obj.secure = UInt8 ...
    obj.nbypass = UInt8 ...
    obj.secint = UInt8 ...
    obj.secport = UInt8 ...
    obj.secmain = UInt8 ...
C SYNOPSIS
Cache_SecurityConfig
config Cache.E_exception // module-wide
index URL

Error raised when a Cache interrupt occurs Reason bits are contents of Cache Interrupt Register

XDCscript usage meta-domain
Cache.E_exception = Error.Desc {
    msg: "E_exception: L%d reason: 0x%x"
};
C SYNOPSIS
Cache_E_exception
config Cache.configureCache // module-wide
index URL

Configure cache at startup?

XDCscript usage meta-domain
Cache.configureCache = Bool false;
DETAILS
It is possible to configure the Cache at startup and not enable it. However, it is not possible to enable the Cache at startup without configuring it.
Enabling the Cache will automatically enable configuring the Cache.
C SYNOPSIS
Cache_configureCache
config Cache.enableCache // module-wide
index URL

Enable cache at startup?

XDCscript usage meta-domain
Cache.enableCache = Bool false;
DETAILS
Enabling the Cache at startup will force configuring the Cache at startup.
C SYNOPSIS
Cache_enableCache
config Cache.maxLineModeBufSize // module-wide
index URL

Maximum buffer size to use discrete cache line operations with

XDCscript usage meta-domain
Cache.maxLineModeBufSize = SizeT undefined;
DETAILS
For buffers below a certain size, cache maintenance operations are more efficient if performed on single cache lines at a time rather than on an entire region.
For buffer sizes equal to or less than this setting, the inv, wb, and wbInv APIs will use a series of individual cache line operations. For buffer sizes large than this setting, a a single block mode operation will be performed.
For M3 cores, the default setting is 1024 bytes. For 64T cores, the default setting is 4096 bytes.
C SYNOPSIS
Cache_maxLineModeBufSize
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Cache.configL1 // module-wide
index URL

L1_CONFIG register settings

XDCscript usage meta-domain
Cache.configL1 = Cache.SecurityConfig {
    secure: 0,
    nbypass: 0,
    secint: 1,
    secport: 1,
    secmain: 1
};
metaonly config Cache.configL2 // module-wide
index URL

L2_CONFIG register settings

XDCscript usage meta-domain
Cache.configL2 = Cache.SecurityConfig {
    secure: 0,
    nbypass: 0,
    secint: 1,
    secport: 1,
    secmain: 1
};
metaonly config Cache.l1InterruptHandler // module-wide
index URL

L1 Interrupt Handler. Default is set to an internal L1 interrupt handler

XDCscript usage meta-domain
Cache.l1InterruptHandler = Void(*)(UArg) undefined;
metaonly config Cache.l1InterruptNumber // module-wide
index URL

L1 Interrupt number. Default is device unique but can be set in the user config file

XDCscript usage meta-domain
Cache.l1InterruptNumber = UInt undefined;
metaonly config Cache.l1InterruptPriority // module-wide
index URL

L1 Interrupt priority. Default is device unique but can be set in the user config file

XDCscript usage meta-domain
Cache.l1InterruptPriority = UInt undefined;
metaonly config Cache.l2InterruptHandler // module-wide
index URL

L2 Interrupt Handler. Default is set to an internal L2 interrupt handler

XDCscript usage meta-domain
Cache.l2InterruptHandler = Void(*)(UArg) undefined;
metaonly config Cache.l2InterruptNumber // module-wide
index URL

L2 Interrupt number. Default is device unique but can be set in the user config file

XDCscript usage meta-domain
Cache.l2InterruptNumber = UInt undefined;
metaonly config Cache.l2InterruptPriority // module-wide
index URL

L2 Interrupt priority. Default is device unique but can be set in the user config file

XDCscript usage meta-domain
Cache.l2InterruptPriority = UInt undefined;
metaonly config Cache.ocpL1 // module-wide
index URL

L1_OCP register settings

XDCscript usage meta-domain
Cache.ocpL1 = Cache.OCPConfig {
    wrap: 0,
    wrbuffer: 0,
    prefetch: 0
};
metaonly config Cache.ocpL2 // module-wide
index URL

L2_OCP register settings

XDCscript usage meta-domain
Cache.ocpL2 = Cache.OCPConfig {
    wrap: 0,
    wrbuffer: 0,
    prefetch: 0,
    cleanbuf: 0
};
generated on Fri, 17 Jun 2011 00:22:32 GMT


package ti.sysbios.heaps
index URL

Contains modules that inherit from IHeap

A "Heap" is a module that implements the IHeap interface. Heaps are dynamic memory managers: they manage a specific piece of memory and support allocating and freeing pieces ("blocks") of that memory. [ more ... ]
XDCspec declarations sourced in ti/sysbios/heaps/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.heaps [2, 0, 0, 0] {
    module HeapBuf;
    // Fixed size buffer heap manager
    module HeapMem;
    // Variable size buffer heap manager
    module HeapMultiBuf;
    // Multiple fixed size buffer heap manager
    module HeapNull;
    // Empty heap
}
DETAILS
A "Heap" is a module that implements the IHeap interface. Heaps are dynamic memory managers: they manage a specific piece of memory and support allocating and freeing pieces ("blocks") of that memory.
The xdc.runtime.Memory module is the common interface for all memory operations. Actual memory management is performed by a Heap instance, such as an instance of HeapMem or HeapBuf. For example, Memory_alloc() is used at runtime to dynamically allocate memory. All of the Memory APIs take a Heap instance as one of their parameters. Internally, the Memory module calls into the heap?s interface functions.
The xdc.runtime.Memory module is documented in the XDCtools online help. Implementations of Heaps provided by SYS/BIOS are discussed here.
Memory allocation sizes are measured in "Minimum Addressable Units" (MAUs) of memory. An MAU is the smallest unit of data storage that can be read or written by the CPU. For the C5000, this is a 16-bit word. For the C28x, this is an 16-bit word. For the all other currently supported target families?including C6000, ARM, and MSP430?this is an 8-bit byte.
generated on Fri, 17 Jun 2011 00:23:43 GMT


module ti.sysbios.heaps.HeapBuf
index URL

Fixed size buffer heap manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The HeapBuf manager provides functions to allocate and free storage from a heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single fixed-size buffer, split into equally sized allocable blocks. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/heaps/HeapBuf.xdc
#include <ti/sysbios/heaps/HeapBuf.h>
Functions
Void | HeapBuf_construct// Initialize a new instance object inside the provided structure(HeapBuf_Struct *structP, const HeapBuf_Params *params, Error_Block *eb);
HeapBuf_Handle | HeapBuf_create// Allocate and initialize a new instance object and return its handle(const HeapBuf_Params *params, Error_Block *eb);
Void | HeapBuf_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapBuf_Handle *handleP);
Void | HeapBuf_destruct// Finalize the instance object inside the provided structure(HeapBuf_Struct *structP);
Void | HeapBuf_getExtendedStats// Retrieves the extended statistics for a HeapBuf instance(HeapBuf_Handle handle, HeapBuf_ExtendedStats *stats);
Void | HeapBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapBuf_Params *params);
Functions common to all IHeap modules
Ptr | HeapBuf_alloc// Allocates a block of memory from the heap(HeapBuf_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapBuf_free// Free a block of memory back to the heap(HeapBuf_Handle handle, Ptr block, SizeT size);
Void | HeapBuf_getStats// Retrieve the statistics from the heap(HeapBuf_Handle handle, Memory_Stats *stats);
Bool | HeapBuf_isBlocking// Returns whether the heap may block during an alloc() or free()(HeapBuf_Handle handle);
Functions common to all target instances
 | HeapBuf_handle// Convert this instance structure pointer into an instance handle, HeapBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapBuf_Handle_label// The label associated with this instance object, HeapBuf_Handle_name// The name of this instance object, HeapBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapBuf_Object_count// The number of statically-created instance objects, HeapBuf_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapBuf_Object_heap// The heap used to allocate dynamically-created instance objects, HeapBuf_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapBuf_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapBuf_Module_getMask// Returns the diagnostics mask for this module, HeapBuf_Module_hasMask// Test whether this module has a diagnostics mask, HeapBuf_Module_heap// The heap from which this module allocates memory, HeapBuf_Module_id// Get this module's unique id, HeapBuf_Module_setMask// Set the diagnostics mask for this module, HeapBuf_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | HeapBuf_ExtendedStats// Stat structure for the HeapBuf_getExtendedStats function ...
typedef HeapBuf_Object * | HeapBuf_Handle// Client reference to an instance object;
typedef struct | HeapBuf_Object// Opaque internal representation of an instance object HeapBuf_Object;
typedef struct | HeapBuf_Params// Instance config-params structure ...
typedef struct | HeapBuf_Struct// Opaque client structure large enough to hold an instance object HeapBuf_Struct;
Constants
extern const Assert_Id | HeapBuf_A_bufAlign// Misalligned buffer;
extern const Assert_Id | HeapBuf_A_invalidAlign// Invalid alignment;
extern const Assert_Id | HeapBuf_A_invalidBufSize// Invalid buffer size;
extern const Assert_Id | HeapBuf_A_invalidFree// Assert raised when an invalid free occurs;
extern const Assert_Id | HeapBuf_A_noBlocksToFree// No allocated blocks;
extern const Assert_Id | HeapBuf_A_nullBuf// Null buf parameter;
extern const Assert_Id | HeapBuf_A_zeroBlocks// Assert raised when the numBlocks parameter is 0;
extern const Assert_Id | HeapBuf_A_zeroBlockSize// Assert raised when the blockSize parameter is 0;
extern const Assert_Id | HeapBuf_A_zeroBufSize// Assert raised when the bufSize parameter is 0;
extern const Error_Id | HeapBuf_E_size// Raised when requested size exceeds blockSize;
extern const Bool | HeapBuf_trackMaxAllocs// Track maximum number of allocations;
DETAILS
The HeapBuf manager provides functions to allocate and free storage from a heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single fixed-size buffer, split into equally sized allocable blocks.
The HeapBuf manager is intended as a very fast and deterministic memory manager which can only allocate blocks of a single size. It is ideal for managing a heap that is only used for allocating a single type of object, or for objects that have very similar sizes.
Allocation from and freeing to a HeapBuf instance is non-blocking and deterministic: a call to alloc or free will always take the same amount of time.
Constraints:
  • Align parameter must be set to 0 for default, or be a power of 2 that is greater than or equal to the value returned by xdc.runtime.Memory.getMaxDefaultTypeAlign.
  • The buffer passed to dynamically create a HeapBuf must be aligned according to the alignment parameter, and must be large enough to account for the actual block size after it has been rounded up to a multiple of the alignment.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
alloc | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
free | Y | Y | Y | Y | N
getStats | Y | Y | Y | Y | N
getExtendedStats | Y | Y | Y | Y | N
isBlocking | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. HeapBuf_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. HeapBuf_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Assuming GateMutex is used as HeapMem's Gate.
  • + : Cannot use HeapMem object while it is being restored.
    • struct HeapBuf_ExtendedStats
    index URL

    Stat structure for the HeapBuf_getExtendedStats function

    C synopsis target-domain
    typedef struct HeapBuf_ExtendedStats {
        UInt maxAllocatedBlocks;
        UInt numAllocatedBlocks;
    } HeapBuf_ExtendedStats;
    FIELDS
    maxAllocatedBlocks — The maximum number of blocks allocated from this heap at any single point in time, during the lifetime of this HeapBuf instance.
    numAllocatedBlocks — The total number of blocks currently allocated in this HeapBuf instance.
    config HeapBuf_A_bufAlign // module-wide
    index URL

    Misalligned buffer

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_bufAlign;
    DETAILS
    This Assert is raised when the buf parameter has not been aligned on the requested alignment.
    config HeapBuf_A_invalidAlign // module-wide
    index URL

    Invalid alignment

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_invalidAlign;
    DETAILS
    This Assert is raised when the align parameter is not the default value of zero, or a power of 2 that is greater than or equal to the value defined by xdc.runtime.Memory.getMaxDefaultTypeAlign.
    config HeapBuf_A_invalidBufSize // module-wide
    index URL

    Invalid buffer size

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_invalidBufSize;
    DETAILS
    This Assert is raised when the bufSize parameter is too small to handle requested blocks.
    config HeapBuf_A_invalidFree // module-wide
    index URL

    Assert raised when an invalid free occurs

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_invalidFree;
    DETAILS
    This assert can be caused when passing a NULL pointer to the free.
    config HeapBuf_A_noBlocksToFree // module-wide
    index URL

    No allocated blocks

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_noBlocksToFree;
    DETAILS
    This Assert is raised when free is called and there are no blocks allocated.
    config HeapBuf_A_nullBuf // module-wide
    index URL

    Null buf parameter

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_nullBuf;
    DETAILS
    This Assert is raised when the buf parameter has been omitted (null) for a dynamic create.
    config HeapBuf_A_zeroBlockSize // module-wide
    index URL

    Assert raised when the blockSize parameter is 0

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_zeroBlockSize;
    config HeapBuf_A_zeroBlocks // module-wide
    index URL

    Assert raised when the numBlocks parameter is 0

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_zeroBlocks;
    config HeapBuf_A_zeroBufSize // module-wide
    index URL

    Assert raised when the bufSize parameter is 0

    C synopsis target-domain
    extern const Assert_Id HeapBuf_A_zeroBufSize;
    config HeapBuf_E_size // module-wide
    index URL

    Raised when requested size exceeds blockSize

    C synopsis target-domain
    extern const Error_Id HeapBuf_E_size;
    config HeapBuf_trackMaxAllocs // module-wide
    index URL

    Track maximum number of allocations

    C synopsis target-domain
    extern const Bool HeapBuf_trackMaxAllocs;
    DETAILS
    This will enable/disable the tracking of the maximum number of allocations for a HeapBuf instance. This maximum refers to the "all time" maximum number of allocations for the history of a HeapBuf instance, not the current number of allocations.
    Module-Wide Built-Ins
    index URL

    C synopsis target-domain
    Types_ModuleId HeapBuf_Module_id();
    // Get this module's unique id
    Bool HeapBuf_Module_startupDone();
    // Test if this module has completed startup
    IHeap_Handle HeapBuf_Module_heap();
    // The heap from which this module allocates memory
    Bool HeapBuf_Module_hasMask();
    // Test whether this module has a diagnostics mask
    Bits16 HeapBuf_Module_getMask();
    // Returns the diagnostics mask for this module
    Void HeapBuf_Module_setMask(Bits16 mask);
    // Set the diagnostics mask for this module
    Instance Object Types
    index URL

    C synopsis target-domain
    typedef struct HeapBuf_Object HeapBuf_Object;
    // Opaque internal representation of an instance object
    typedef HeapBuf_Object *HeapBuf_Handle;
    // Client reference to an instance object
    typedef struct HeapBuf_Struct HeapBuf_Struct;
    // Opaque client structure large enough to hold an instance object
    HeapBuf_Handle HeapBuf_handle(HeapBuf_Struct *structP);
    // Convert this instance structure pointer into an instance handle
    HeapBuf_Struct *HeapBuf_struct(HeapBuf_Handle handle);
    // Convert this instance handle into an instance structure pointer
    Instance Config Parameters
    index URL

    C synopsis target-domain
    typedef struct HeapBuf_Params {
    // Instance config-params structure
         IInstance_Params *instance;
        // Common per-instance configs
        SizeT align;
        // Alignment (in MAUs) of each block
        SizeT blockSize;
        // Size (in MAUs) of each block
        Ptr buf;
        // User supplied buffer; for dynamic creates only
         Memory_Size bufSize;
        // Size (in MAUs) of the entire buffer; for dynamic creates only
        UInt numBlocks;
        // Number of fixed-size blocks
    } HeapBuf_Params;
    Void HeapBuf_Params_init(HeapBuf_Params *params);
    // Initialize this config-params structure with supplier-specified defaults before instance creation
    config HeapBuf_align // instance
    index URL

    Alignment (in MAUs) of each block

    C synopsis target-domain
    struct HeapBuf_Params {
         ...
        SizeT align;
    DETAILS
    The alignment must be a power of 2 that is greater than or equal to the target dependent value defined by xdc.runtime.Memory.getMaxDefaultTypeAlign. If the default value of 0 is specified, this value will be changed to be the minimum structure alignment requirement, as defined by xdc.runtime.Memory.getMaxDefaultTypeAlign.
    For static creates, the HeapBuf module will allocate space for the buffer and will align it on this requested alignment.
    For dynamic creates, this parameter is used solely for error checking. The buffer provided to a dynamically created HeapBuf must be aligned manually, and an assert will be raised if the buffer is not properly aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to satisfy the alignment.
    config HeapBuf_blockSize // instance
    index URL

    Size (in MAUs) of each block

    C synopsis target-domain
    struct HeapBuf_Params {
         ...
        SizeT blockSize;
    DETAILS
    HeapBuf will round the blockSize up to the nearest multiple of the alignment, so the actual blockSize may be larger. When creating a HeapBuf dynamically, this needs to be taken into account to determine the proper buffer size to pass in.
    Required parameter.
    The default size of the blocks is 0 MAUs.
    config HeapBuf_buf // instance
    index URL

    User supplied buffer; for dynamic creates only

    C synopsis target-domain
    struct HeapBuf_Params {
         ...
        Ptr buf;
    DETAILS
    The caller must supply the memory buffer for a dynamically created HeapBuf to manage. The provided buffer must be aligned according to the HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter is 128, then the buffer's start address must be a multiple of 128.
    For static creates, the buffer is allocated automatically based on the blockSize and numBlocks parameters.
    This parameter is required for dynamic creates and ignored for static creates.
    config HeapBuf_bufSize // instance
    index URL

    Size (in MAUs) of the entire buffer; for dynamic creates only

    C synopsis target-domain
    struct HeapBuf_Params {
         ...
         Memory_Size bufSize;
    DETAILS
    When dynamically creating a HeapBuf, this should be the actual size of the memory buffer provided for HeapBuf to manage.
    This parameter is used solely for error checking; an Error is raised if the bufSize is too small for the requested blockSize and numBlocks. Because of minimum alignment considerations, it's easy to provide too small of a buffer to manage, and difficult to detect if it happened.
    This parameter is required for dynamic creates and ignored for static creates.
    The default buffer size is 0 MAUs.
    config HeapBuf_numBlocks // instance
    index URL

    Number of fixed-size blocks

    C synopsis target-domain
    struct HeapBuf_Params {
         ...
        UInt numBlocks;
    DETAILS
    Required parameter.
    The default number of blocks is 0.
    Instance Creation
    index URL

    C synopsis target-domain
    HeapBuf_Handle HeapBuf_create(const HeapBuf_Params *params, Error_Block *eb);
    // Allocate and initialize a new instance object and return its handle
    Void HeapBuf_construct(HeapBuf_Struct *structP, const HeapBuf_Params *params, Error_Block *eb);
    // Initialize a new instance object inside the provided structure
    ARGUMENTS
    params — per-instance config params, or NULL to select default values (target-domain only)
    eb — active error-handling block, or NULL to select default policy (target-domain only)
    DETAILS
    See specific IHeap implementation for parameters used.
    Instance Deletion
    index URL

    C synopsis target-domain
    Void HeapBuf_delete(HeapBuf_Handle *handleP);
    // Finalize and free this previously allocated instance object, setting the referenced handle to NULL
    Void HeapBuf_destruct(HeapBuf_Struct *structP);
    // Finalize the instance object inside the provided structure
    HeapBuf_alloc() // instance
    index URL

    Allocates a block of memory from the heap

    C synopsis target-domain
    Ptr HeapBuf_alloc(HeapBuf_Handle handle, SizeT size, SizeT align, Error_Block *eb);
    ARGUMENTS
    handle — handle of a previously-created HeapBuf instance object
    size — size (in MADUs) of the block
    align — alignment (in MADUs) of the block
    eb — pointer to error block
    DETAILS
    This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
    HeapBuf_alloc will only fail if there are no available blocks or if the requested block size is larger than the HeapBuf's blockSize. All other requests, regardless of size, will succeed.
    HEAPBUF
    All alignment is handled in the create, therefore the align argument in alloc is ignored.
    RETURNS
    Returns the address of the allocated memory.
    HeapBuf_free() // instance
    index URL

    Free a block of memory back to the heap

    C synopsis target-domain
    Void HeapBuf_free(HeapBuf_Handle handle, Ptr block, SizeT size);
    ARGUMENTS
    handle — handle of a previously-created HeapBuf instance object
    block — non-NULL address of allocated block to free
    size — size (in MADUs) of the block of memory to free
    DETAILS
    This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
    HeapBuf_getExtendedStats() // instance
    index URL

    Retrieves the extended statistics for a HeapBuf instance

    C synopsis target-domain
    Void HeapBuf_getExtendedStats(HeapBuf_Handle handle, HeapBuf_ExtendedStats *stats);
    ARGUMENTS
    handle — handle of a previously-created HeapBuf instance object
    stats — Location for the returned extended statistics.
    DETAILS
    This function retrieves the extended statistics for a HeapBuf instance. It does not retrieve the standard xdc.runtime.Memory.Stats information.
    HeapBuf_getStats() // instance
    index URL

    Retrieve the statistics from the heap

    C synopsis target-domain
    Void HeapBuf_getStats(HeapBuf_Handle handle, Memory_Stats *stats);
    ARGUMENTS
    handle — handle of a previously-created HeapBuf instance object
    stats — non-NULL pointer to an output buffer
    DETAILS
    The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
    This function is called by the xdc.runtime.Memory.getStats() function.
    HeapBuf_isBlocking() // instance
    index URL

    Returns whether the heap may block during an alloc() or free()

    C synopsis target-domain
    Bool HeapBuf_isBlocking(HeapBuf_Handle handle);
    ARGUMENTS
    handle — handle of a previously-created HeapBuf instance object
    HEAPBUF
    This function always returns FALSE since the alloc/free never block on a resource.
    RETURNS
    If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
    Instance Convertors
    index URL

    C synopsis target-domain
    IHeap_Handle HeapBuf_Handle_upCast(HeapBuf_Handle handle);
    // unconditionally move one level up the inheritance hierarchy
    HeapBuf_Handle HeapBuf_Handle_downCast(IHeap_Handle handle);
    // conditionally move one level down the inheritance hierarchy; NULL upon failure
    Instance Built-Ins
    index URL

    C synopsis target-domain
    Int HeapBuf_Object_count();
    // The number of statically-created instance objects
    HeapBuf_Handle HeapBuf_Object_get(HeapBuf_Object *array, Int i);
    // The handle of the i-th statically-created instance object (array == NULL)
    HeapBuf_Handle HeapBuf_Object_first();
    // The handle of the first dynamically-created instance object, or NULL
    HeapBuf_Handle HeapBuf_Object_next(HeapBuf_Handle handle);
    // The handle of the next dynamically-created instance object, or NULL
    IHeap_Handle HeapBuf_Object_heap();
    // The heap used to allocate dynamically-created instance objects
    Types_Label *HeapBuf_Handle_label(HeapBuf_Handle handle, Types_Label *buf);
    // The label associated with this instance object
    String HeapBuf_Handle_name(HeapBuf_Handle handle);
    // The name of this instance object
    XDCscript usage meta-domain sourced in ti/sysbios/heaps/HeapBuf.xdc
    var HeapBuf = xdc.useModule('ti.sysbios.heaps.HeapBuf');
    module-wide constants & types
        var obj = new HeapBuf.ExtendedStats// Stat structure for the HeapBuf_getExtendedStats function;
            obj.maxAllocatedBlocks = UInt ...
            obj.numAllocatedBlocks = UInt ...
    module-wide config parameters
         HeapBuf.A_bufAlign// Misalligned buffer = Assert.Desc {
            msg: "buf not properly aligned"
        };
         HeapBuf.A_invalidAlign// Invalid alignment = Assert.Desc {
            msg: "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"
        };
         HeapBuf.A_invalidBufSize// Invalid buffer size = Assert.Desc {
            msg: "HeapBuf_create's bufSize parameter is invalid (too small)"
        };
         HeapBuf.A_invalidFree// Assert raised when an invalid free occurs = Assert.Desc {
            msg: "A_invalidFree: Invalid free"
        };
         HeapBuf.A_noBlocksToFree// No allocated blocks = Assert.Desc {
            msg: "Cannot call HeapBuf_free when no blocks have been allocated"
        };
         HeapBuf.A_nullBuf// Null buf parameter = Assert.Desc {
            msg: "buf parameter cannot be null"
        };
         HeapBuf.A_zeroBlockSize// Assert raised when the blockSize parameter is 0 = Assert.Desc {
            msg: "blockSize cannot be zero"
        };
         HeapBuf.A_zeroBlocks// Assert raised when the numBlocks parameter is 0 = Assert.Desc {
            msg: "numBlocks cannot be zero"
        };
         HeapBuf.A_zeroBufSize// Assert raised when the bufSize parameter is 0 = Assert.Desc {
            msg: "bufSize cannot be zero"
        };
         HeapBuf.E_size// Raised when requested size exceeds blockSize = Error.Desc {
            msg: "requested size is too big: handle=0x%x, size=%u"
        };
         HeapBuf.trackMaxAllocs// Track maximum number of allocations = Bool false;
         HeapBuf.common$// Common module configuration parameters = Types.Common$ undefined;
    per-instance config parameters
        var params = new HeapBuf.Params// Instance config-params object;
            params.align// Alignment (in MAUs) of each block = SizeT 0;
            params.blockSize// Size (in MAUs) of each block = SizeT 0;
            params.buf// User supplied buffer; for dynamic creates only = Ptr 0;
            params.bufSize// Size (in MAUs) of the entire buffer; for dynamic creates only = UArg 0;
            params.numBlocks// Number of fixed-size blocks = UInt 0;
            params.sectionName// Section name for the buffer managed by the instance = String null;
    per-instance creation
        var inst = HeapBuf.create// Create an instance-object(params);
    struct HeapBuf.ExtendedStats
    index URL

    Stat structure for the HeapBuf_getExtendedStats function

    XDCscript usage meta-domain
    var obj = new HeapBuf.ExtendedStats;
        obj.maxAllocatedBlocks = UInt ...
        obj.numAllocatedBlocks = UInt ...
    FIELDS
    maxAllocatedBlocks — The maximum number of blocks allocated from this heap at any single point in time, during the lifetime of this HeapBuf instance.
    numAllocatedBlocks — The total number of blocks currently allocated in this HeapBuf instance.
    C SYNOPSIS
    HeapBuf_ExtendedStats
    config HeapBuf.A_bufAlign // module-wide
    index URL

    Misalligned buffer

    XDCscript usage meta-domain
    HeapBuf.A_bufAlign = Assert.Desc {
        msg: "buf not properly aligned"
    };
    DETAILS
    This Assert is raised when the buf parameter has not been aligned on the requested alignment.
    C SYNOPSIS
    HeapBuf_A_bufAlign
    config HeapBuf.A_invalidAlign // module-wide
    index URL

    Invalid alignment

    XDCscript usage meta-domain
    HeapBuf.A_invalidAlign = Assert.Desc {
        msg: "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"
    };
    DETAILS
    This Assert is raised when the align parameter is not the default value of zero, or a power of 2 that is greater than or equal to the value defined by xdc.runtime.Memory.getMaxDefaultTypeAlign.
    C SYNOPSIS
    HeapBuf_A_invalidAlign
    config HeapBuf.A_invalidBufSize // module-wide
    index URL

    Invalid buffer size

    XDCscript usage meta-domain
    HeapBuf.A_invalidBufSize = Assert.Desc {
        msg: "HeapBuf_create's bufSize parameter is invalid (too small)"
    };
    DETAILS
    This Assert is raised when the bufSize parameter is too small to handle requested blocks.
    C SYNOPSIS
    HeapBuf_A_invalidBufSize
    config HeapBuf.A_invalidFree // module-wide
    index URL

    Assert raised when an invalid free occurs

    XDCscript usage meta-domain
    HeapBuf.A_invalidFree = Assert.Desc {
        msg: "A_invalidFree: Invalid free"
    };
    DETAILS
    This assert can be caused when passing a NULL pointer to the free.
    C SYNOPSIS
    HeapBuf_A_invalidFree
    config HeapBuf.A_noBlocksToFree // module-wide
    index URL

    No allocated blocks

    XDCscript usage meta-domain
    HeapBuf.A_noBlocksToFree = Assert.Desc {
        msg: "Cannot call HeapBuf_free when no blocks have been allocated"
    };
    DETAILS
    This Assert is raised when free is called and there are no blocks allocated.
    C SYNOPSIS
    HeapBuf_A_noBlocksToFree
    config HeapBuf.A_nullBuf // module-wide
    index URL

    Null buf parameter

    XDCscript usage meta-domain
    HeapBuf.A_nullBuf = Assert.Desc {
        msg: "buf parameter cannot be null"
    };
    DETAILS
    This Assert is raised when the buf parameter has been omitted (null) for a dynamic create.
    C SYNOPSIS
    HeapBuf_A_nullBuf
    config HeapBuf.A_zeroBlockSize // module-wide
    index URL

    Assert raised when the blockSize parameter is 0

    XDCscript usage meta-domain
    HeapBuf.A_zeroBlockSize = Assert.Desc {
        msg: "blockSize cannot be zero"
    };
    C SYNOPSIS
    HeapBuf_A_zeroBlockSize
    config HeapBuf.A_zeroBlocks // module-wide
    index URL

    Assert raised when the numBlocks parameter is 0

    XDCscript usage meta-domain
    HeapBuf.A_zeroBlocks = Assert.Desc {
        msg: "numBlocks cannot be zero"
    };
    C SYNOPSIS
    HeapBuf_A_zeroBlocks
    config HeapBuf.A_zeroBufSize // module-wide
    index URL

    Assert raised when the bufSize parameter is 0

    XDCscript usage meta-domain
    HeapBuf.A_zeroBufSize = Assert.Desc {
        msg: "bufSize cannot be zero"
    };
    C SYNOPSIS
    HeapBuf_A_zeroBufSize
    config HeapBuf.E_size // module-wide
    index URL

    Raised when requested size exceeds blockSize

    XDCscript usage meta-domain
    HeapBuf.E_size = Error.Desc {
        msg: "requested size is too big: handle=0x%x, size=%u"
    };
    C SYNOPSIS
    HeapBuf_E_size
    config HeapBuf.trackMaxAllocs // module-wide
    index URL

    Track maximum number of allocations

    XDCscript usage meta-domain
    HeapBuf.trackMaxAllocs = Bool false;
    DETAILS
    This will enable/disable the tracking of the maximum number of allocations for a HeapBuf instance. This maximum refers to the "all time" maximum number of allocations for the history of a HeapBuf instance, not the current number of allocations.
    C SYNOPSIS
    HeapBuf_trackMaxAllocs
    metaonly config HeapBuf.common$ // module-wide
    index URL

    Common module configuration parameters

    XDCscript usage meta-domain
    HeapBuf.common$ = Types.Common$ undefined;
    DETAILS
    All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
    Instance Config Parameters
    index URL

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    // Instance config-params object
        params.align = SizeT 0;
        // Alignment (in MAUs) of each block
        params.blockSize = SizeT 0;
        // Size (in MAUs) of each block
        params.buf = Ptr 0;
        // User supplied buffer; for dynamic creates only
        params.bufSize = UArg 0;
        // Size (in MAUs) of the entire buffer; for dynamic creates only
        params.numBlocks = UInt 0;
        // Number of fixed-size blocks
        params.sectionName = String null;
        // Section name for the buffer managed by the instance
    config HeapBuf.align // instance
    index URL

    Alignment (in MAUs) of each block

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.align = SizeT 0;
    DETAILS
    The alignment must be a power of 2 that is greater than or equal to the target dependent value defined by xdc.runtime.Memory.getMaxDefaultTypeAlign. If the default value of 0 is specified, this value will be changed to be the minimum structure alignment requirement, as defined by xdc.runtime.Memory.getMaxDefaultTypeAlign.
    For static creates, the HeapBuf module will allocate space for the buffer and will align it on this requested alignment.
    For dynamic creates, this parameter is used solely for error checking. The buffer provided to a dynamically created HeapBuf must be aligned manually, and an assert will be raised if the buffer is not properly aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to satisfy the alignment.
    C SYNOPSIS
    null
    config HeapBuf.blockSize // instance
    index URL

    Size (in MAUs) of each block

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.blockSize = SizeT 0;
    DETAILS
    HeapBuf will round the blockSize up to the nearest multiple of the alignment, so the actual blockSize may be larger. When creating a HeapBuf dynamically, this needs to be taken into account to determine the proper buffer size to pass in.
    Required parameter.
    The default size of the blocks is 0 MAUs.
    C SYNOPSIS
    null
    config HeapBuf.buf // instance
    index URL

    User supplied buffer; for dynamic creates only

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.buf = Ptr 0;
    DETAILS
    The caller must supply the memory buffer for a dynamically created HeapBuf to manage. The provided buffer must be aligned according to the HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter is 128, then the buffer's start address must be a multiple of 128.
    For static creates, the buffer is allocated automatically based on the blockSize and numBlocks parameters.
    This parameter is required for dynamic creates and ignored for static creates.
    C SYNOPSIS
    null
    config HeapBuf.bufSize // instance
    index URL

    Size (in MAUs) of the entire buffer; for dynamic creates only

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.bufSize = UArg 0;
    DETAILS
    When dynamically creating a HeapBuf, this should be the actual size of the memory buffer provided for HeapBuf to manage.
    This parameter is used solely for error checking; an Error is raised if the bufSize is too small for the requested blockSize and numBlocks. Because of minimum alignment considerations, it's easy to provide too small of a buffer to manage, and difficult to detect if it happened.
    This parameter is required for dynamic creates and ignored for static creates.
    The default buffer size is 0 MAUs.
    C SYNOPSIS
    null
    config HeapBuf.numBlocks // instance
    index URL

    Number of fixed-size blocks

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.numBlocks = UInt 0;
    DETAILS
    Required parameter.
    The default number of blocks is 0.
    C SYNOPSIS
    null
    metaonly config HeapBuf.sectionName // instance
    index URL

    Section name for the buffer managed by the instance

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    ...
    params.sectionName = String null;
    DETAILS
    The buffer allocated for a statically created HeapBuf instance will be placed in this section.
    The default section is the 'dataSection' in the platform.
    Instance Creation
    index URL

    XDCscript usage meta-domain
    var params = new HeapBuf.Params;
    // Allocate instance config-params
    params.config = ...
    // Assign individual configs
    var inst = HeapBuf.create(params);
    // Create an instance-object
    ARGUMENTS
    params — per-instance config params, or NULL to select default values (target-domain only)
    eb — active error-handling block, or NULL to select default policy (target-domain only)
    DETAILS
    See specific IHeap implementation for parameters used.
    generated on Fri, 17 Jun 2011 00:23:43 GMT


module ti.sysbios.heaps.HeapMem
index URL

Variable size buffer heap manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/heaps/HeapMem.xdc
#include <ti/sysbios/heaps/HeapMem.h>
Functions
Void | HeapMem_construct// Initialize a new instance object inside the provided structure(HeapMem_Struct *structP, const HeapMem_Params *params);
HeapMem_Handle | HeapMem_create// Allocate and initialize a new instance object and return its handle(const HeapMem_Params *params, Error_Block *eb);
Void | HeapMem_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapMem_Handle *handleP);
Void | HeapMem_destruct// Finalize the instance object inside the provided structure(HeapMem_Struct *structP);
Void | HeapMem_getExtendedStats// Retrieves the extended statistics for a HeapMem instance(HeapMem_Handle handle, HeapMem_ExtendedStats *stats);
Void | HeapMem_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapMem_Params *params);
Void | HeapMem_restore// Restores an instance to its original created state(HeapMem_Handle handle);
Functions common to all IHeap modules
Ptr | HeapMem_alloc// Allocates a block of memory from the heap(HeapMem_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapMem_free// Free a block of memory back to the heap(HeapMem_Handle handle, Ptr block, SizeT size);
Void | HeapMem_getStats// Retrieve the statistics from the heap(HeapMem_Handle handle, Memory_Stats *stats);
Bool | HeapMem_isBlocking// Returns whether the heap may block during an alloc() or free()(HeapMem_Handle handle);
Functions common to all target instances
 | HeapMem_handle// Convert this instance structure pointer into an instance handle, HeapMem_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapMem_Handle_label// The label associated with this instance object, HeapMem_Handle_name// The name of this instance object, HeapMem_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapMem_Object_count// The number of statically-created instance objects, HeapMem_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapMem_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapMem_Object_heap// The heap used to allocate dynamically-created instance objects, HeapMem_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapMem_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapMem_Module_getMask// Returns the diagnostics mask for this module, HeapMem_Module_hasMask// Test whether this module has a diagnostics mask, HeapMem_Module_heap// The heap from which this module allocates memory, HeapMem_Module_id// Get this module's unique id, HeapMem_Module_setMask// Set the diagnostics mask for this module, HeapMem_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct | HeapMem_ExtendedStats// Stat structure for the HeapMem_getExtendedStats function ...
typedef HeapMem_Object * | HeapMem_Handle// Client reference to an instance object;
typedef struct | HeapMem_Object// Opaque internal representation of an instance object HeapMem_Object;
typedef struct | HeapMem_Params// Instance config-params structure ...
typedef struct | HeapMem_Struct// Opaque client structure large enough to hold an instance object HeapMem_Struct;
Constants
extern const Assert_Id | HeapMem_A_align// Assert raised when the requested alignment is not a power of 2;
extern const Assert_Id | HeapMem_A_heapSize// Assert raised when the requested heap size is too small;
extern const Assert_Id | HeapMem_A_invalidFree// Assert raised when the free detects that an invalid addr or size;
extern const Assert_Id | HeapMem_A_zeroBlock// Assert raised when a block of size 0 is requested;
extern const Error_Id | HeapMem_E_memory// Raised when requested size exceeds largest free block;
DETAILS
HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap.

HeapMem Gate

A HeapMem instance will use the HeapMem module Gate to protect any accesses to its list of free memory blocks. The HeapMem instance will enter and leave the module Gate when allocating blocks, freeing blocks, and retrieving statistics about the HeapMem. By default, the Gate is of type GateMutex. A different Gate can be specified using the common$.gate parameter. For example, to use a GateTask to protect HeapMem: HeapMem.common$.gate = GateTask.create(); To save on overhead, HeapMem does not create additional Gate instances on a per-instance basis; there is only one Gate instance shared across all of the HeapMem instances. Therefore, the HeapMem.common$.gateParams parameter (used for configuring per-instance Gates) is ignored. The type of Gate used should be chosen based on the type of threads (Hwi, Swi, Task, etc.) using the heap. It should also consider the non-deterministic nature of the HeapMem. A call to alloc or free will traverse a list of free blocks, so a GateHwi, for example, is likely an inappropriate Gate for HeapMem.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
alloc | N** | N** | Y** | Y | N
construct | Y | Y | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | Y | Y | Y | Y | N
free | N** | N** | Y** | Y | N
getExtendedStats | Y | Y | Y | Y | N
getStats | N** | N** | Y** | Y | N
isBlocking | Y | Y | Y | Y | N
restore | Y+ | Y+ | Y+ | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. HeapMem_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. HeapMem_Module_startupDone() returns FALSE).
  • * : Assuming blocking Heap is used for creation.
  • **: Assuming GateMutex is used as HeapMem's Gate.
  • + : Cannot use HeapMem object while it is being restored.
struct HeapMem_ExtendedStats
index URL

Stat structure for the HeapMem_getExtendedStats function

C synopsis target-domain
typedef struct HeapMem_ExtendedStats {
    Ptr buf;
    SizeT size;
} HeapMem_ExtendedStats;
FIELDS
buf — Base address of the internal buffer. This may be different from the original buf parameter due to alignment requirements.
size — Size of the internal buffer. This may be different from the original size parameter due to alignment requirements.
config HeapMem_A_align // module-wide
index URL

Assert raised when the requested alignment is not a power of 2

C synopsis target-domain
extern const Assert_Id HeapMem_A_align;
config HeapMem_A_heapSize // module-wide
index URL

Assert raised when the requested heap size is too small

C synopsis target-domain
extern const Assert_Id HeapMem_A_heapSize;
config HeapMem_A_invalidFree // module-wide
index URL

Assert raised when the free detects that an invalid addr or size

C synopsis target-domain
extern const Assert_Id HeapMem_A_invalidFree;
DETAILS
This could arise when multiple frees are done on the same buffer or if corruption occurred.
This also could occur when an alloc is made with size N and the free for this buffer specifies size M where M > N. Note: not every case is detectable.
This assert can also be caused when passing an invalid addr to free or if the size is causing the end of the buffer to be out of the expected range.
config HeapMem_A_zeroBlock // module-wide
index URL

Assert raised when a block of size 0 is requested

C synopsis target-domain
extern const Assert_Id HeapMem_A_zeroBlock;
DETAILS
This error can also be raised if the requested size wraps the contents of a SizeT type when it is adjusted for a minimum alignment. For example, when SizeT is 16-bits and a size request is made for 0xFFFB.
config HeapMem_E_memory // module-wide
index URL

Raised when requested size exceeds largest free block

C synopsis target-domain
extern const Error_Id HeapMem_E_memory;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId HeapMem_Module_id();
// Get this module's unique id
Bool HeapMem_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle HeapMem_Module_heap();
// The heap from which this module allocates memory
Bool HeapMem_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMem_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMem_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct HeapMem_Object HeapMem_Object;
// Opaque internal representation of an instance object
typedef HeapMem_Object *HeapMem_Handle;
// Client reference to an instance object
typedef struct HeapMem_Struct HeapMem_Struct;
// Opaque client structure large enough to hold an instance object
HeapMem_Handle HeapMem_handle(HeapMem_Struct *structP);
// Convert this instance structure pointer into an instance handle
HeapMem_Struct *HeapMem_struct(HeapMem_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct HeapMem_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Ptr buf;
    // Buffer being managed by this heap instance
     Memory_Size size;
    // Size of buffer being managed by this heap instance
} HeapMem_Params;
Void HeapMem_Params_init(HeapMem_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMem_buf // instance
index URL

Buffer being managed by this heap instance

C synopsis target-domain
struct HeapMem_Params {
     ...
    Ptr buf;
DETAILS
This parameter is ignored in the static HeapMem.create() call. It is a required parameter in the dynamic HeapMem_create() call.
HeapMem requires that the buffer be aligned on a target-specific minimum alignment, and will adjust the buffer's start address and size as necessary to satisfy this requirement.
config HeapMem_size // instance
index URL

Size of buffer being managed by this heap instance

C synopsis target-domain
struct HeapMem_Params {
     ...
     Memory_Size size;
DETAILS
The usable size may be smaller depending on alignment requirements.
Instance Creation
index URL

C synopsis target-domain
HeapMem_Handle HeapMem_create(const HeapMem_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void HeapMem_construct(HeapMem_Struct *structP, const HeapMem_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
Instance Deletion
index URL

C synopsis target-domain
Void HeapMem_delete(HeapMem_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void HeapMem_destruct(HeapMem_Struct *structP);
// Finalize the instance object inside the provided structure
HeapMem_alloc() // instance
index URL

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapMem_alloc(HeapMem_Handle handle, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
HeapMem_alloc() will lock the heap using the HeapMem Gate while it traverses the list of free blocks to find a large enough block for the request.
Guidelines for using large heaps and multiple alloc() calls.
  • If possible, allocate larger blocks first. Previous allocations of small memory blocks can reduce the size of the blocks available for larger memory allocations.
  • Realize that alloc() can fail even if the heap contains a sufficient absolute amount of unallocated space. This is because the largest free memory block may be smaller than total amount of unallocated memory.
HEAPMEM
The actual block returned may be larger than requested to satisfy alignment requirements
RETURNS
Returns the address of the allocated memory.
HeapMem_free() // instance
index URL

Free a block of memory back to the heap

C synopsis target-domain
Void HeapMem_free(HeapMem_Handle handle, Ptr block, SizeT size);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
free() will lock the heap using the HeapMem Gate, if one is specified using 'HeapMem.common$.gate'.
HEAPMEM
free() places the memory block specified by addr and size back into the free pool of the heap specified. The newly freed block is combined with any adjacent free blocks. The space is then available for further allocation by alloc().
HeapMem_getExtendedStats() // instance
index URL

Retrieves the extended statistics for a HeapMem instance

C synopsis target-domain
Void HeapMem_getExtendedStats(HeapMem_Handle handle, HeapMem_ExtendedStats *stats);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
stats — Location for the returned extended statistics.
DETAILS
This function retrieves the extended statistics for a HeapMem instance. It does not retrieve the standard xdc.runtime.Memory.Stats information.
HeapMem_getStats() // instance
index URL

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapMem_getStats(HeapMem_Handle handle, Memory_Stats *stats);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
The returned totalSize reflects the usable size of the buffer, not necessarily the size specified during create.
HEAPMEM
getStats() will lock the heap using the HeapMem Gate while it retrieves the HeapMem's statistics.
HeapMem_isBlocking() // instance
index URL

Returns whether the heap may block during an alloc() or free()

C synopsis target-domain
Bool HeapMem_isBlocking(HeapMem_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
HEAPMEM
This function queries the gate (as specified by 'HeapMem.common$.gate') to determine if the alloc/free can be blocking.
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
HeapMem_restore() // instance
index URL

Restores an instance to its original created state

C synopsis target-domain
Void HeapMem_restore(HeapMem_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
DETAILS
This function restores a static or dynamically created instance to its original created state. Any memory previously allocated from the heap is no longer valid after this API is called. This function does not check whether there is allocated memory or not.
Instance Convertors
index URL

C synopsis target-domain
IHeap_Handle HeapMem_Handle_upCast(HeapMem_Handle handle);
// unconditionally move one level up the inheritance hierarchy
HeapMem_Handle HeapMem_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int HeapMem_Object_count();
// The number of statically-created instance objects
HeapMem_Handle HeapMem_Object_get(HeapMem_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
HeapMem_Handle HeapMem_Object_first();
// The handle of the first dynamically-created instance object, or NULL
HeapMem_Handle HeapMem_Object_next(HeapMem_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle HeapMem_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *HeapMem_Handle_label(HeapMem_Handle handle, Types_Label *buf);
// The label associated with this instance object
String HeapMem_Handle_name(HeapMem_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/heaps/HeapMem.xdc
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
module-wide constants & types
    var obj = new HeapMem.ExtendedStats// Stat structure for the HeapMem_getExtendedStats function;
        obj.buf = Ptr ...
        obj.size = SizeT ...
module-wide config parameters
     HeapMem.A_align// Assert raised when the requested alignment is not a power of 2 = Assert.Desc {
        msg: "A_align: Requested align is not a power of 2"
    };
     HeapMem.A_heapSize// Assert raised when the requested heap size is too small = Assert.Desc {
        msg: "A_heapSize: Requested heap size is too small"
    };
     HeapMem.A_invalidFree// Assert raised when the free detects that an invalid addr or size = Assert.Desc {
        msg: "A_invalidFree: Invalid free"
    };
     HeapMem.A_zeroBlock// Assert raised when a block of size 0 is requested = Assert.Desc {
        msg: "A_zeroBlock: Cannot allocate size 0"
    };
     HeapMem.E_memory// Raised when requested size exceeds largest free block = Error.Desc {
        msg: "out of memory: handle=0x%x, size=%u"
    };
     HeapMem.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new HeapMem.Params// Instance config-params object;
        params.align// Alignment of the buffer being managed by this heap instance = SizeT 0;
        params.buf// Buffer being managed by this heap instance = Ptr 0;
        params.sectionName// Section name for the buffer managed by the instance = String null;
        params.size// Size of buffer being managed by this heap instance = UArg 0;
per-instance creation
    var inst = HeapMem.create// Create an instance-object(params);
struct HeapMem.ExtendedStats
index URL

Stat structure for the HeapMem_getExtendedStats function

XDCscript usage meta-domain
var obj = new HeapMem.ExtendedStats;
    obj.buf = Ptr ...
    obj.size = SizeT ...
FIELDS
buf — Base address of the internal buffer. This may be different from the original buf parameter due to alignment requirements.
size — Size of the internal buffer. This may be different from the original size parameter due to alignment requirements.
C SYNOPSIS
HeapMem_ExtendedStats
config HeapMem.A_align // module-wide
index URL

Assert raised when the requested alignment is not a power of 2

XDCscript usage meta-domain
HeapMem.A_align = Assert.Desc {
    msg: "A_align: Requested align is not a power of 2"
};
C SYNOPSIS
HeapMem_A_align
config HeapMem.A_heapSize // module-wide
index URL

Assert raised when the requested heap size is too small

XDCscript usage meta-domain
HeapMem.A_heapSize = Assert.Desc {
    msg: "A_heapSize: Requested heap size is too small"
};
C SYNOPSIS
HeapMem_A_heapSize
config HeapMem.A_invalidFree // module-wide
index URL

Assert raised when the free detects that an invalid addr or size

XDCscript usage meta-domain
HeapMem.A_invalidFree = Assert.Desc {
    msg: "A_invalidFree: Invalid free"
};
DETAILS
This could arise when multiple frees are done on the same buffer or if corruption occurred.
This also could occur when an alloc is made with size N and the free for this buffer specifies size M where M > N. Note: not every case is detectable.
This assert can also be caused when passing an invalid addr to free or if the size is causing the end of the buffer to be out of the expected range.
C SYNOPSIS
HeapMem_A_invalidFree
config HeapMem.A_zeroBlock // module-wide
index URL

Assert raised when a block of size 0 is requested

XDCscript usage meta-domain
HeapMem.A_zeroBlock = Assert.Desc {
    msg: "A_zeroBlock: Cannot allocate size 0"
};
DETAILS
This error can also be raised if the requested size wraps the contents of a SizeT type when it is adjusted for a minimum alignment. For example, when SizeT is 16-bits and a size request is made for 0xFFFB.
C SYNOPSIS
HeapMem_A_zeroBlock
config HeapMem.E_memory // module-wide
index URL

Raised when requested size exceeds largest free block

XDCscript usage meta-domain
HeapMem.E_memory = Error.Desc {
    msg: "out of memory: handle=0x%x, size=%u"
};
C SYNOPSIS
HeapMem_E_memory
metaonly config HeapMem.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
HeapMem.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new HeapMem.Params;
// Instance config-params object
    params.align = SizeT 0;
    // Alignment of the buffer being managed by this heap instance
    params.buf = Ptr 0;
    // Buffer being managed by this heap instance
    params.sectionName = String null;
    // Section name for the buffer managed by the instance
    params.size = UArg 0;
    // Size of buffer being managed by this heap instance
config HeapMem.buf // instance
index URL

Buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
...
params.buf = Ptr 0;
DETAILS
This parameter is ignored in the static HeapMem.create() call. It is a required parameter in the dynamic HeapMem_create() call.
HeapMem requires that the buffer be aligned on a target-specific minimum alignment, and will adjust the buffer's start address and size as necessary to satisfy this requirement.
C SYNOPSIS
null
config HeapMem.size // instance
index URL

Size of buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
...
params.size = UArg 0;
DETAILS
The usable size may be smaller depending on alignment requirements.
C SYNOPSIS
null
metaonly config HeapMem.align // instance
index URL

Alignment of the buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
...
params.align = SizeT 0;
DETAILS
In the static HeapMem.create() call, the buffer allocated for the HeapMem instance will have the alignment specified by this parameter.
In the dynamic case, the client must supply the buffer, so it is the client's responsibility to manage the buffer's alignment, and there is no 'align' parameter.
The specified alignment must be a power of 2.
HeapMem requires that the buffer be aligned on a target-specific minimum alignment, and will adjust (round up) the requested alignment as necessary to satisfy this requirement.
The default alignment is 0.
metaonly config HeapMem.sectionName // instance
index URL

Section name for the buffer managed by the instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
Instance Creation
index URL

XDCscript usage meta-domain
var params = new HeapMem.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMem.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
generated on Fri, 17 Jun 2011 00:23:43 GMT


module ti.sysbios.heaps.HeapMultiBuf
index URL

Multiple fixed size buffer heap manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The HeapMultiBuf manager provides functions to allocate and free storage from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf manages multiple fixed-size memory buffers. Each buffer contains a fixed number of allocable memory 'blocks' of the same size. Simply put, a HeapMultiBuf instance manages a collection of HeapBuf instances. HeapMultiBuf is intended as a fast and deterministic memory manager which can service requests for blocks of arbitrary size. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/heaps/HeapMultiBuf.xdc
#include <ti/sysbios/heaps/HeapMultiBuf.h>
Functions
Void | HeapMultiBuf_construct// Initialize a new instance object inside the provided structure(HeapMultiBuf_Struct *structP, const HeapMultiBuf_Params *params, Error_Block *eb);
HeapMultiBuf_Handle | HeapMultiBuf_create// Allocate and initialize a new instance object and return its handle(const HeapMultiBuf_Params *params, Error_Block *eb);
Void | HeapMultiBuf_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapMultiBuf_Handle *handleP);
Void | HeapMultiBuf_destruct// Finalize the instance object inside the provided structure(HeapMultiBuf_Struct *structP);
Void | HeapMultiBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapMultiBuf_Params *params);
Functions common to all IHeap modules
Ptr | HeapMultiBuf_alloc// Allocates a block of memory from the heap(HeapMultiBuf_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapMultiBuf_free// Free a block of memory back to the heap(HeapMultiBuf_Handle handle, Ptr block, SizeT size);
Void | HeapMultiBuf_getStats// Retrieve the statistics from the heap(HeapMultiBuf_Handle handle, Memory_Stats *stats);
Bool | HeapMultiBuf_isBlocking// Returns whether the heap may block during an alloc() or free()(HeapMultiBuf_Handle handle);
Functions common to all target instances
 | HeapMultiBuf_handle// Convert this instance structure pointer into an instance handle, HeapMultiBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapMultiBuf_Handle_label// The label associated with this instance object, HeapMultiBuf_Handle_name// The name of this instance object, HeapMultiBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapMultiBuf_Object_count// The number of statically-created instance objects, HeapMultiBuf_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapMultiBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapMultiBuf_Object_heap// The heap used to allocate dynamically-created instance objects, HeapMultiBuf_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapMultiBuf_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapMultiBuf_Module_getMask// Returns the diagnostics mask for this module, HeapMultiBuf_Module_hasMask// Test whether this module has a diagnostics mask, HeapMultiBuf_Module_heap// The heap from which this module allocates memory, HeapMultiBuf_Module_id// Get this module's unique id, HeapMultiBuf_Module_setMask// Set the diagnostics mask for this module, HeapMultiBuf_Module_startupDone// Test if this module has completed startup
Typedefs
typedef HeapMultiBuf_Object * | HeapMultiBuf_Handle// Client reference to an instance object;
typedef struct | HeapMultiBuf_Object// Opaque internal representation of an instance object HeapMultiBuf_Object;
typedef struct | HeapMultiBuf_Params// Instance config-params structure ...
typedef struct | HeapMultiBuf_Struct// Opaque client structure large enough to hold an instance object HeapMultiBuf_Struct;
Constants
extern const Assert_Id | HeapMultiBuf_A_blockNotFreed// Invalid block pointer;
extern const Error_Id | HeapMultiBuf_E_size// Raised when requested size exceeds all blockSizes;
DETAILS
The HeapMultiBuf manager provides functions to allocate and free storage from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf manages multiple fixed-size memory buffers. Each buffer contains a fixed number of allocable memory 'blocks' of the same size. Simply put, a HeapMultiBuf instance manages a collection of HeapBuf instances. HeapMultiBuf is intended as a fast and deterministic memory manager which can service requests for blocks of arbitrary size.
An example HeapMultiBuf instance might have sixteen 32-byte blocks in one buffer, and four 128-byte blocks in another buffer. A request for memory will be serviced by the smallest possible block, so a request for 100 bytes would receive a 128-byte block in our example.
Allocating from HeapMultiBuf will try to return a block from the first buffer which has:
1. A block size that is >= to the requested size
AND
2. An alignment that is >= to the requested alignment
If the first matching buffer is empty, HeapMultiBuf will only continue searching for a block if 'block borrowing' is enabled (see Block Borrowing).

HeapMultiBuf and HeapBuf

The HeapMultiBuf module is built on top of the HeapBuf module. Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration of a HeapMultiBuf is done by providing an array of configured HeapBuf parameter structures. Refer to the HeapBuf documentation for information on the buffer parameters. All of the documentation and parameters for HeapBuf apply equally to HeapMultiBuf. Another consequence of this is that configuration checking is left to the HeapBuf module. If a buffer in a HeapMultiBuf has been incorrectly configured (with blockSize = 0, for example), HeapBuf, not HeapMultiBuf, will raise an Assert. Since HeapMultiBuf is built on HeapBuf, it simply performs the logic to determine which HeapBuf to allocate a block from or which HeapBuf to free a block to.

Configuration Example

The following configuration code creates a HeapMultiBuf instance which manages 3 pools of 10 blocks each, with block sizes of 64, 128 and 256.
  var HeapMultiBuf = xdc.useModule('ti.sysbios.heaps.HeapMultiBuf');
  var HeapBuf = xdc.useModule('ti.sysbios.heaps.HeapBuf');

  // Create parameter structure for HeapMultiBuf instance.
  var hmbParams = new HeapMultiBuf.Params();
  hmbParams.numBufs = 3;

  // Create the parameter structures for each of the three
  // HeapBufs to be managed by the HeapMultiBuf instance.
  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[0].blockSize = 64;
  hmbParams.bufParams[0].numBlocks = 10;

  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[1].blockSize = 128;
  hmbParams.bufParams[1].numBlocks = 10;

  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[2].blockSize = 256;
  hmbParams.bufParams[2].numBlocks = 10;

  // Create the HeapMultiBuf instance, and assign the global handle
  // 'multiBufHeap' to it. Add '#include <xdc/cfg/global.h>' to your
  // .c file to reference the instance by this handle.
  Program.global.multiBufHeap = HeapMultiBuf.create(hmbParams);

Block Borrowing

HeapMultiBuf can support "block borrowing". With this feature turned on, if a request is made for a 32-byte block and none are available, HeapMultiBuf will continue looking for an available block in other buffers. When a borrowed block is freed, it will be returned back to its original buffer. Enabling Block Borrowing changes the determinism of alloc, since it may have to check any number of buffers to find an available block. Block borrowing may also occur, even if it is disabled, if a block of a particular size is requested with an alignment that is greater than the configured alignment for that block size. For example, a HeapMultiBuf is configured with a buffer of 32-byte blocks with an alignment of 8, and a buffer of 64-byte blocks with an alignment of 16. If a request is made for a 32-byte block with an alignment of 16, it will be serviced by the buffer of 64-byte blocks.

Static vs. Dynamic Creation

As with HeapBuf, a statically created HeapMultiBuf instance will ignore the bufSize and buf parameters. Dynamic creates require all of the parameters. It should be noted that static creates are ideal if code space is a concern; dynamically creating a HeapMultiBuf requires a relatively large amount of initialization code to be pulled in to the executable.

Block Sizes and Alignment

  • A buffer with a requested alignment of 0 will receive the target- specific minimum alignment.
  • The actual block sizes will be a multiple of the alignment. For example, if a buffer is configured to have 56-byte blocks with an alignment of 32, HeapMultiBuf will actually create 64-byte blocks. When providing the buffer for a dynamic create, make sure it is large enough to take this into account.
  • Multiple buffers with the same block size ARE allowed. This may occur, for example, if sizeof is used to specify the block sizes.
  • If any buffers have both the same block size and alignment, they will be merged. If this is a problem, consider managing these buffers directly with HeapBuf objects.

Real-Time Concerns

Allocation from and freeing to a HeapMultiBuf instance is non-blocking. HeapMultiBuf is deterministic:
  • A call to alloc will always take the same amount of time for a given block size (with block borrowing disabled).
  • The worst case call to free is constant and proportional to the number of buffers managed.

Restrictions

  • Align parameters must be a power of 2.
  • The buffers passed to dynamically create a HeapMultiBuf must be aligned according to the alignment parameter, and must be large enough to account for the actual block size after it has been rounded up to a multiple of the alignment.
  • Buffers must be provided to dynamically create a HeapMultiBuf, and cannot be provided to statically create a HeapMultiBuf.

Unconstrained Functions

All functions

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
alloc | Y | Y | Y | Y | N
construct | N* | N* | Y | Y | N
create | N* | N* | Y | Y | N
delete | N* | N* | Y | Y | N
destruct | N* | N* | Y | Y | N
free | Y | Y | Y | Y | N
getStats | Y | Y | Y | Y | N
isBlocking | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. HeapMultiBuf_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. HeapMultiBuf_Module_startupDone() returns FALSE).
  • *: Assuming blocking Heap is used for creation.
  • **: Assuming GateMutex is used as HeapMem's Gate.
  • + : Cannot use HeapMem object while it is being restored.
config HeapMultiBuf_A_blockNotFreed // module-wide
index URL

Invalid block pointer

C synopsis target-domain
extern const Assert_Id HeapMultiBuf_A_blockNotFreed;
DETAILS
This Assert is raised if a call to free does not successfully free the block back to any of the buffers. Indicates that the block pointer is invalid, or that the HeapMultiBuf state has been corrupted.
config HeapMultiBuf_E_size // module-wide
index URL

Raised when requested size exceeds all blockSizes

C synopsis target-domain
extern const Error_Id HeapMultiBuf_E_size;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId HeapMultiBuf_Module_id();
// Get this module's unique id
Bool HeapMultiBuf_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle HeapMultiBuf_Module_heap();
// The heap from which this module allocates memory
Bool HeapMultiBuf_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMultiBuf_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMultiBuf_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct HeapMultiBuf_Object HeapMultiBuf_Object;
// Opaque internal representation of an instance object
typedef HeapMultiBuf_Object *HeapMultiBuf_Handle;
// Client reference to an instance object
typedef struct HeapMultiBuf_Struct HeapMultiBuf_Struct;
// Opaque client structure large enough to hold an instance object
HeapMultiBuf_Handle HeapMultiBuf_handle(HeapMultiBuf_Struct *structP);
// Convert this instance structure pointer into an instance handle
HeapMultiBuf_Struct *HeapMultiBuf_struct(HeapMultiBuf_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct HeapMultiBuf_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Bool blockBorrow;
    // Turn block borrowing on (true) or off (false)
     HeapBuf_Params bufParams[];
    // Config parameters for each buffer
    Int numBufs;
    // Number of memory buffers
} HeapMultiBuf_Params;
Void HeapMultiBuf_Params_init(HeapMultiBuf_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMultiBuf_blockBorrow // instance
index URL

Turn block borrowing on (true) or off (false)

C synopsis target-domain
struct HeapMultiBuf_Params {
     ...
    Bool blockBorrow;
DETAILS
With block borrowing on, if there are no blocks available of the requested size, then alloc will look for a larger block to return. Calls to alloc which borrow blocks will be slower, and will cause internal fragmentation of the heap (until the block is freed), so it is ideal to configure a HeapMultiBuf such that block borrowing is not needed.
config HeapMultiBuf_bufParams // instance
index URL

Config parameters for each buffer

C synopsis target-domain
struct HeapMultiBuf_Params {
     ...
     HeapBuf_Params bufParams[];
DETAILS
Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration of a HeapMultiBuf is done by providing an array of configured HeapBuf parameter structures. Refer to the HeapBuf documentation for information on the buffer parameters. All of the documentation and parameters for HeapBuf apply to HeapMultiBuf. If a buffer is configured incorrectly, HeapBuf, not HeapMultiBuf, will raise an Assert.
config HeapMultiBuf_numBufs // instance
index URL

Number of memory buffers

C synopsis target-domain
struct HeapMultiBuf_Params {
     ...
    Int numBufs;
DETAILS
The number of different fixed size memory buffers that are managed by the heap instance. The bufParams array has length numBufs.
The default number of buffers is 0.
Instance Creation
index URL

C synopsis target-domain
HeapMultiBuf_Handle HeapMultiBuf_create(const HeapMultiBuf_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void HeapMultiBuf_construct(HeapMultiBuf_Struct *structP, const HeapMultiBuf_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
Instance Deletion
index URL

C synopsis target-domain
Void HeapMultiBuf_delete(HeapMultiBuf_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void HeapMultiBuf_destruct(HeapMultiBuf_Struct *structP);
// Finalize the instance object inside the provided structure
HeapMultiBuf_alloc() // instance
index URL

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapMultiBuf_alloc(HeapMultiBuf_Handle handle, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created HeapMultiBuf instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
HEAPMULTIBUF
HeapMultiBuf will return a block that is >= 'size' with an alignment that is >= 'align'. The HeapMultiBuf will attempt to service a request for any size; the specified size does not need to match the configured block sizes of the buffers.
RETURNS
Returns the address of the allocated memory.
HeapMultiBuf_free() // instance
index URL

Free a block of memory back to the heap

C synopsis target-domain
Void HeapMultiBuf_free(HeapMultiBuf_Handle handle, Ptr block, SizeT size);
ARGUMENTS
handle — handle of a previously-created HeapMultiBuf instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
HEAPMULTIBUF
HeapMultiBuf ignores the 'size' parameter to free. It determines the correct buffer to free the block to by comparing addresses.
HeapMultiBuf_getStats() // instance
index URL

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapMultiBuf_getStats(HeapMultiBuf_Handle handle, Memory_Stats *stats);
ARGUMENTS
handle — handle of a previously-created HeapMultiBuf instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
HeapMultiBuf_isBlocking() // instance
index URL

Returns whether the heap may block during an alloc() or free()

C synopsis target-domain
Bool HeapMultiBuf_isBlocking(HeapMultiBuf_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapMultiBuf instance object
HEAPMULTIBUF
This function always returns FALSE since the alloc/free never block on a resource.
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
Instance Convertors
index URL

C synopsis target-domain
IHeap_Handle HeapMultiBuf_Handle_upCast(HeapMultiBuf_Handle handle);
// unconditionally move one level up the inheritance hierarchy
HeapMultiBuf_Handle HeapMultiBuf_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int HeapMultiBuf_Object_count();
// The number of statically-created instance objects
HeapMultiBuf_Handle HeapMultiBuf_Object_get(HeapMultiBuf_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
HeapMultiBuf_Handle HeapMultiBuf_Object_first();
// The handle of the first dynamically-created instance object, or NULL
HeapMultiBuf_Handle HeapMultiBuf_Object_next(HeapMultiBuf_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle HeapMultiBuf_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *HeapMultiBuf_Handle_label(HeapMultiBuf_Handle handle, Types_Label *buf);
// The label associated with this instance object
String HeapMultiBuf_Handle_name(HeapMultiBuf_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/heaps/HeapMultiBuf.xdc
var HeapMultiBuf = xdc.useModule('ti.sysbios.heaps.HeapMultiBuf');
module-wide config parameters
     HeapMultiBuf.A_blockNotFreed// Invalid block pointer = Assert.Desc {
        msg: "Invalid block address on the free. Failed to free block back to heap."
    };
     HeapMultiBuf.E_size// Raised when requested size exceeds all blockSizes = Error.Desc {
        msg: "requested size is too big: handle=0x%x, size=%u"
    };
     HeapMultiBuf.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new HeapMultiBuf.Params// Instance config-params object;
        params.blockBorrow// Turn block borrowing on (true) or off (false) = Bool false;
        params.bufParams// Config parameters for each buffer = HeapBuf.Params[] undefined;
        params.numBufs// Number of memory buffers = Int 0;
per-instance creation
    var inst = HeapMultiBuf.create// Create an instance-object(params);
config HeapMultiBuf.A_blockNotFreed // module-wide
index URL

Invalid block pointer

XDCscript usage meta-domain
HeapMultiBuf.A_blockNotFreed = Assert.Desc {
    msg: "Invalid block address on the free. Failed to free block back to heap."
};
DETAILS
This Assert is raised if a call to free does not successfully free the block back to any of the buffers. Indicates that the block pointer is invalid, or that the HeapMultiBuf state has been corrupted.
C SYNOPSIS
HeapMultiBuf_A_blockNotFreed
config HeapMultiBuf.E_size // module-wide
index URL

Raised when requested size exceeds all blockSizes

XDCscript usage meta-domain
HeapMultiBuf.E_size = Error.Desc {
    msg: "requested size is too big: handle=0x%x, size=%u"
};
C SYNOPSIS
HeapMultiBuf_E_size
metaonly config HeapMultiBuf.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
HeapMultiBuf.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new HeapMultiBuf.Params;
// Instance config-params object
    params.blockBorrow = Bool false;
    // Turn block borrowing on (true) or off (false)
    params.bufParams = HeapBuf.Params[] undefined;
    // Config parameters for each buffer
    params.numBufs = Int 0;
    // Number of memory buffers
config HeapMultiBuf.blockBorrow // instance
index URL

Turn block borrowing on (true) or off (false)

XDCscript usage meta-domain
var params = new HeapMultiBuf.Params;
...
params.blockBorrow = Bool false;
DETAILS
With block borrowing on, if there are no blocks available of the requested size, then alloc will look for a larger block to return. Calls to alloc which borrow blocks will be slower, and will cause internal fragmentation of the heap (until the block is freed), so it is ideal to configure a HeapMultiBuf such that block borrowing is not needed.
C SYNOPSIS
null
config HeapMultiBuf.bufParams // instance
index URL

Config parameters for each buffer

XDCscript usage meta-domain
var params = new HeapMultiBuf.Params;
...
params.bufParams = HeapBuf.Params[] undefined;
DETAILS
Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration of a HeapMultiBuf is done by providing an array of configured HeapBuf parameter structures. Refer to the HeapBuf documentation for information on the buffer parameters. All of the documentation and parameters for HeapBuf apply to HeapMultiBuf. If a buffer is configured incorrectly, HeapBuf, not HeapMultiBuf, will raise an Assert.
C SYNOPSIS
null
config HeapMultiBuf.numBufs // instance
index URL

Number of memory buffers

XDCscript usage meta-domain
var params = new HeapMultiBuf.Params;
...
params.numBufs = Int 0;
DETAILS
The number of different fixed size memory buffers that are managed by the heap instance. The bufParams array has length numBufs.
The default number of buffers is 0.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new HeapMultiBuf.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMultiBuf.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
generated on Fri, 17 Jun 2011 00:23:43 GMT


module ti.sysbios.heaps.HeapNull
index URL

Empty heap

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in ti/sysbios/heaps/HeapNull.xdc
#include <ti/sysbios/heaps/HeapNull.h>
Functions
Void | HeapNull_construct// Initialize a new instance object inside the provided structure(HeapNull_Struct *structP, const HeapNull_Params *params);
HeapNull_Handle | HeapNull_create// Allocate and initialize a new instance object and return its handle(const HeapNull_Params *params, Error_Block *eb);
Void | HeapNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapNull_Handle *handleP);
Void | HeapNull_destruct// Finalize the instance object inside the provided structure(HeapNull_Struct *structP);
Void | HeapNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapNull_Params *params);
Functions common to all IHeap modules
Ptr | HeapNull_alloc// Allocates a block of memory from the heap(HeapNull_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapNull_free// Free a block of memory back to the heap(HeapNull_Handle handle, Ptr block, SizeT size);
Void | HeapNull_getStats// Retrieve the statistics from the heap(HeapNull_Handle handle, Memory_Stats *stats);
Bool | HeapNull_isBlocking// Returns whether the heap may block during an alloc() or free()(HeapNull_Handle handle);
Functions common to all target instances
 | HeapNull_handle// Convert this instance structure pointer into an instance handle, HeapNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapNull_Handle_label// The label associated with this instance object, HeapNull_Handle_name// The name of this instance object, HeapNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapNull_Object_count// The number of statically-created instance objects, HeapNull_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapNull_Object_heap// The heap used to allocate dynamically-created instance objects, HeapNull_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapNull_Module_getMask// Returns the diagnostics mask for this module, HeapNull_Module_hasMask// Test whether this module has a diagnostics mask, HeapNull_Module_heap// The heap from which this module allocates memory, HeapNull_Module_id// Get this module's unique id, HeapNull_Module_setMask// Set the diagnostics mask for this module, HeapNull_Module_startupDone// Test if this module has completed startup
Typedefs
typedef HeapNull_Object * | HeapNull_Handle// Client reference to an instance object;
typedef struct | HeapNull_Object// Opaque internal representation of an instance object HeapNull_Object;
typedef struct | HeapNull_Params// Instance config-params structure ...
typedef struct | HeapNull_Struct// Opaque client structure large enough to hold an instance object HeapNull_Struct;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId HeapNull_Module_id();
// Get this module's unique id
Bool HeapNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle HeapNull_Module_heap();
// The heap from which this module allocates memory
Bool HeapNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapNull_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct HeapNull_Object HeapNull_Object;
// Opaque internal representation of an instance object
typedef HeapNull_Object *HeapNull_Handle;
// Client reference to an instance object
typedef struct HeapNull_Struct HeapNull_Struct;
// Opaque client structure large enough to hold an instance object
HeapNull_Handle HeapNull_handle(HeapNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
HeapNull_Struct *HeapNull_struct(HeapNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct HeapNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} HeapNull_Params;
Void HeapNull_Params_init(HeapNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
HeapNull_Handle HeapNull_create(const HeapNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void HeapNull_construct(HeapNull_Struct *structP, const HeapNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void HeapNull_delete(HeapNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void HeapNull_destruct(HeapNull_Struct *structP);
// Finalize the instance object inside the provided structure
HeapNull_alloc() // instance
index URL

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapNull_alloc(HeapNull_Handle handle, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created HeapNull instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
RETURNS
Returns the address of the allocated memory.
HeapNull_free() // instance
index URL

Free a block of memory back to the heap

C synopsis target-domain
Void HeapNull_free(HeapNull_Handle handle, Ptr block, SizeT size);
ARGUMENTS
handle — handle of a previously-created HeapNull instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
HeapNull_getStats() // instance
index URL

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapNull_getStats(HeapNull_Handle handle, Memory_Stats *stats);
ARGUMENTS
handle — handle of a previously-created HeapNull instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
HeapNull_isBlocking() // instance
index URL

Returns whether the heap may block during an alloc() or free()

C synopsis target-domain
Bool HeapNull_isBlocking(HeapNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapNull instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
Instance Convertors
index URL

C synopsis target-domain
IHeap_Handle HeapNull_Handle_upCast(HeapNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
HeapNull_Handle HeapNull_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int HeapNull_Object_count();
// The number of statically-created instance objects
HeapNull_Handle HeapNull_Object_get(HeapNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
HeapNull_Handle HeapNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
HeapNull_Handle HeapNull_Object_next(HeapNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle HeapNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *HeapNull_Handle_label(HeapNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String HeapNull_Handle_name(HeapNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/heaps/HeapNull.xdc
var HeapNull = xdc.useModule('ti.sysbios.heaps.HeapNull');
module-wide config parameters
     HeapNull.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new HeapNull.Params// Instance config-params object;
per-instance creation
    var inst = HeapNull.create// Create an instance-object(params);
metaonly config HeapNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
HeapNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new HeapNull.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new HeapNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapNull.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:23:43 GMT


package ti.sysbios.interfaces
index URL

Contains all interface specifications

For the proxy-delegate mechanism between generic modules and the modules in ti.sysbios.family to work properly, both the proxy and the delegate modules must be implementations of a common interface specification. The Timer, Hwi, and Cache interface specifications reside in ti.sysbios.interfaces and are ti.sysbios.interfaces.ITimer, ti.sysbios.interfaces.IHwi, and ti.sysbios.interfaces.ICache respectively. [ more ... ]
XDCspec declarations sourced in ti/sysbios/interfaces/package.xdc
package ti.sysbios.interfaces [2, 0, 0, 0] {
    interface ICache;
    // Cache Interface
    interface IHwi;
    // Hardware Interrupt Support Module
    interface ISettings;
    // Interface for family-specific Settings modules
    interface ITimer;
    // Interface for Timer Peripherals Manager
    interface ITimerSupport;
    // Interface for TimerSupport Manager
    interface ITimestamp;
    // Timestamp Interface
}
DETAILS
For the proxy-delegate mechanism between generic modules and the modules in ti.sysbios.family to work properly, both the proxy and the delegate modules must be implementations of a common interface specification. The Timer, Hwi, and Cache interface specifications reside in ti.sysbios.interfaces and are ti.sysbios.interfaces.ITimer, ti.sysbios.interfaces.IHwi, and ti.sysbios.interfaces.ICache respectively.
These interface specifications define a minimum set of general APIs that, it is believed, will satisfy a vast majority of application requirements.
The I<mod>Support interfaces define "internal" interfaces used by the <mod> modules in their implementation. These interfaces simplify the process of porting to a new architecture; one only needs to implement the I<mod>Support interface to enable the full functionality of the ti.sysbios.<mod> module.
generated on Fri, 17 Jun 2011 00:23:46 GMT


interface ti.sysbios.interfaces.ICache
index URL

Cache Interface

XDCspec summary sourced in ti/sysbios/interfaces/ICache.xdc
interface ICache { ...
// inherits xdc.runtime.IModule
XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
package ti.sysbios.interfaces;
interface ICache {
module-wide constants & types
    enum Type// Lists of bitmask cache types {
         Type_L1P// Level 1 Program cache,
         Type_L1D// Level 1 Data cache,
         Type_L1// Level 1 caches,
         Type_L2P// Level 2 Program cache,
         Type_L2D// Level 2 Data cache,
         Type_L2// Level 2 caches,
         Type_ALLP// All Program caches,
         Type_ALLD// All Data caches,
         Type_ALL// All caches
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void disable// Disables the 'type' cache(s)(Bits16 type);
    Void enable// Enables all cache(s)(Bits16 type);
    Void inv// Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
    Void wait// Wait for a previous cache operation to complete();
    Void wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
    Void wbAll// Write back all caches();
    Void wbInv// Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
    Void wbInvAll// Write back invalidate all caches();
}
enum ICache.Type
index URL

Lists of bitmask cache types

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
enum Type {
    Type_L1P,
    // Level 1 Program cache
    Type_L1D,
    // Level 1 Data cache
    Type_L1,
    // Level 1 caches
    Type_L2P,
    // Level 2 Program cache
    Type_L2D,
    // Level 2 Data cache
    Type_L2,
    // Level 2 caches
    Type_ALLP,
    // All Program caches
    Type_ALLD,
    // All Data caches
    Type_ALL
    // All caches
};
metaonly config ICache.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ICache.disable() // module-wide
index URL

Disables the 'type' cache(s)

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void disable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
ICache.enable() // module-wide
index URL

Enables all cache(s)

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void enable(Bits16 type);
ARGUMENTS
type — bit mask of Cache type
ICache.inv() // module-wide
index URL

Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
ICache.wait() // module-wide
index URL

Wait for a previous cache operation to complete

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void wait();
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
ICache.wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written back to the source memory.
ICache.wbAll() // module-wide
index URL

Write back all caches

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void wbAll();
DETAILS
Perform a global write back. There is no effect on program cache. All data cache lines are left valid.
ICache.wbInv() // module-wide
index URL

Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all 'type' caches

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
type — bit mask of Cache type
wait — wait until the operation is completed
ICache.wbInvAll() // module-wide
index URL

Write back invalidate all caches

XDCspec declarations sourced in ti/sysbios/interfaces/ICache.xdc
Void wbInvAll();
DETAILS
Performs a global write back and invalidate. All cache lines are written out to physical memory and then invalidated.
generated on Fri, 17 Jun 2011 00:23:45 GMT


interface ti.sysbios.interfaces.IHwi
index URL

Hardware Interrupt Support Module

  • C synopsis
  • Individual elements
  • DETAILS
  • RUNTIME HWI CREATION
  • HOOK FUNCTIONS
The IHwi interface specifies APIs for globally enabling, disabling, and restoring interrupts. [ more ... ]
XDCspec summary sourced in ti/sysbios/interfaces/IHwi.xdc
interface IHwi { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
package ti.sysbios.interfaces;
interface IHwi {
module-wide constants & types
    enum MaskingOption// Shorthand interrupt masking options {
         MaskingOption_NONE,
         MaskingOption_ALL,
         MaskingOption_SELF,
         MaskingOption_BITMASK,
         MaskingOption_LOWER
    };
    typedef Void (*FuncPtr// Hwi create function type definition)(UArg);
    typedef UArg Irp// Interrupt Return Pointer;
    struct HookSet// Hwi hook set type definition {
        Void (*registerFxn)(Int);
        Void (*createFxn)(IHwi.Handle,Error.Block*);
        Void (*beginFxn)(IHwi.Handle);
        Void (*endFxn)(IHwi.Handle);
        Void (*deleteFxn)(IHwi.Handle);
    };
module-wide config parameters
    config Bool dispatcherAutoNestingSupport// Include interrupt nesting logic in interrupt dispatcher? = true;
    config Bool dispatcherIrpTrackingSupport// Controls whether the dispatcher retains the interrupted thread's return address = true;
    config Bool dispatcherSwiSupport// Include Swi scheduling logic in interrupt dispatcher?;
    config Bool dispatcherTaskSupport// Include Task scheduling logic in interrupt dispatcher?;
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void clearInterrupt// Clear a specific interrupt(UInt intNum);
    UInt disable// Globally disable interrupts();
    UInt disableInterrupt// Disable a specific interrupt(UInt intNum);
    UInt enable// Globally enable interrupts();
    UInt enableInterrupt// Enable a specific interrupt(UInt intNum);
    Void restore// Globally restore interrupts(UInt key);
    Void restoreInterrupt// Restore a specific interrupt's enabled/disabled state(UInt intNum, UInt key);
    Void startup// Initially enable interrupts();
    metaonly Void addHookSet// addHookSet is used in a config file to add a hook set (defined by struct HookSet)(IHwi.HookSet hook);
instance:
per-instance config parameters
    config UArg arg// ISR function argument. Default is 0 = 0;
    config Bool enableInt// Enable this interrupt now? Default is true = true;
    config Int eventId// Interrupt event ID (Interrupt Selection Number) = -1;
    config IHwi.MaskingOption maskSetting// maskSetting. Default is Hwi_MaskingOption_SELF = IHwi.MaskingOption_SELF;
    config Int priority// Interrupt priority = -1;
per-instance creation
     create// Create an instance-object(Int intNum, IHwi.FuncPtr hwiFxn);
per-instance functions
     IHwi.FuncPtr getFunc// Get Hwi function and arg(UArg *arg);
    Ptr getHookContext// Get hook instance's context for a Hwi(Int id);
     IHwi.Irp getIrp// Get address of interrupted instruction();
    Void setFunc// Overwrite Hwi function and arg(IHwi.FuncPtr fxn, UArg arg);
    Void setHookContext// Set hook instance's context for a Hwi(Int id, Ptr hookContext);
}
DETAILS
The IHwi interface specifies APIs for globally enabling, disabling, and restoring interrupts.
Additionally, management of individual, device-specific hardware interrupts is provided.
The user can statically or dynamically assign routines that run when specific hardware interrupts occur.
Dynamic assignment of Hwi routines to interrupts at run-time is done using the Hwi_create function.
Interrupt routines can be written completely in C, completely in assembly, or in a mix of C and assembly. In order to support interrupt routines written completely in C, an interrupt dispatcher is provided that performs the requisite prolog and epilog for an interrupt routine.
Some routines are assigned to interrupts by the other SYS/BIOS modules. For example, the Clock module configures its own timer interrupt handler. See the Clock Module for more details.
RUNTIME HWI CREATION
Below is an example of configuring an interrupt at runtime. Usually this code would be placed in main().
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/hal/Hwi.h>

  Hwi_Handle myHwi;

  Int main(Int argc, char* argv[])
  {
      Hwi_Params hwiParams;
      Error_Block eb;

      Hwi_Params_init(&hwiParams);
      Error_init(&eb);

      // set the argument you want passed to your ISR function
      hwiParams.arg = 1;

      // set the event id of the peripheral assigned to this interrupt
      hwiParams.eventId = 10;

      // don't allow this interrupt to nest itself
      hwiParams.maskSetting = Hwi_MaskingOption_SELF;

      //
      // Configure interrupt 5 to invoke "myIsr".
      // Automatically enables interrupt 5 by default
      // set params.enableInt = FALSE if you want to control
      // when the interrupt is enabled using Hwi_enableInterrupt()
      //

      myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);

      if (Error_check(&eb)) {
          // handle the error
      }
  }

  Void myIsr(UArg arg)
  {
      // here when interrupt #5 goes off
  }
HOOK FUNCTIONS
Sets of hook functions can be specified for the Hwi module using the configuration tool. Each set contains these hook functions:
  • Register: A function called before any statically-created Hwis are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
  • Create: A function that is called when a Hwi is created. This includes hwis that are created statically and those created dynamically using Hwi_create.
  • Begin: A function that is called just prior to running a Hwi.
  • End: A function that is called just after a Hwi finishes.
  • Delete: A function that is called when a Hwi is deleted at run-time with Hwi_delete.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to Hwi_setHookContext and Hwi_getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use Hwi_setHookContext or Hwi_getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete Functions
The create and delete functions are called whenever a Hwi is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).
  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);

  Void myDeleteFxn(Hwi_Handle hwi);
Begin and End Functions
The beginFxn and endFxn function hooks are called with interrupts globally disabled, therefore any hook processing function will contribute to the overall system interrupt response latency. In order to minimize this impact, carefully consider the processing time spent in an Hwi beginFxn or endFxn function hook.
  Void myBeginFxn(Hwi_Handle hwi);

  Void myEndFxn(Hwi_Handle hwi);
Hook functions can only be configured statically.
enum IHwi.MaskingOption
index URL

Shorthand interrupt masking options

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
enum MaskingOption {
    MaskingOption_NONE,
    MaskingOption_ALL,
    MaskingOption_SELF,
    MaskingOption_BITMASK,
    MaskingOption_LOWER
};
VALUES
MaskingOption_NONE — No interrupts are disabled
MaskingOption_ALL — All interrupts are disabled
MaskingOption_SELF — Only this interrupt is disabled
MaskingOption_BITMASK — User supplies interrupt enable masks
MaskingOption_LOWER — All current and lower priority interrupts are disabled.
Only a few targets/devices truly support this masking option. For those that don't, this setting is treated the same as MaskingOption_SELF.
typedef IHwi.FuncPtr
index URL

Hwi create function type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
typedef Void (*FuncPtr)(UArg);
typedef IHwi.Irp
index URL

Interrupt Return Pointer

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
typedef UArg Irp;
DETAILS
This is the address of the interrupted instruction.
struct IHwi.HookSet
index URL

Hwi hook set type definition

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
struct HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(IHwi.Handle,Error.Block*);
    Void (*beginFxn)(IHwi.Handle);
    Void (*endFxn)(IHwi.Handle);
    Void (*deleteFxn)(IHwi.Handle);
};
DETAILS
The functions that make up a hookSet have certain restrictions. They cannot call any Hwi instance functions other than Hwi_getHookContext() and Hwi_setHookContext(). For all practical purposes, they should treat the Hwi_Handle passed to these functions as an opaque handle.
config IHwi.dispatcherAutoNestingSupport // module-wide
index URL

Include interrupt nesting logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherAutoNestingSupport = true;
DETAILS
Default is true.
This option provides the user with the ability to optimize interrupt dispatcher performance when support for interrupt nesting is not required.
Setting this parameter to false will disable the logic in the interrupt dispatcher that manipulates interrupt mask registers and enables and disables interrupts before and after invoking the user's Hwi function.
Set this parameter to false if you don't need interrupts enabled during the execution of your Hwi functions.
config IHwi.dispatcherIrpTrackingSupport // module-wide
index URL

Controls whether the dispatcher retains the interrupted thread's return address

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherIrpTrackingSupport = true;
DETAILS
This option is enabled by default.
Setting this parameter to false will disable the logic in the interrupt dispatcher that keeps track of the interrupt's return address and provide a small savings in interrupt latency.
The application can get an interrupt's most recent return address using the getIrp API.
config IHwi.dispatcherSwiSupport // module-wide
index URL

Include Swi scheduling logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherSwiSupport;
DETAILS
Default is inherited from BIOS.swiEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that Swis will not be posted from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Swi scheduler prior to returning from an interrupt.
config IHwi.dispatcherTaskSupport // module-wide
index URL

Include Task scheduling logic in interrupt dispatcher?

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool dispatcherTaskSupport;
DETAILS
Default is inherited from BIOS.taskEnabled, which is true by default.
This option provides the user with the ability to optimize interrupt dispatcher performance when it is known that no Task scheduling APIs (ie Semaphore_post()) will be executed from any of their Hwi threads.
Setting this parameter to false will disable the logic in the interrupt dispatcher that invokes the Task scheduler prior to returning from an interrupt.
metaonly config IHwi.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
IHwi.clearInterrupt() // module-wide
index URL

Clear a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void clearInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to clear
DETAILS
Clears a specific interrupt's pending status. The implementation is family-specific.
IHwi.disable() // module-wide
index URL

Globally disable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt disable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_disable globally disables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_disable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
Call Hwi_disable before a portion of a function that needs to run without interruption. When critical processing is complete, call Hwi_restore or Hwi_enable to reenable hardware interrupts.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Hwi_disable may be called from main(). However, since Hwi interrupts are already disabled in main(), such a call has no effect.
CONSTRAINTS
If a Task switching API such as Semaphore_pend(), Semaphore_post(), Task_sleep(), or Task_yield() is invoked which results in a context switch while interrupts are disabled, an embedded call to Hwi_enable occurs on the way to the new thread context which unconditionally re-enables interrupts. Interrupts will remain enabled until a subsequent Hwi_disable invocation.
Swis always run with interrupts enabled. See Swi_post() for a discussion Swis and interrupts.
IHwi.disableInterrupt() // module-wide
index URL

Disable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt disableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to disable
RETURNS
key to restore previous enable/disable state
DETAILS
Disable a specific interrupt identified by an interrupt number.
IHwi.enable() // module-wide
index URL

Globally enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt enable();
RETURNS
opaque key for use by Hwi_restore()
DETAILS
Hwi_enable globally enables hardware interrupts and returns an opaque key indicating whether interrupts were globally enabled or disabled on entry to Hwi_enable(). The actual value of the key is target/device specific and is meant to be passed to Hwi_restore().
This function is called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
Hardware interrupts are enabled unless a call to Hwi_disable disables them.
Servicing of interrupts that occur while interrupts are disabled is postponed until interrupts are reenabled. However, if the same type of interrupt occurs several times while interrupts are disabled, the interrupt's function is executed only once when interrupts are reenabled.
A context switch can occur when calling Hwi_enable or Hwi_restore if an enabled interrupt occurred while interrupts are disabled.
Any call to Hwi_enable enables interrupts, even if Hwi_disable has been called several times.
Hwi_enable must not be called from main().
IHwi.enableInterrupt() // module-wide
index URL

Enable a specific interrupt

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
UInt enableInterrupt(UInt intNum);
ARGUMENTS
intNum — interrupt number to enable
RETURNS
key to restore previous enable/disable state
DETAILS
Enables a specific interrupt identified by an interrupt number.
IHwi.restore() // module-wide
index URL

Globally restore interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void restore(UInt key);
ARGUMENTS
key — enable/disable state to restore
DETAILS
Hwi_restore globally restores interrupts to the state determined by the key argument provided by a previous invocation of Hwi_disable.
A context switch may occur when calling Hwi_restore if Hwi_restore reenables interrupts and another Hwi occurred while interrupts were disabled.
Hwi_restore may be called from main(). However, since Hwi_enable cannot be called from main(), interrupts are always disabled in main(), and a call to Hwi_restore has no effect.
IHwi.restoreInterrupt() // module-wide
index URL

Restore a specific interrupt's enabled/disabled state

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void restoreInterrupt(UInt intNum, UInt key);
ARGUMENTS
intNum — interrupt number to restore
key — key returned from enableInt or disableInt
DETAILS
Restores a specific interrupt identified by an interrupt number. restoreInterrupt is generally used to restore an interrupt to its state before disableInterrupt or enableInterrupt was invoked
IHwi.startup() // module-wide
index URL

Initially enable interrupts

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void startup();
DETAILS
Called within BIOS_start
metaonly IHwi.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set (defined by struct HookSet)

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
metaonly Void addHookSet(IHwi.HookSet hook);
ARGUMENTS
hook — structure of type HookSet
DETAILS
HookSet structure elements may be omitted, in which case those elements will not exist.
config IHwi.arg // instance
index URL

ISR function argument. Default is 0

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config UArg arg = 0;
config IHwi.enableInt // instance
index URL

Enable this interrupt now? Default is true

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Bool enableInt = true;
config IHwi.eventId // instance
index URL

Interrupt event ID (Interrupt Selection Number)

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Int eventId = -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
config IHwi.maskSetting // instance
index URL

maskSetting. Default is Hwi_MaskingOption_SELF

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config IHwi.MaskingOption maskSetting = IHwi.MaskingOption_SELF;
config IHwi.priority // instance
index URL

Interrupt priority

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
config Int priority = -1;
DETAILS
Default is -1. Not all targets/devices support this instance parameter. On those that don't, this parameter is ignored.
Instance Creation
index URL

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
create(Int intNum, IHwi.FuncPtr hwiFxn);
// Create an instance-object
ARGUMENTS
intNum — interrupt number
hwiFxn — pointer to ISR function
DETAILS
A Hwi dispatcher table entry is created and filled with the function specified by the fxn parameter and the attributes specified by the params parameter.
If params is NULL, the Hwi's dispatcher properties are assigned a default set of values. Otherwise, the following properties are specified by a structure of type Hwi_Params.
  • The arg element is a generic argument that is passed to the plugged function as its only parameter. The default value is 0.
  • The enableInt element determines whether the interrupt should be enabled in the IER by create.
  • The maskSetting element defines the dispatcherAutoNestingSupport behavior of the interrupt.
Hwi_create returns a pointer to the created Hwi object.
IHwi.getFunc() // instance
index URL

Get Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
IHwi.FuncPtr getFunc(UArg *arg);
ARGUMENTS
arg — pointer for returning hwi's ISR function argument
RETURNS
hwi's ISR function
IHwi.getHookContext() // instance
index URL

Get hook instance's context for a Hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Ptr getHookContext(Int id);
RETURNS
hook instance's context for hwi
IHwi.getIrp() // instance
index URL

Get address of interrupted instruction

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
IHwi.Irp getIrp();
RETURNS
most current IRP of a Hwi
IHwi.setFunc() // instance
index URL

Overwrite Hwi function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void setFunc(IHwi.FuncPtr fxn, UArg arg);
ARGUMENTS
fxn — pointer to ISR function
arg — argument to ISR function
DETAILS
Replaces a Hwi object's hwiFxn function originally provided in create.
IHwi.setHookContext() // instance
index URL

Set hook instance's context for a Hwi

XDCspec declarations sourced in ti/sysbios/interfaces/IHwi.xdc
Void setHookContext(Int id, Ptr hookContext);
ARGUMENTS
id — hook instance's ID
hookContext — value to write to context
generated on Fri, 17 Jun 2011 00:23:46 GMT


interface ti.sysbios.interfaces.ISettings

metaonly interface ti.sysbios.interfaces.ISettings
index URL

Interface for family-specific Settings modules

Every new device family must implement this interface.
XDCspec summary sourced in ti/sysbios/interfaces/ISettings.xdc
metaonly interface ISettings { ...
XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
package ti.sysbios.interfaces;
metaonly interface ISettings {
module-wide functions
    String getDefaultBootModule// returns the family-specific Boot module();
    String getDefaultCacheDelegate// returns the family-specific CacheSupport module delegate();
    UInt32 getDefaultClockTickPeriod// returns the family-specific Clock tickPeriod();
    String getDefaultHwiDelegate// returns the family-specific Hwi module delegate();
    String getDefaultIntrinsicsSupportDelegate// returns the family-specific IntrinsicsSupport module delegate();
    String getDefaultTaskSupportDelegate// returns the family-specific TaskSupport module delegate();
    String getDefaultTimerDelegate// returns the family-specific Timer module delegate();
    String getDefaultTimerSupportDelegate// returns the family-specific Timer Support module delegate();
    String getDefaultTimestampDelegate// returns the family-specific Timestamp module delegate();
    String getFamilySettingsXml// Returns the path to the family-specific Grace page();
}
ISettings.getDefaultBootModule() // module-wide
index URL

returns the family-specific Boot module

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultBootModule();
ISettings.getDefaultCacheDelegate() // module-wide
index URL

returns the family-specific CacheSupport module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultCacheDelegate();
ISettings.getDefaultClockTickPeriod() // module-wide
index URL

returns the family-specific Clock tickPeriod

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
UInt32 getDefaultClockTickPeriod();
ISettings.getDefaultHwiDelegate() // module-wide
index URL

returns the family-specific Hwi module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultHwiDelegate();
ISettings.getDefaultIntrinsicsSupportDelegate() // module-wide
index URL

returns the family-specific IntrinsicsSupport module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultIntrinsicsSupportDelegate();
ISettings.getDefaultTaskSupportDelegate() // module-wide
index URL

returns the family-specific TaskSupport module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultTaskSupportDelegate();
ISettings.getDefaultTimerDelegate() // module-wide
index URL

returns the family-specific Timer module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultTimerDelegate();
ISettings.getDefaultTimerSupportDelegate() // module-wide
index URL

returns the family-specific Timer Support module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultTimerSupportDelegate();
ISettings.getDefaultTimestampDelegate() // module-wide
index URL

returns the family-specific Timestamp module delegate

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getDefaultTimestampDelegate();
ISettings.getFamilySettingsXml() // module-wide
index URL

Returns the path to the family-specific Grace page

XDCspec declarations sourced in ti/sysbios/interfaces/ISettings.xdc
String getFamilySettingsXml();
generated on Fri, 17 Jun 2011 00:23:46 GMT


interface ti.sysbios.interfaces.ITimer
index URL

Interface for Timer Peripherals Manager

  • C synopsis
  • Individual elements
XDCspec summary sourced in ti/sysbios/interfaces/ITimer.xdc
interface ITimer { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
package ti.sysbios.interfaces;
interface ITimer {
module-wide constants & types
    const UInt ANY// Const used to specify any timer = ~0;
    enum PeriodType// Timer period units {
         PeriodType_MICROSECS// period in microsecs,
         PeriodType_COUNTS// period in counts
    };
    enum RunMode// Timer Run Modes {
         RunMode_CONTINUOUS// periodic and continuous,
         RunMode_ONESHOT// one-shot,
         RunMode_DYNAMIC// dynamically reprogrammed
    };
    enum StartMode// Timer Start Modes {
         StartMode_AUTO// timer starts automatically,
         StartMode_USER// timer will be started by user
    };
    enum Status// Timer Status {
         Status_INUSE// timer in use,
         Status_FREE// timer is free
    };
    typedef Void (*FuncPtr// Timer tick function prototype)(UArg);
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    UInt getNumTimers// Returns number of timer peripherals on the platform();
     ITimer.Status getStatus// Returns timer status (free or in use)(UInt id);
instance:
per-instance config parameters
    config UArg arg// Argument for tick function = null;
    config Types.FreqHz extFreq// Timer frequency = {
        lo: 0,
        hi: 0
    };
    config UInt32 period// Period of a tick = 0;
    config ITimer.PeriodType periodType// Period type = ITimer.PeriodType_MICROSECS;
    config ITimer.RunMode runMode// Timer run mode = ITimer.RunMode_CONTINUOUS;
    config ITimer.StartMode startMode// Timer start mode = ITimer.StartMode_AUTO;
per-instance creation
     create// Create an instance-object(Int id, ITimer.FuncPtr tickFxn);
per-instance functions
    UInt32 getCount// Read timer counter register();
    Void getFreq// Return timer frequency in Hz(Types.FreqHz *freq);
     ITimer.FuncPtr getFunc// Get Timer function and arg(UArg *arg);
    UInt32 getPeriod// Get timer period in timer counts();
    Void setFunc// Overwrite Timer function and arg(ITimer.FuncPtr fxn, UArg arg);
    Void setPeriod// Set timer period specified in timer counts(UInt32 period);
    Bool setPeriodMicroSecs// Set timer period specified in microseconds(UInt32 microsecs);
    Void start// Reload and start the timer();
    Void stop// Stop the timer();
}
const ITimer.ANY
index URL

Const used to specify any timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
const UInt ANY = ~0;
enum ITimer.PeriodType
index URL

Timer period units

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum PeriodType {
    PeriodType_MICROSECS,
    // period in microsecs
    PeriodType_COUNTS
    // period in counts
};
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum ITimer.RunMode
index URL

Timer Run Modes

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum RunMode {
    RunMode_CONTINUOUS,
    // periodic and continuous
    RunMode_ONESHOT,
    // one-shot
    RunMode_DYNAMIC
    // dynamically reprogrammed
};
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum ITimer.StartMode
index URL

Timer Start Modes

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum StartMode {
    StartMode_AUTO,
    // timer starts automatically
    StartMode_USER
    // timer will be started by user
};
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum ITimer.Status
index URL

Timer Status

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
enum Status {
    Status_INUSE,
    // timer in use
    Status_FREE
    // timer is free
};
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef ITimer.FuncPtr
index URL

Timer tick function prototype

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
typedef Void (*FuncPtr)(UArg);
metaonly config ITimer.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ITimer.getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
UInt getNumTimers();
RETURNS
Number of timer peripherals.
ITimer.getStatus() // module-wide
index URL

Returns timer status (free or in use)

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
ITimer.Status getStatus(UInt id);
RETURNS
timer status
config ITimer.arg // instance
index URL

Argument for tick function

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config UArg arg = null;
DETAILS
Default is null.
config ITimer.extFreq // instance
index URL

Timer frequency

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config Types.FreqHz extFreq = {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config ITimer.period // instance
index URL

Period of a tick

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config UInt32 period = 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config ITimer.periodType // instance
index URL

Period type

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.PeriodType periodType = ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
config ITimer.runMode // instance
index URL

Timer run mode

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.RunMode runMode = ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
config ITimer.startMode // instance
index URL

Timer start mode

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
config ITimer.StartMode startMode = ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
create(Int id, ITimer.FuncPtr tickFxn);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
ITimer.getCount() // instance
index URL

Read timer counter register

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
UInt32 getCount();
RETURNS
timer counter value
ITimer.getFreq() // instance
index URL

Return timer frequency in Hz

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void getFreq(Types.FreqHz *freq);
ARGUMENTS
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
ITimer.getFunc() // instance
index URL

Get Timer function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
ITimer.FuncPtr getFunc(UArg *arg);
ARGUMENTS
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
ITimer.getPeriod() // instance
index URL

Get timer period in timer counts

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
UInt32 getPeriod();
RETURNS
period in timer counts
ITimer.setFunc() // instance
index URL

Overwrite Timer function and arg

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void setFunc(ITimer.FuncPtr fxn, UArg arg);
ARGUMENTS
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
ITimer.setPeriod() // instance
index URL

Set timer period specified in timer counts

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void setPeriod(UInt32 period);
ARGUMENTS
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
ITimer.setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Bool setPeriodMicroSecs(UInt32 microsecs);
ARGUMENTS
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
ITimer.start() // instance
index URL

Reload and start the timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void start();
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
ITimer.stop() // instance
index URL

Stop the timer

XDCspec declarations sourced in ti/sysbios/interfaces/ITimer.xdc
Void stop();
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
generated on Fri, 17 Jun 2011 00:23:46 GMT


interface ti.sysbios.interfaces.ITimerSupport
index URL

Interface for TimerSupport Manager

XDCspec summary sourced in ti/sysbios/interfaces/ITimerSupport.xdc
interface ITimerSupport { ...
// inherits xdc.runtime.IModule
XDCspec declarations sourced in ti/sysbios/interfaces/ITimerSupport.xdc
package ti.sysbios.interfaces;
interface ITimerSupport {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void enable// (UInt timerId, Error.Block *eb);
}
metaonly config ITimerSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/ITimerSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ITimerSupport.enable() // module-wide
index URL
XDCspec declarations sourced in ti/sysbios/interfaces/ITimerSupport.xdc
Void enable(UInt timerId, Error.Block *eb);
generated on Fri, 17 Jun 2011 00:23:46 GMT


interface ti.sysbios.interfaces.ITimestamp
index URL

Timestamp Interface

This interface defines the methods used by client applications to get timestamp values. It is implemented by the Timestamp module.
XDCspec summary sourced in ti/sysbios/interfaces/ITimestamp.xdc
interface ITimestamp { ...
// inherits xdc.runtime.ITimestampProvider
    // inherits xdc.runtime.ITimestampClient
        // inherits xdc.runtime.IModule
XDCspec declarations sourced in ti/sysbios/interfaces/ITimestamp.xdc
package ti.sysbios.interfaces;
interface ITimestamp inherits ITimestampProvider {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    override Bits32 get32// Return a 32-bit timestamp();
    override Void get64// Return a 64-bit timestamp(Types.Timestamp64 *result);
    override Void getFreq// Get the timestamp timer's frequency (in Hz)(Types.FreqHz *freq);
}
metaonly config ITimestamp.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in ti/sysbios/interfaces/ITimestamp.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ITimestamp.get32() // module-wide
index URL

Return a 32-bit timestamp

XDCspec declarations sourced in ti/sysbios/interfaces/ITimestamp.xdc
override Bits32 get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64, get64
ITimestamp.get64() // module-wide
index URL

Return a 64-bit timestamp

XDCspec declarations sourced in ti/sysbios/interfaces/ITimestamp.xdc
override Void get64(Types.Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32, get32
ITimestamp.getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

XDCspec declarations sourced in ti/sysbios/interfaces/ITimestamp.xdc
override Void getFreq(Types.FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64, get32, get64
generated on Fri, 17 Jun 2011 00:23:46 GMT


package ti.sysbios.knl
index URL

Contains core threading modules for the SYS/BIOS kernel

Many real-time applications must perform a number of functions at the same time, often in response to external events such as the availability of data or the presence of a control signal. Both the functions and when they are performed are important. [ more ... ]
XDCspec declarations sourced in ti/sysbios/knl/package.xdc
requires ti.sysbios.interfaces;
requires ti.sysbios.family;
package ti.sysbios.knl [2, 0, 0, 0] {
    module Clock;
    // System Clock Manager
    module Event;
    // Event Manager
    module Idle;
    // Idle Thread Manager
    module Mailbox;
    // Mailbox Manager
    module Semaphore;
    // Semaphore Manager
    module Swi;
    // Software Interrupt Manager
    module Task;
    // Task Manager
}
DETAILS
Many real-time applications must perform a number of functions at the same time, often in response to external events such as the availability of data or the presence of a control signal. Both the functions and when they are performed are important.
Such functions are called "threads". Within SYS/BIOS, the term is defined broadly to include any independent stream of instructions executed by the processor. A thread is a single point of control that can activate a function call or an interrupt service routine (ISR).
SYS/BIOS enables your applications to be structured as a collection of threads. Multithreaded programs allow higher-priority threads to preempt lower-priority threads and allow various types of interaction between threads, including blocking, communication, and synchronization.
SYS/BIOS provides support for several types of threads with different priorities. Each thread type has different execution and preemption characteristics. The thread types (from highest to lowest priority) are:
  • Hardware interrupts (ti.sysbios.hal.Hwi), which includes ti.sysbios.hal.Timer functions
  • Software interrupts (ti.sysbios.knl.Swi), which includes ti.sysbios.knl.Clock functions
  • Tasks (ti.sysbios.knl.Task)
  • Background thread (ti.sysbios.knl.Idle)
The ti.sysbios.knl package also provides several modules for synchronizing threads.
  • Semaphores (ti.sysbios.knl.Semaphore) are often used to coordinate access to a shared resource among a set of competing tasks. Semaphores can be used for task synchronization and mutual exclusion. Semaphore objects can be declared as either counting or binary semaphores. The same APIs are used for both counting and binary semaphores.
  • Events (ti.sysbios.knl.Event) provide a means for communicating between and synchronizing threads. They are similar to Semaphores, except that they allow you to specify multiple conditions ("events") that must occur before the waiting thread returns.
  • Mailboxes (ti.sysbios.knl.Mailbox) can be used to pass buffers from one thread to another. A Mailbox instance can be used by multiple readers and writers.
In addition to Semaphores, Events, and Mailboxes, you can use Gates to prevent concurrent accesses to critical regions of code. The xdc.runtime.Gate module is provided by XDCtools, but SYS/BIOS provides some additional implementations in ti.sysbios.gates.
generated on Fri, 17 Jun 2011 00:23:57 GMT


module ti.sysbios.knl.Clock
index URL

System Clock Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The System Clock Manager is responsible for all timing services in SYS/BIOS. It generates the periodic system tick. The tick period is configurable. The timeout and period for all Clock Instances and timeout values in other SYS/BIOS modules are specified in terms of Clock ticks. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Clock.xdc
#include <ti/sysbios/knl/Clock.h>
Functions
Void | Clock_construct// Initialize a new instance object inside the provided structure(Clock_Struct *structP, Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params);
Clock_Handle | Clock_create// Allocate and initialize a new instance object and return its handle(Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params, Error_Block *eb);
Void | Clock_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Clock_Handle *handleP);
Void | Clock_destruct// Finalize the instance object inside the provided structure(Clock_Struct *structP);
UInt | Clock_getPeriod// Get period of instance(Clock_Handle handle);
UInt32 | Clock_getTicks// Time in Clock ticks();
UInt | Clock_getTimeout// Get timeout of instance(Clock_Handle handle);
Timer_Handle | Clock_getTimerHandle// Get timer Handle();
Void | Clock_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Clock_Params *params);
Void | Clock_setFunc// Overwrite Clock function and arg(Clock_Handle handle, Clock_FuncPtr fxn, UArg arg);
Void | Clock_setPeriod// Set periodic interval(Clock_Handle handle, UInt period);
Void | Clock_setTimeout// Set the initial timeout(Clock_Handle handle, UInt timeout);
Void | Clock_start// Start instance(Clock_Handle handle);
Void | Clock_stop// Stop instance(Clock_Handle handle);
Void | Clock_tick// Advance Clock time by one tick();
Bool | Clock_tickReconfig// Reconfigure clock for new cpu frequency();
Void | Clock_tickStart// Start clock after reconfiguration();
Void | Clock_tickStop// Stop clock for reconfiguration();
Functions common to all target instances
 | Clock_handle// Convert this instance structure pointer into an instance handle, Clock_Handle_label// The label associated with this instance object, Clock_Handle_name// The name of this instance object, Clock_Object_count// The number of statically-created instance objects, Clock_Object_first// The handle of the first dynamically-created instance object, or NULL, Clock_Object_get// The handle of the i-th statically-created instance object (array == NULL), Clock_Object_heap// The heap used to allocate dynamically-created instance objects, Clock_Object_next// The handle of the next dynamically-created instance object, or NULL, Clock_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Clock_Module_getMask// Returns the diagnostics mask for this module, Clock_Module_hasMask// Test whether this module has a diagnostics mask, Clock_Module_heap// The heap from which this module allocates memory, Clock_Module_id// Get this module's unique id, Clock_Module_setMask// Set the diagnostics mask for this module, Clock_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Clock_FuncPtr// Instance function prototype)(UArg);
typedef Clock_Object * | Clock_Handle// Client reference to an instance object;
typedef struct | Clock_Object// Opaque internal representation of an instance object Clock_Object;
typedef struct | Clock_Params// Instance config-params structure ...
typedef struct | Clock_Struct// Opaque client structure large enough to hold an instance object Clock_Struct;
typedef enum | Clock_TickMode// Clock Tick Mode ...
typedef enum | Clock_TickSource// Clock tick source ...
Constants
extern const Assert_Id | Clock_A_badThreadType// Asserted in Clock_create and Clock_delete;
extern const Assert_Id | Clock_A_clockDisabled// Asserted in Clock_create();
extern const Log_Event | Clock_LM_begin// Logged just prior to calling each Clock function;
extern const Log_Event | Clock_LM_tick// Logged in every Clock tick interrupt;
extern const Log_Event | Clock_LW_delayed// Logged if Clock Swi delayed by >= 1 tick;
extern const Clock_TickMode | Clock_tickMode// Timer tick mode;
extern const UInt32 | Clock_tickPeriod// Tick period specified in microseconds;
extern const Clock_TickSource | Clock_tickSource// Source of clock ticks;
extern const UInt | Clock_timerId// Timer Id used to create a Timer instance;
DETAILS
The System Clock Manager is responsible for all timing services in SYS/BIOS. It generates the periodic system tick. The tick period is configurable. The timeout and period for all Clock Instances and timeout values in other SYS/BIOS modules are specified in terms of Clock ticks.
The Clock Manager supports two tick "modes": a periodic mode with an interrupt on each tick (TickMode_PERIODIC), and a tick suppression mode (TickMode_DYNAMIC), which reduces the number of timer interrupts to the minimum required to support the scheduled timeouts. For devices that support it (e.g., MSP430 devices), TickMode_DYNAMIC will be the default mode if one is not specified in the application configuration; otherwise, the default mode will be TickMode_PERIODIC. The following example shows how the tick mode can be specified in the application configuration:
  var Clock = xdc.useModule('ti.sysbios.knl.Clock');

  // Tell the Clock module to use TickMode_PERIODIC
  Clock.tickMode = Clock.TickMode_PERIODIC;
Clock Instances are functions that can be scheduled to run after a certain number of Clock ticks. Clock instances are either one-shot or periodic. Instances are started when created or they are started later using the Clock_start()function. Instances can be stopped using the Clock_stop() function. All Clock Instances are executed when they expire in the context of a software interrupt.
Clock objects are placed in the Clock object service list when created/constructed and remain there until deleted/destructed. To minimize processing overhead, unused or expired Clock objects should be deleted or destructed.
The getTicks() function returns number of clock ticks since startup.
By default, the Clock module statically configures a ti.sysbios.hal.Timer timer instance to provide the periodic 1 ms tick interrupt. If you want to use a custom configured timer for the Clock module's tick source, use the following example configuration as a guide:
  var Clock = xdc.useModule('ti.sysbios.knl.Clock');

  // Tell the Clock module that YOU are providing the periodic interrupt
  Clock.tickSource = Clock.TickSource_USER;

  // this example uses the ti.sysbios.timers.dmtimer.Timer module
  var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');

  // create a dmtimer config parameter object
  var timerParams = new Timer.Params();

  // make sure you set the period to 1000 us (1ms)
  timerParams.period = 1000;

  // custom dmtimer config parameters here...
  timerParams.twer.ovf_wup_ena = 1;

  // Create the timer.
  // This example uses timer id 3.
  // The timer interrupt handler must be set to 'Clock.tick'.
  Timer.create(3, Clock.tick, timerParams);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
construct | N | N | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getTicks | Y | Y | Y | N | N
getTimeout | Y | Y | Y | Y | N
getTimerHandle | Y | Y | Y | Y | Y
Params_init | Y | Y | Y | Y | Y
setFunc | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setTimeout | Y | Y | Y | Y | N
start | Y | Y | Y | Y | N
stop | Y | Y | Y | Y | N
tick | Y | Y | Y | N | N
tickReconfig | Y | Y | Y | N | N
tickStart | Y | Y | Y | N | N
tickStop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Clock_Module_startupDone() returns TRUE).
    • During Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During Startup.firstFxns.
    • In your module startup before this module is started (e.g. Clock_Module_startupDone() returns FALSE).
enum Clock_TickMode
index URL

Clock Tick Mode

C synopsis target-domain
typedef enum Clock_TickMode {
    Clock_TickMode_PERIODIC,
    // Timer will interrupt every period
    Clock_TickMode_DYNAMIC
    // Unnecessary timer ticks can be suppressed
} Clock_TickMode;
enum Clock_TickSource
index URL

Clock tick source

C synopsis target-domain
typedef enum Clock_TickSource {
    Clock_TickSource_TIMER,
    // Use Timer to automatically call Clock_tick()
    Clock_TickSource_USER,
    // Application explicitly calls Clock_tick()
    Clock_TickSource_NULL
    // Clock_tick() is never called
} Clock_TickSource;
VALUES
TickSource_TIMER — Clock_tick() is called automatically from within a ti.sysbios.hal.Timer ISR. The specific timer and its period can be controlled via timerId and tickPeriod.
TickSource_USER — Clock_tick() must be explicitly called by the user's application.
TickSource_NULL — Clock_tick() is never called. In this case, it is an error for the application to ever call Clock_tick().
SEE
tickPeriod, timerId
typedef Clock_FuncPtr
index URL

Instance function prototype

C synopsis target-domain
typedef Void (*Clock_FuncPtr)(UArg);
config Clock_A_badThreadType // module-wide
index URL

Asserted in Clock_create and Clock_delete

C synopsis target-domain
extern const Assert_Id Clock_A_badThreadType;
config Clock_A_clockDisabled // module-wide
index URL

Asserted in Clock_create()

C synopsis target-domain
extern const Assert_Id Clock_A_clockDisabled;
config Clock_LM_begin // module-wide
index URL

Logged just prior to calling each Clock function

C synopsis target-domain
extern const Log_Event Clock_LM_begin;
config Clock_LM_tick // module-wide
index URL

Logged in every Clock tick interrupt

C synopsis target-domain
extern const Log_Event Clock_LM_tick;
config Clock_LW_delayed // module-wide
index URL

Logged if Clock Swi delayed by >= 1 tick

C synopsis target-domain
extern const Log_Event Clock_LW_delayed;
config Clock_tickMode // module-wide
index URL

Timer tick mode

C synopsis target-domain
extern const Clock_TickMode Clock_tickMode;
DETAILS
This parameter specifies the tick mode to be used by the underlying Timer. With TickMode_PERIODIC the timer will interrupt the CPU at a fixed rate, defined by the tickPeriod. With TickMode_DYNAMIC the timer can be dynamically reprogrammed by Clock, to interrupt the CPU when the next tick is actually needed for a scheduled timeout.
config Clock_tickPeriod // module-wide
index URL

Tick period specified in microseconds

C synopsis target-domain
extern const UInt32 Clock_tickPeriod;
DETAILS
Default value is family dependent. For example, Linux systems often only support a minimum period of 10000 us and multiples of 10000 us. TI platforms have a default of 1000 us.
config Clock_tickSource // module-wide
index URL

Source of clock ticks

C synopsis target-domain
extern const Clock_TickSource Clock_tickSource;
DETAILS
If this parameter is not set to TickSource_TIMER,
  Clock_tickStart(),
  Clock_tickStop(), and
  Clock_tickReconfig(), have no effect.
The default is TickSource_TIMER.
config Clock_timerId // module-wide
index URL

Timer Id used to create a Timer instance

C synopsis target-domain
extern const UInt Clock_timerId;
DETAILS
If Clock.tickSource is set to TickSource_TIMER, the Clock module automatically creates a instance that automatically calls Clock_doTick() on a periodic basis (as specified by tickPeriod and periodType.)
This configuration parameter allows you to control which timer is used to drive the Clock module.
The default value is Timer.ANY (~0) and the maximum timerId possible is family and device specific.
SEE
ti.sysbios.hal.Timer
Clock_getTicks() // module-wide
index URL

Time in Clock ticks

C synopsis target-domain
UInt32 Clock_getTicks();
RETURNS
time in clock ticks
DETAILS
The value returned will wrap back to zero after it reaches the max value that can be stored in 32 bits.
Clock_getTimerHandle() // module-wide
index URL

Get timer Handle

C synopsis target-domain
Timer_Handle Clock_getTimerHandle();
RETURNS
Timer Handle
DETAILS
Used when is it necessary to change family specific options for the timer and its Hwi Object.
Clock_tick() // module-wide
index URL

Advance Clock time by one tick

C synopsis target-domain
Void Clock_tick();
DETAILS
After incrementing a global tick counter, this function posts a Swi that processes the clock instances.
This function is automatically called by a timer ISR when tickSource is set to TickSource_TIMER.
When tickSource is set to TickSource_USER, Clock_tick() must be called by the application. Usually, this is done within a user defined Hwi, Swi, or Task.
Note that this function is not re-entrant. The application is responsible for ensuring that invocations of this function are serialized: either only one thread in the system ever calls this function or all calls are "wrapped" by an appropriate mutex.
SEE
tickSource
Clock_tickReconfig() // module-wide
index URL

Reconfigure clock for new cpu frequency

C synopsis target-domain
Bool Clock_tickReconfig();
RETURNS
true if successful
DETAILS
This function uses the new cpu frequency to reconfigure the timer used for generation of clock ticks such that tick period is accurate. This function is used along with Clock_tickStop() and Clock_tickStart() to allow reconfiguration of timer at runtime.
When calling Clock_tickReconfig outside of main(), you must also call Clock_tickStop and Clock_tickStart to stop and restart the timer. Use the following call sequence:
  // disable interrupts if an interrupt could lead to
  // another call to Clock_tickReconfig or if interrupt
  // processing relies on having a running timer
  Hwi_disable() or Swi_disable();
  BIOS_setCpuFrequency(Types.FreqHz *freq);
  Clock_tickStop();
  Clock_tickReconfig();
  Clock_tickStart();
  Hwi_restore() or Swi_enable()
When calling Clock_tickReconfig from main(), the timer has not yet been started because the timer is started as part of BIOS_start(). As a result, you can use the following simplified call sequence in main():
  BIOS_setCpuFrequency(Types.FreqHz *freq);
  Clock_tickReconfig(Void);
The return value is false if the timer cannot support the new frequency
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.
Clock_tickStart() // module-wide
index URL

Start clock after reconfiguration

C synopsis target-domain
Void Clock_tickStart();
DETAILS
This function starts the timer used for generation of clock ticks It is used along with Clock_tickStop() and Clock_tickReconfig() to allow reconfiguration of timer at runtime. The new timer configuration reflects changes caused by a call to reconfig().
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.
Clock_tickStop() // module-wide
index URL

Stop clock for reconfiguration

C synopsis target-domain
Void Clock_tickStop();
DETAILS
This function is used to stop the timer used for generation of clock ticks. It is used along with Clock_tickStart() and Clock_tickReconfig() to allow reconfiguration of timer at runtime.
CONSTRAINTS
This function is non-reentrant and appropriate locks must be used to protect against re-entrancy.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Clock_Module_id();
// Get this module's unique id
Bool Clock_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Clock_Module_heap();
// The heap from which this module allocates memory
Bool Clock_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Clock_Module_getMask();
// Returns the diagnostics mask for this module
Void Clock_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Clock_Object Clock_Object;
// Opaque internal representation of an instance object
typedef Clock_Object *Clock_Handle;
// Client reference to an instance object
typedef struct Clock_Struct Clock_Struct;
// Opaque client structure large enough to hold an instance object
Clock_Handle Clock_handle(Clock_Struct *structP);
// Convert this instance structure pointer into an instance handle
Clock_Struct *Clock_struct(Clock_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Clock_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Uninterpreted argument passed to instance function
    UInt period;
    // Period of this instance (in clock ticks)
    Bool startFlag;
    // Start immediately after instance is created
} Clock_Params;
Void Clock_Params_init(Clock_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Clock_arg // instance
index URL

Uninterpreted argument passed to instance function

C synopsis target-domain
struct Clock_Params {
     ...
    UArg arg;
DETAILS
The default is null.
config Clock_period // instance
index URL

Period of this instance (in clock ticks)

C synopsis target-domain
struct Clock_Params {
     ...
    UInt period;
DETAILS
The default value of this parameter is 0, which indicates this is a one-shot Clock object.
A non zero value for this parameter specifies that the Clock object is to be called periodically, and also specifies the rate (in Clock ticks) that the Clock function will be called AFTER the initial 'timeout' argument period.
For one-shot Clock instances, this parameter must be set to zero.
config Clock_startFlag // instance
index URL

Start immediately after instance is created

C synopsis target-domain
struct Clock_Params {
     ...
    Bool startFlag;
DETAILS
When this flag is set to false, the user will have to call Clock_start() to start the instance.
When set to true, both statically created Clock objects and Clock objects created in main() are started at the end of main() when the user calls BIOS_start(). Dynamically created Clock objects created after main() (ie within a task) will be started immediately.
The default setting for this parameter is false.
The configured Clock function will be called initially after an interval equal to the 'timeout' argument for both one-shot and periodic Clock objects.
Periodic Clock objects will subsequently be called at the rate specified by the period parameter.
Instance Creation
index URL

C synopsis target-domain
Clock_Handle Clock_create(Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Clock_construct(Clock_Struct *structP, Clock_FuncPtr clockFxn, UInt timeout, const Clock_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
clockFxn — Function that runs upon timeout
timeout — One-shot timeout or initial start delay (in clock ticks)
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
The first argument is the function that gets called when the timeout expires.
The 'timeout' argument is used to specify the initial timeout for both one-shot and periodic Clock instances (in Clock ticks).
The period parameter is used to set the subsequent timeout interval (in Clock ticks) for periodic instances.
For one-shot instances, the period parameter must be set to zero.
When instances are created they are placed upon a linked list managed by the Clock module. For this reason, instances cannot be created from either Hwi or Swi context.
Instance Deletion
index URL

C synopsis target-domain
Void Clock_delete(Clock_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Clock_destruct(Clock_Struct *structP);
// Finalize the instance object inside the provided structure
Clock_getPeriod() // instance
index URL

Get period of instance

C synopsis target-domain
UInt Clock_getPeriod(Clock_Handle handle);
ARGUMENTS
handle — handle of a previously-created Clock instance object
RETURNS
returns periodic interval in Clock ticks
DETAILS
Returns the period of an instance.
Clock_getTimeout() // instance
index URL

Get timeout of instance

C synopsis target-domain
UInt Clock_getTimeout(Clock_Handle handle);
ARGUMENTS
handle — handle of a previously-created Clock instance object
RETURNS
returns timeout in clock ticks
DETAILS
Returns the remaining time if instance has been started.
Clock_setFunc() // instance
index URL

Overwrite Clock function and arg

C synopsis target-domain
Void Clock_setFunc(Clock_Handle handle, Clock_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Clock instance object
clockFxn — function of type FuncPtr
arg — argument to clockFxn
DETAILS
Replaces a Clock object's clockFxn function originally provided in create.
CONSTRAINTS
Cannot change function and arg of Clock object that has been started.
Clock_setPeriod() // instance
index URL

Set periodic interval

C synopsis target-domain
Void Clock_setPeriod(Clock_Handle handle, UInt period);
ARGUMENTS
handle — handle of a previously-created Clock instance object
period — periodic interval in Clock ticks
CONSTRAINTS
Cannot change period of instance that has been started.
Clock_setTimeout() // instance
index URL

Set the initial timeout

C synopsis target-domain
Void Clock_setTimeout(Clock_Handle handle, UInt timeout);
ARGUMENTS
handle — handle of a previously-created Clock instance object
timeout — initial timeout in Clock ticks
CONSTRAINTS
Cannot change the initial timeout of instance that has been started.
Clock_start() // instance
index URL

Start instance

C synopsis target-domain
Void Clock_start(Clock_Handle handle);
ARGUMENTS
handle — handle of a previously-created Clock instance object
DETAILS
The timeout and period values set during create() or by calling Clock_setTimeout() and Clock_setPeriod() are used and the expiry is recomputed. Note that for periodic instances, the first expiry is computed using the timeout specified. All subsequent expiries use the period value.
CONSTRAINTS
Timeout of instance cannot be zero
Clock_stop() // instance
index URL

Stop instance

C synopsis target-domain
Void Clock_stop(Clock_Handle handle);
ARGUMENTS
handle — handle of a previously-created Clock instance object
Instance Built-Ins
index URL

C synopsis target-domain
Int Clock_Object_count();
// The number of statically-created instance objects
Clock_Handle Clock_Object_get(Clock_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Clock_Handle Clock_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Clock_Handle Clock_Object_next(Clock_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Clock_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Clock_Handle_label(Clock_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Clock_Handle_name(Clock_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Clock.xdc
var Clock = xdc.useModule('ti.sysbios.knl.Clock');
module-wide constants & types
    values of type Clock.TickMode// Clock Tick Mode
        const Clock.TickMode_PERIODIC// Timer will interrupt every period;
        const Clock.TickMode_DYNAMIC// Unnecessary timer ticks can be suppressed;
    values of type Clock.TickSource// Clock tick source
        const Clock.TickSource_TIMER// Use Timer to automatically call Clock_tick();
        const Clock.TickSource_USER// Application explicitly calls Clock_tick();
        const Clock.TickSource_NULL// Clock_tick() is never called;
module-wide config parameters
     Clock.A_badThreadType// Asserted in Clock_create and Clock_delete = Assert.Desc {
        msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
    };
     Clock.A_clockDisabled// Asserted in Clock_create() = Assert.Desc {
        msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
    };
     Clock.LM_begin// Logged just prior to calling each Clock function = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: clk: 0x%x, func: 0x%x"
    };
     Clock.LM_tick// Logged in every Clock tick interrupt = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_tick: tick: %d"
    };
     Clock.LW_delayed// Logged if Clock Swi delayed by >= 1 tick = Log.EventDesc {
        mask: Diags.USER3,
        msg: "LW_delayed: delay: %d"
    };
     Clock.tickMode// Timer tick mode = Clock.TickMode undefined;
     Clock.tickPeriod// Tick period specified in microseconds = UInt32 undefined;
     Clock.tickSource// Source of clock ticks = Clock.TickSource Clock.TickSource_TIMER;
     Clock.timerId// Timer Id used to create a Timer instance = UInt ~0;
     Clock.common$// Common module configuration parameters = Types.Common$ undefined;
     Clock.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
     Clock.swiPriority// The priority of Swi used by Clock to process its instances = UInt undefined;
per-instance config parameters
    var params = new Clock.Params// Instance config-params object;
        params.arg// Uninterpreted argument passed to instance function = UArg null;
        params.period// Period of this instance (in clock ticks) = UInt 0;
        params.startFlag// Start immediately after instance is created = Bool false;
per-instance creation
    var inst = Clock.create// Create an instance-object(Void(*)(UArg) clockFxn, UInt timeout, params);
enum Clock.TickMode
index URL

Clock Tick Mode

XDCscript usage meta-domain
values of type Clock.TickMode
    const Clock.TickMode_PERIODIC;
    // Timer will interrupt every period
    const Clock.TickMode_DYNAMIC;
    // Unnecessary timer ticks can be suppressed
C SYNOPSIS
Clock_TickMode
enum Clock.TickSource
index URL

Clock tick source

XDCscript usage meta-domain
values of type Clock.TickSource
    const Clock.TickSource_TIMER;
    // Use Timer to automatically call Clock_tick()
    const Clock.TickSource_USER;
    // Application explicitly calls Clock_tick()
    const Clock.TickSource_NULL;
    // Clock_tick() is never called
VALUES
TickSource_TIMER — Clock_tick() is called automatically from within a ti.sysbios.hal.Timer ISR. The specific timer and its period can be controlled via timerId and tickPeriod.
TickSource_USER — Clock_tick() must be explicitly called by the user's application.
TickSource_NULL — Clock_tick() is never called. In this case, it is an error for the application to ever call Clock_tick().
SEE
tickPeriod, timerId
C SYNOPSIS
Clock_TickSource
config Clock.A_badThreadType // module-wide
index URL

Asserted in Clock_create and Clock_delete

XDCscript usage meta-domain
Clock.A_badThreadType = Assert.Desc {
    msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
};
C SYNOPSIS
Clock_A_badThreadType
config Clock.A_clockDisabled // module-wide
index URL

Asserted in Clock_create()

XDCscript usage meta-domain
Clock.A_clockDisabled = Assert.Desc {
    msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
};
C SYNOPSIS
Clock_A_clockDisabled
config Clock.LM_begin // module-wide
index URL

Logged just prior to calling each Clock function

XDCscript usage meta-domain
Clock.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: clk: 0x%x, func: 0x%x"
};
C SYNOPSIS
Clock_LM_begin
config Clock.LM_tick // module-wide
index URL

Logged in every Clock tick interrupt

XDCscript usage meta-domain
Clock.LM_tick = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_tick: tick: %d"
};
C SYNOPSIS
Clock_LM_tick
config Clock.LW_delayed // module-wide
index URL

Logged if Clock Swi delayed by >= 1 tick

XDCscript usage meta-domain
Clock.LW_delayed = Log.EventDesc {
    mask: Diags.USER3,
    msg: "LW_delayed: delay: %d"
};
C SYNOPSIS
Clock_LW_delayed
config Clock.tickMode // module-wide
index URL

Timer tick mode

XDCscript usage meta-domain
Clock.tickMode = Clock.TickMode undefined;
DETAILS
This parameter specifies the tick mode to be used by the underlying Timer. With TickMode_PERIODIC the timer will interrupt the CPU at a fixed rate, defined by the tickPeriod. With TickMode_DYNAMIC the timer can be dynamically reprogrammed by Clock, to interrupt the CPU when the next tick is actually needed for a scheduled timeout.
C SYNOPSIS
Clock_tickMode
config Clock.tickPeriod // module-wide
index URL

Tick period specified in microseconds

XDCscript usage meta-domain
Clock.tickPeriod = UInt32 undefined;
DETAILS
Default value is family dependent. For example, Linux systems often only support a minimum period of 10000 us and multiples of 10000 us. TI platforms have a default of 1000 us.
C SYNOPSIS
Clock_tickPeriod
config Clock.tickSource // module-wide
index URL

Source of clock ticks

XDCscript usage meta-domain
Clock.tickSource = Clock.TickSource Clock.TickSource_TIMER;
DETAILS
If this parameter is not set to TickSource_TIMER,
  Clock_tickStart(),
  Clock_tickStop(), and
  Clock_tickReconfig(), have no effect.
The default is TickSource_TIMER.
C SYNOPSIS
Clock_tickSource
config Clock.timerId // module-wide
index URL

Timer Id used to create a Timer instance

XDCscript usage meta-domain
Clock.timerId = UInt ~0;
DETAILS
If Clock.tickSource is set to TickSource_TIMER, the Clock module automatically creates a instance that automatically calls Clock_doTick() on a periodic basis (as specified by tickPeriod and periodType.)
This configuration parameter allows you to control which timer is used to drive the Clock module.
The default value is Timer.ANY (~0) and the maximum timerId possible is family and device specific.
SEE
ti.sysbios.hal.Timer
C SYNOPSIS
Clock_timerId
metaonly config Clock.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Clock.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Clock.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
Clock.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly config Clock.swiPriority // module-wide
index URL

The priority of Swi used by Clock to process its instances

XDCscript usage meta-domain
Clock.swiPriority = UInt undefined;
DETAILS
All Clock instances are executed in the context of a single Swi. This parameter allows you to control the priority of that Swi.
The default value of this parameter is Swi.numPriorities - 1; i.e., the maximum Swi priority.
SEE
ti.sysbios.knl.Swi.numPriorities
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Clock.Params;
// Instance config-params object
    params.arg = UArg null;
    // Uninterpreted argument passed to instance function
    params.period = UInt 0;
    // Period of this instance (in clock ticks)
    params.startFlag = Bool false;
    // Start immediately after instance is created
config Clock.arg // instance
index URL

Uninterpreted argument passed to instance function

XDCscript usage meta-domain
var params = new Clock.Params;
...
params.arg = UArg null;
DETAILS
The default is null.
C SYNOPSIS
null
config Clock.period // instance
index URL

Period of this instance (in clock ticks)

XDCscript usage meta-domain
var params = new Clock.Params;
...
params.period = UInt 0;
DETAILS
The default value of this parameter is 0, which indicates this is a one-shot Clock object.
A non zero value for this parameter specifies that the Clock object is to be called periodically, and also specifies the rate (in Clock ticks) that the Clock function will be called AFTER the initial 'timeout' argument period.
For one-shot Clock instances, this parameter must be set to zero.
C SYNOPSIS
null
config Clock.startFlag // instance
index URL

Start immediately after instance is created

XDCscript usage meta-domain
var params = new Clock.Params;
...
params.startFlag = Bool false;
DETAILS
When this flag is set to false, the user will have to call Clock_start() to start the instance.
When set to true, both statically created Clock objects and Clock objects created in main() are started at the end of main() when the user calls BIOS_start(). Dynamically created Clock objects created after main() (ie within a task) will be started immediately.
The default setting for this parameter is false.
The configured Clock function will be called initially after an interval equal to the 'timeout' argument for both one-shot and periodic Clock objects.
Periodic Clock objects will subsequently be called at the rate specified by the period parameter.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Clock.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Clock.create(Void(*)(UArg) clockFxn, UInt timeout, params);
// Create an instance-object
ARGUMENTS
clockFxn — Function that runs upon timeout
timeout — One-shot timeout or initial start delay (in clock ticks)
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
The first argument is the function that gets called when the timeout expires.
The 'timeout' argument is used to specify the initial timeout for both one-shot and periodic Clock instances (in Clock ticks).
The period parameter is used to set the subsequent timeout interval (in Clock ticks) for periodic instances.
For one-shot instances, the period parameter must be set to zero.
When instances are created they are placed upon a linked list managed by the Clock module. For this reason, instances cannot be created from either Hwi or Swi context.
generated on Fri, 17 Jun 2011 00:23:56 GMT


module ti.sysbios.knl.Event
index URL

Event Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
SYS/BIOS events are a means of communication between Tasks and other threads such as Hwis, Swis, and other Tasks, or between Tasks and other SYS/BIOS objects. Other SYS/BIOS objects include semaphores, mailboxes, message queues, etc. Only tasks can wait for events; whereas tasks, Hwis, Swis, or SYS/BIOS objects can post them. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Event.xdc
#include <ti/sysbios/knl/Event.h>
Functions
Void | Event_construct// Initialize a new instance object inside the provided structure(Event_Struct *structP, const Event_Params *params);
Event_Handle | Event_create// Allocate and initialize a new instance object and return its handle(const Event_Params *params, Error_Block *eb);
Void | Event_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Event_Handle *handleP);
Void | Event_destruct// Finalize the instance object inside the provided structure(Event_Struct *structP);
UInt | Event_getPostedEvents// Returns the set of events that have not been consumed by a task (ie those events that have not fully satisfied any pend() conditions). No events are consumed!(Event_Handle handle);
Void | Event_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Event_Params *params);
UInt | Event_pend// Wait for events defined in 'and' OR 'or' masks(Event_Handle handle, UInt andMask, UInt orMask, UInt timeout);
Void | Event_post// Post event(s) to an event object(Event_Handle handle, UInt eventMask);
Functions common to all target instances
 | Event_handle// Convert this instance structure pointer into an instance handle, Event_Handle_label// The label associated with this instance object, Event_Handle_name// The name of this instance object, Event_Object_count// The number of statically-created instance objects, Event_Object_first// The handle of the first dynamically-created instance object, or NULL, Event_Object_get// The handle of the i-th statically-created instance object (array == NULL), Event_Object_heap// The heap used to allocate dynamically-created instance objects, Event_Object_next// The handle of the next dynamically-created instance object, or NULL, Event_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Event_Module_getMask// Returns the diagnostics mask for this module, Event_Module_hasMask// Test whether this module has a diagnostics mask, Event_Module_heap// The heap from which this module allocates memory, Event_Module_id// Get this module's unique id, Event_Module_setMask// Set the diagnostics mask for this module, Event_Module_startupDone// Test if this module has completed startup
Defines
#define | Event_Id_00// Pre-defined Event Ids (UInt)0x1
#define | Event_Id_01// (UInt)0x2
#define | Event_Id_02// (UInt)0x4
#define | Event_Id_03// (UInt)0x8
#define | Event_Id_04// (UInt)0x10
#define | Event_Id_05// (UInt)0x20
#define | Event_Id_06// (UInt)0x40
#define | Event_Id_07// (UInt)0x80
#define | Event_Id_08// (UInt)0x100
#define | Event_Id_09// (UInt)0x200
#define | Event_Id_10// (UInt)0x400
#define | Event_Id_11// (UInt)0x800
#define | Event_Id_12// (UInt)0x1000
#define | Event_Id_13// (UInt)0x2000
#define | Event_Id_14// (UInt)0x4000
#define | Event_Id_15// (UInt)0x8000
#define | Event_Id_16// (UInt)0x10000
#define | Event_Id_17// (UInt)0x20000
#define | Event_Id_18// (UInt)0x40000
#define | Event_Id_19// (UInt)0x80000
#define | Event_Id_20// (UInt)0x100000
#define | Event_Id_21// (UInt)0x200000
#define | Event_Id_22// (UInt)0x400000
#define | Event_Id_23// (UInt)0x800000
#define | Event_Id_24// (UInt)0x1000000
#define | Event_Id_25// (UInt)0x2000000
#define | Event_Id_26// (UInt)0x4000000
#define | Event_Id_27// (UInt)0x8000000
#define | Event_Id_28// (UInt)0x10000000
#define | Event_Id_29// (UInt)0x20000000
#define | Event_Id_30// (UInt)0x40000000
#define | Event_Id_31// (UInt)0x80000000
#define | Event_Id_NONE// (UInt)0
Typedefs
typedef Event_Object * | Event_Handle// Client reference to an instance object;
typedef struct | Event_Object// Opaque internal representation of an instance object Event_Object;
typedef struct | Event_Params// Instance config-params structure ...
typedef struct | Event_Struct// Opaque client structure large enough to hold an instance object Event_Struct;
Constants
extern const Assert_Id | Event_A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context;
extern const Assert_Id | Event_A_eventInUse// Asserted when pend is called by multiple tasks on the same Event object;
extern const Assert_Id | Event_A_nullEventId// Asserted when post is called with eventId == 0;
extern const Assert_Id | Event_A_nullEventMasks// Asserted when pend is called with andMask and orMask == 0;
extern const Log_Event | Event_LM_pend// Logged on calls to Event_pend();
extern const Log_Event | Event_LM_post// Logged on calls to Event_post();
DETAILS
SYS/BIOS events are a means of communication between Tasks and other threads such as Hwis, Swis, and other Tasks, or between Tasks and other SYS/BIOS objects. Other SYS/BIOS objects include semaphores, mailboxes, message queues, etc. Only tasks can wait for events; whereas tasks, Hwis, Swis, or SYS/BIOS objects can post them.
In order for a task to be notified of an event from a SYS/BIOS object an event object must first be registered with that object. Separate APIs are provided (in their respective modules) for each of the SYS/BIOS object types that support this feature.
Events are synchronous in nature, meaning that a receiving task will block or pend while waiting for the events to occur. When the desired events are received, the pending task continues its execution, as it would after a call to Semaphore_pend(), for example.
Tasks can also wait on events that are not linked to other SYS/BIOS objects. These events are explicitly posted from other threads such as tasks, Swis, or Hwis. A task does not register to receive these events; the sending thread simply posts its event(s) to the event object the task is pending on. This scenario is similar to having an ISR post a semaphore.
A task can wait on events from multiple resources and/or threads; thus, it can be waiting for a semaphore to be posted and for a message to arrive in a message queue or an ISR thread to signal that an event has occurred.
Events are binary. Events become available (posted) on each Event_post() of the eventId and become non-available (consumed) on each qualifying Event_pend() mask.
Unlike Semaphores, only a single task can pend on an Event object.
pend is used to wait for events. The andMask & orMask determine which event(s) must occur before returning from pend. The timeout parameter allows the task to wait until a timeout, wait indefinitely, or not wait at all. A return value of zero indicates that a timeout has occurred. A non-zero return value is the set of events that were active at the time the task was unblocked.
The andMask defines a set of events that must ALL occur to allow pend to return.
The orMask defines a set of events that will cause pend to return if ANY of them occur.
All active events present in the orMask are consumed (ie removed from the event object) upon return from pend. Only when all events present in the andMask are active are they consumed on return from pend.
pend returns immediately if the andMask OR orMask conditions are true upon entry.
post is used to signal events. If a task is waiting for the event and all of the event conditions are met, post unblocks the task. If no task is waiting, post simply registers the event with the event object and returns.
The maximum number of eventIds supported is target specific and depends on the number of bits in a UInt data type. For 6x and ARM devices the maximum number of eventIds is therefore 32. For 28x and MSP430 devices, the maximum number of eventIds is 16.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
create | N | N | Y | Y | N
Params_init | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getPostedEvents | Y | Y | Y | Y | Y
pend | N | N | Y | N | N
post | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Event_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Event_Module_startupDone() returns FALSE).
const Event_Id_00
index URL

Pre-defined Event Ids

C synopsis target-domain
#define Event_Id_00 (UInt)0x1
DETAILS
Event_Ids are provided to simplify the specification of andMasks and orMasks arguments to Event_pend().
Since each Event_Id is a bitmask composed of only a single bit, a group of Event_Ids within an andMask or orMask can be indicated by simply adding them together. For instance, to indicate that a task is to be awakened only when both Event_Id_00 and Event_Id_01 have been posted, the andMask for Event_pend() would be constructed as below:
  Event_pend(event, Event_Id_00+EventId_01, Event_Id_NONE,
             BIOS_WAIT_FOREVER);
As shown above, Event_Id_NONE is to be used as an empty (NULL) andMask or orMask.
NOTE
For targets where a UInt is 32 bits in length, Event_Id_00 thru Event_Id_31 can be used.
For targets where a UInt is 16 bits in length, Event_Id_00 thru Event_Id_15 can be used.
const Event_Id_01
index URL
C synopsis target-domain
#define Event_Id_01 (UInt)0x2
SEE
Pre-defined Event IDs.
const Event_Id_02
index URL
C synopsis target-domain
#define Event_Id_02 (UInt)0x4
SEE
Pre-defined Event IDs.
const Event_Id_03
index URL
C synopsis target-domain
#define Event_Id_03 (UInt)0x8
SEE
Pre-defined Event IDs.
const Event_Id_04
index URL
C synopsis target-domain
#define Event_Id_04 (UInt)0x10
SEE
Pre-defined Event IDs.
const Event_Id_05
index URL
C synopsis target-domain
#define Event_Id_05 (UInt)0x20
SEE
Pre-defined Event IDs.
const Event_Id_06
index URL
C synopsis target-domain
#define Event_Id_06 (UInt)0x40
SEE
Pre-defined Event IDs.
const Event_Id_07
index URL
C synopsis target-domain
#define Event_Id_07 (UInt)0x80
SEE
Pre-defined Event IDs.
const Event_Id_08
index URL
C synopsis target-domain
#define Event_Id_08 (UInt)0x100
SEE
Pre-defined Event IDs.
const Event_Id_09
index URL
C synopsis target-domain
#define Event_Id_09 (UInt)0x200
SEE
Pre-defined Event IDs.
const Event_Id_10
index URL
C synopsis target-domain
#define Event_Id_10 (UInt)0x400
SEE
Pre-defined Event IDs.
const Event_Id_11
index URL
C synopsis target-domain
#define Event_Id_11 (UInt)0x800
SEE
Pre-defined Event IDs.
const Event_Id_12
index URL
C synopsis target-domain
#define Event_Id_12 (UInt)0x1000
SEE
Pre-defined Event IDs.
const Event_Id_13
index URL
C synopsis target-domain
#define Event_Id_13 (UInt)0x2000
SEE
Pre-defined Event IDs.
const Event_Id_14
index URL
C synopsis target-domain
#define Event_Id_14 (UInt)0x4000
SEE
Pre-defined Event IDs.
const Event_Id_15
index URL
C synopsis target-domain
#define Event_Id_15 (UInt)0x8000
SEE
Pre-defined Event IDs.
const Event_Id_16
index URL
C synopsis target-domain
#define Event_Id_16 (UInt)0x10000
SEE
Pre-defined Event IDs.
const Event_Id_17
index URL
C synopsis target-domain
#define Event_Id_17 (UInt)0x20000
SEE
Pre-defined Event IDs.
const Event_Id_18
index URL
C synopsis target-domain
#define Event_Id_18 (UInt)0x40000
SEE
Pre-defined Event IDs.
const Event_Id_19
index URL
C synopsis target-domain
#define Event_Id_19 (UInt)0x80000
SEE
Pre-defined Event IDs.
const Event_Id_20
index URL
C synopsis target-domain
#define Event_Id_20 (UInt)0x100000
SEE
Pre-defined Event IDs.
const Event_Id_21
index URL
C synopsis target-domain
#define Event_Id_21 (UInt)0x200000
SEE
Pre-defined Event IDs.
const Event_Id_22
index URL
C synopsis target-domain
#define Event_Id_22 (UInt)0x400000
SEE
Pre-defined Event IDs.
const Event_Id_23
index URL
C synopsis target-domain
#define Event_Id_23 (UInt)0x800000
SEE
Pre-defined Event IDs.
const Event_Id_24
index URL
C synopsis target-domain
#define Event_Id_24 (UInt)0x1000000
SEE
Pre-defined Event IDs.
const Event_Id_25
index URL
C synopsis target-domain
#define Event_Id_25 (UInt)0x2000000
SEE
Pre-defined Event IDs.
const Event_Id_26
index URL
C synopsis target-domain
#define Event_Id_26 (UInt)0x4000000
SEE
Pre-defined Event IDs.
const Event_Id_27
index URL
C synopsis target-domain
#define Event_Id_27 (UInt)0x8000000
SEE
Pre-defined Event IDs.
const Event_Id_28
index URL
C synopsis target-domain
#define Event_Id_28 (UInt)0x10000000
SEE
Pre-defined Event IDs.
const Event_Id_29
index URL
C synopsis target-domain
#define Event_Id_29 (UInt)0x20000000
SEE
Pre-defined Event IDs.
const Event_Id_30
index URL
C synopsis target-domain
#define Event_Id_30 (UInt)0x40000000
SEE
Pre-defined Event IDs.
const Event_Id_31
index URL
C synopsis target-domain
#define Event_Id_31 (UInt)0x80000000
SEE
Pre-defined Event IDs.
const Event_Id_NONE
index URL
C synopsis target-domain
#define Event_Id_NONE (UInt)0
SEE
Pre-defined Event IDs.
config Event_A_badContext // module-wide
index URL

Asserted when pend is called with non-zero timeout from other than a Task context

C synopsis target-domain
extern const Assert_Id Event_A_badContext;
config Event_A_eventInUse // module-wide
index URL

Asserted when pend is called by multiple tasks on the same Event object

C synopsis target-domain
extern const Assert_Id Event_A_eventInUse;
config Event_A_nullEventId // module-wide
index URL

Asserted when post is called with eventId == 0

C synopsis target-domain
extern const Assert_Id Event_A_nullEventId;
config Event_A_nullEventMasks // module-wide
index URL

Asserted when pend is called with andMask and orMask == 0

C synopsis target-domain
extern const Assert_Id Event_A_nullEventMasks;
config Event_LM_pend // module-wide
index URL

Logged on calls to Event_pend()

C synopsis target-domain
extern const Log_Event Event_LM_pend;
config Event_LM_post // module-wide
index URL

Logged on calls to Event_post()

C synopsis target-domain
extern const Log_Event Event_LM_post;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Event_Module_id();
// Get this module's unique id
Bool Event_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Event_Module_heap();
// The heap from which this module allocates memory
Bool Event_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Event_Module_getMask();
// Returns the diagnostics mask for this module
Void Event_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Event_Object Event_Object;
// Opaque internal representation of an instance object
typedef Event_Object *Event_Handle;
// Client reference to an instance object
typedef struct Event_Struct Event_Struct;
// Opaque client structure large enough to hold an instance object
Event_Handle Event_handle(Event_Struct *structP);
// Convert this instance structure pointer into an instance handle
Event_Struct *Event_struct(Event_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Event_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} Event_Params;
Void Event_Params_init(Event_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
Event_Handle Event_create(const Event_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Event_construct(Event_Struct *structP, const Event_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new Event object.
Instance Deletion
index URL

C synopsis target-domain
Void Event_delete(Event_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Event_destruct(Event_Struct *structP);
// Finalize the instance object inside the provided structure
Event_getPostedEvents() // instance
index URL

Returns the set of events that have not been consumed by a task (ie those events that have not fully satisfied any pend() conditions). No events are consumed!

C synopsis target-domain
UInt Event_getPostedEvents(Event_Handle handle);
ARGUMENTS
handle — handle of a previously-created Event instance object
RETURNS
All un-consumed events posted to the event.
Event_pend() // instance
index URL

Wait for events defined in 'and' OR 'or' masks

C synopsis target-domain
UInt Event_pend(Event_Handle handle, UInt andMask, UInt orMask, UInt timeout);
ARGUMENTS
handle — handle of a previously-created Event instance object
andMask — return from pend() when ALL of these events have occurred
orMask — return from pend() when ANY of these events have occurred
timeout — return from pend() after this many system time units
RETURNS
All consumed events or zero if timeout.
DETAILS
pend() is used to wait for events. The andMask and orMask determine which event(s) must occur before returning from pend(). The timeout parameter allows the task to wait until a timeout, wait indefinitely, or not wait at all. A return value of zero indicates that a timeout has occurred. A non-zero return value is the set of events that were active at the time the task was unblocked.
The andMask defines a set of events that must ALL occur to allow pend() to return.
The orMask defines a set of events that will cause pend() to return if ANY of them occur.
All active events present in the orMask are consumed (i.e. removed from the event object) upon return from pend(). Only when all events present in the andMask are active are they consumed on return from pend().
The pend conditions are satisfied when either ALL of the events in the andMask occur or ANY of the events in the orMask occur.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for matching events to be posted.
A timeout value of BIOS_NO_WAIT causes Event_pend to return immediately.
Event_post() // instance
index URL

Post event(s) to an event object

C synopsis target-domain
Void Event_post(Event_Handle handle, UInt eventMask);
ARGUMENTS
handle — handle of a previously-created Event instance object
eventMask — mask of eventIds to post (must be non-zero)
DETAILS
Event_post() is used to signal events. If a task is waiting for the event and the event conditions are met, post() unblocks the task. If no tasks are waiting, post() simply registers the event with the event object and returns.
Instance Built-Ins
index URL

C synopsis target-domain
Int Event_Object_count();
// The number of statically-created instance objects
Event_Handle Event_Object_get(Event_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Event_Handle Event_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Event_Handle Event_Object_next(Event_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Event_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Event_Handle_label(Event_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Event_Handle_name(Event_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Event.xdc
var Event = xdc.useModule('ti.sysbios.knl.Event');
module-wide constants & types
    const Event.Id_00// Pre-defined Event Ids = 0x1;
    const Event.Id_01// = 0x2;
    const Event.Id_02// = 0x4;
    const Event.Id_03// = 0x8;
    const Event.Id_04// = 0x10;
    const Event.Id_05// = 0x20;
    const Event.Id_06// = 0x40;
    const Event.Id_07// = 0x80;
    const Event.Id_08// = 0x100;
    const Event.Id_09// = 0x200;
    const Event.Id_10// = 0x400;
    const Event.Id_11// = 0x800;
    const Event.Id_12// = 0x1000;
    const Event.Id_13// = 0x2000;
    const Event.Id_14// = 0x4000;
    const Event.Id_15// = 0x8000;
    const Event.Id_16// = 0x10000;
    const Event.Id_17// = 0x20000;
    const Event.Id_18// = 0x40000;
    const Event.Id_19// = 0x80000;
    const Event.Id_20// = 0x100000;
    const Event.Id_21// = 0x200000;
    const Event.Id_22// = 0x400000;
    const Event.Id_23// = 0x800000;
    const Event.Id_24// = 0x1000000;
    const Event.Id_25// = 0x2000000;
    const Event.Id_26// = 0x4000000;
    const Event.Id_27// = 0x8000000;
    const Event.Id_28// = 0x10000000;
    const Event.Id_29// = 0x20000000;
    const Event.Id_30// = 0x40000000;
    const Event.Id_31// = 0x80000000;
    const Event.Id_NONE// = 0;
module-wide config parameters
     Event.A_badContext// Asserted when pend is called with non-zero timeout from other than a Task context = Assert.Desc {
        msg: "A_badContext: bad calling context. Must be called from a Task."
    };
     Event.A_eventInUse// Asserted when pend is called by multiple tasks on the same Event object = Assert.Desc {
        msg: "A_eventInUse: Event object already in use."
    };
     Event.A_nullEventId// Asserted when post is called with eventId == 0 = Assert.Desc {
        msg: "A_nullEventId: posted eventId is null."
    };
     Event.A_nullEventMasks// Asserted when pend is called with andMask and orMask == 0 = Assert.Desc {
        msg: "A_nullEventMasks: orMask and andMask are null."
    };
     Event.LM_pend// Logged on calls to Event_pend() = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_pend: event: 0x%x, currEvents: 0x%x, andMask: 0x%x, orMask: 0x%x, timeout: %d"
    };
     Event.LM_post// Logged on calls to Event_post() = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_post: event: 0x%x, currEvents: 0x%x, eventId: 0x%x"
    };
     Event.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Event.Params// Instance config-params object;
per-instance creation
    var inst = Event.create// Create an instance-object(params);
const Event.Id_00
index URL

Pre-defined Event Ids

XDCscript usage meta-domain
const Event.Id_00 = 0x1;
DETAILS
Event_Ids are provided to simplify the specification of andMasks and orMasks arguments to Event_pend().
Since each Event_Id is a bitmask composed of only a single bit, a group of Event_Ids within an andMask or orMask can be indicated by simply adding them together. For instance, to indicate that a task is to be awakened only when both Event_Id_00 and Event_Id_01 have been posted, the andMask for Event_pend() would be constructed as below:
  Event_pend(event, Event_Id_00+EventId_01, Event_Id_NONE,
             BIOS_WAIT_FOREVER);
As shown above, Event_Id_NONE is to be used as an empty (NULL) andMask or orMask.
NOTE
For targets where a UInt is 32 bits in length, Event_Id_00 thru Event_Id_31 can be used.
For targets where a UInt is 16 bits in length, Event_Id_00 thru Event_Id_15 can be used.
C SYNOPSIS
Event_Id_00
const Event.Id_01
index URL
XDCscript usage meta-domain
const Event.Id_01 = 0x2;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_01
const Event.Id_02
index URL
XDCscript usage meta-domain
const Event.Id_02 = 0x4;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_02
const Event.Id_03
index URL
XDCscript usage meta-domain
const Event.Id_03 = 0x8;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_03
const Event.Id_04
index URL
XDCscript usage meta-domain
const Event.Id_04 = 0x10;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_04
const Event.Id_05
index URL
XDCscript usage meta-domain
const Event.Id_05 = 0x20;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_05
const Event.Id_06
index URL
XDCscript usage meta-domain
const Event.Id_06 = 0x40;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_06
const Event.Id_07
index URL
XDCscript usage meta-domain
const Event.Id_07 = 0x80;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_07
const Event.Id_08
index URL
XDCscript usage meta-domain
const Event.Id_08 = 0x100;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_08
const Event.Id_09
index URL
XDCscript usage meta-domain
const Event.Id_09 = 0x200;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_09
const Event.Id_10
index URL
XDCscript usage meta-domain
const Event.Id_10 = 0x400;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_10
const Event.Id_11
index URL
XDCscript usage meta-domain
const Event.Id_11 = 0x800;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_11
const Event.Id_12
index URL
XDCscript usage meta-domain
const Event.Id_12 = 0x1000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_12
const Event.Id_13
index URL
XDCscript usage meta-domain
const Event.Id_13 = 0x2000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_13
const Event.Id_14
index URL
XDCscript usage meta-domain
const Event.Id_14 = 0x4000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_14
const Event.Id_15
index URL
XDCscript usage meta-domain
const Event.Id_15 = 0x8000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_15
const Event.Id_16
index URL
XDCscript usage meta-domain
const Event.Id_16 = 0x10000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_16
const Event.Id_17
index URL
XDCscript usage meta-domain
const Event.Id_17 = 0x20000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_17
const Event.Id_18
index URL
XDCscript usage meta-domain
const Event.Id_18 = 0x40000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_18
const Event.Id_19
index URL
XDCscript usage meta-domain
const Event.Id_19 = 0x80000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_19
const Event.Id_20
index URL
XDCscript usage meta-domain
const Event.Id_20 = 0x100000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_20
const Event.Id_21
index URL
XDCscript usage meta-domain
const Event.Id_21 = 0x200000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_21
const Event.Id_22
index URL
XDCscript usage meta-domain
const Event.Id_22 = 0x400000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_22
const Event.Id_23
index URL
XDCscript usage meta-domain
const Event.Id_23 = 0x800000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_23
const Event.Id_24
index URL
XDCscript usage meta-domain
const Event.Id_24 = 0x1000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_24
const Event.Id_25
index URL
XDCscript usage meta-domain
const Event.Id_25 = 0x2000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_25
const Event.Id_26
index URL
XDCscript usage meta-domain
const Event.Id_26 = 0x4000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_26
const Event.Id_27
index URL
XDCscript usage meta-domain
const Event.Id_27 = 0x8000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_27
const Event.Id_28
index URL
XDCscript usage meta-domain
const Event.Id_28 = 0x10000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_28
const Event.Id_29
index URL
XDCscript usage meta-domain
const Event.Id_29 = 0x20000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_29
const Event.Id_30
index URL
XDCscript usage meta-domain
const Event.Id_30 = 0x40000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_30
const Event.Id_31
index URL
XDCscript usage meta-domain
const Event.Id_31 = 0x80000000;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_31
const Event.Id_NONE
index URL
XDCscript usage meta-domain
const Event.Id_NONE = 0;
SEE
Pre-defined Event IDs.
C SYNOPSIS
Event_Id_NONE
config Event.A_badContext // module-wide
index URL

Asserted when pend is called with non-zero timeout from other than a Task context

XDCscript usage meta-domain
Event.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. Must be called from a Task."
};
C SYNOPSIS
Event_A_badContext
config Event.A_eventInUse // module-wide
index URL

Asserted when pend is called by multiple tasks on the same Event object

XDCscript usage meta-domain
Event.A_eventInUse = Assert.Desc {
    msg: "A_eventInUse: Event object already in use."
};
C SYNOPSIS
Event_A_eventInUse
config Event.A_nullEventId // module-wide
index URL

Asserted when post is called with eventId == 0

XDCscript usage meta-domain
Event.A_nullEventId = Assert.Desc {
    msg: "A_nullEventId: posted eventId is null."
};
C SYNOPSIS
Event_A_nullEventId
config Event.A_nullEventMasks // module-wide
index URL

Asserted when pend is called with andMask and orMask == 0

XDCscript usage meta-domain
Event.A_nullEventMasks = Assert.Desc {
    msg: "A_nullEventMasks: orMask and andMask are null."
};
C SYNOPSIS
Event_A_nullEventMasks
config Event.LM_pend // module-wide
index URL

Logged on calls to Event_pend()

XDCscript usage meta-domain
Event.LM_pend = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_pend: event: 0x%x, currEvents: 0x%x, andMask: 0x%x, orMask: 0x%x, timeout: %d"
};
C SYNOPSIS
Event_LM_pend
config Event.LM_post // module-wide
index URL

Logged on calls to Event_post()

XDCscript usage meta-domain
Event.LM_post = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_post: event: 0x%x, currEvents: 0x%x, eventId: 0x%x"
};
C SYNOPSIS
Event_LM_post
metaonly config Event.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Event.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Event.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Event.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Event.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new Event object.
generated on Fri, 17 Jun 2011 00:23:56 GMT


module ti.sysbios.knl.Idle
index URL

Idle Thread Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Idle module is used to specify the list of functions to be called when no other tasks are running in the system. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Idle.xdc
#include <ti/sysbios/knl/Idle.h>
Functions
Void | Idle_run// Make one pass through idle functions();
Functions common to all target modules
 | Idle_Module_getMask// Returns the diagnostics mask for this module, Idle_Module_hasMask// Test whether this module has a diagnostics mask, Idle_Module_heap// The heap from which this module allocates memory, Idle_Module_id// Get this module's unique id, Idle_Module_setMask// Set the diagnostics mask for this module, Idle_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Idle_FuncPtr// Idle function type definition)();
DETAILS
The Idle module is used to specify the list of functions to be called when no other tasks are running in the system.
If tasking is enabled, then the Task module will create an "Idle task" with the lowest possible priority. When no other tasks are running, this idle task runs in an infinite loop, calling the list of functions specified by the Idle module.
If tasking is disabled, then the idle functions are called in an infinite loop after main and any Module startup functions.
The list of idle functions is only statically configurable; it cannot be modified at runtime.
typedef Idle_FuncPtr
index URL

Idle function type definition

C synopsis target-domain
typedef Void (*Idle_FuncPtr)();
Idle_run() // module-wide
index URL

Make one pass through idle functions

C synopsis target-domain
Void Idle_run();
DETAILS
This function is called internally by the Idle task when the Idle task has been enabled in the Task module (see Task.enableIdleTask).
This function makes one pass through the array of functions defined in the Idle.funcList, calling one function after the next. This function returns after all functions have been executed one time.
SEE
Task.enableIdleTask, Task.allBlockedFunc
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Idle_Module_id();
// Get this module's unique id
Bool Idle_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Idle_Module_heap();
// The heap from which this module allocates memory
Bool Idle_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Idle_Module_getMask();
// Returns the diagnostics mask for this module
Void Idle_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/knl/Idle.xdc
var Idle = xdc.useModule('ti.sysbios.knl.Idle');
module-wide constants & types
    var obj = new Idle.ModuleView// ;
        obj.index = UInt ...
        obj.fxn = String ...
module-wide config parameters
     Idle.common$// Common module configuration parameters = Types.Common$ undefined;
     Idle.idleFxns// Functions to be called when no other Tasks are running = Idle.FuncPtr[length] [
        null,
        null,
        null,
        null,
        null,
        null,
        null,
        null
    ];
module-wide functions
     Idle.addFunc// Statically add a function to the Idle function list(Void(*)() func) returns Void
metaonly struct Idle.ModuleView
index URL
XDCscript usage meta-domain
var obj = new Idle.ModuleView;
    obj.index = UInt ...
    obj.fxn = String ...
metaonly config Idle.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Idle.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Idle.idleFxns // module-wide
index URL

Functions to be called when no other Tasks are running

XDCscript usage meta-domain
Idle.idleFxns = Idle.FuncPtr[length] [
    null,
    null,
    null,
    null,
    null,
    null,
    null,
    null
];
DETAILS
Functions added to this array are added to the list of functions called by the Idle loop which repeatedly calls @{link #run Idle_run}.
It is also possible to use @{link #addFunc Idle.addFunc()} to add an idle function. Both the functions added to idleFxns and those added via Idle.addFunc() will be run by the target's Idle loop.
metaonly Idle.addFunc() // module-wide
index URL

Statically add a function to the Idle function list

XDCscript usage meta-domain
Idle.addFunc(Void(*)() func) returns Void
generated on Fri, 17 Jun 2011 00:23:56 GMT


module ti.sysbios.knl.Mailbox
index URL

Mailbox Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Mailbox module makes available a set of functions that manipulate mailbox objects accessed through handles of type Mailbox_Handle. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Mailbox.xdc
#include <ti/sysbios/knl/Mailbox.h>
Functions
Void | Mailbox_construct// Initialize a new instance object inside the provided structure(Mailbox_Struct *structP, SizeT msgSize, UInt numMsgs, const Mailbox_Params *params, Error_Block *eb);
Mailbox_Handle | Mailbox_create// Allocate and initialize a new instance object and return its handle(SizeT msgSize, UInt numMsgs, const Mailbox_Params *params, Error_Block *eb);
Void | Mailbox_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Mailbox_Handle *handleP);
Void | Mailbox_destruct// Finalize the instance object inside the provided structure(Mailbox_Struct *structP);
Int | Mailbox_getNumFreeMsgs// Get the number messages available for use(Mailbox_Handle handle);
Int | Mailbox_getNumPendingMsgs// Get the number of messages that are ready to be read(Mailbox_Handle handle);
Void | Mailbox_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Mailbox_Params *params);
Bool | Mailbox_pend// Wait for a message from mailbox(Mailbox_Handle handle, Ptr msg, UInt timeout);
Bool | Mailbox_post// Post a message to mailbox(Mailbox_Handle handle, Ptr msg, UInt timeout);
Functions common to all target instances
 | Mailbox_handle// Convert this instance structure pointer into an instance handle, Mailbox_Handle_label// The label associated with this instance object, Mailbox_Handle_name// The name of this instance object, Mailbox_Object_count// The number of statically-created instance objects, Mailbox_Object_first// The handle of the first dynamically-created instance object, or NULL, Mailbox_Object_get// The handle of the i-th statically-created instance object (array == NULL), Mailbox_Object_heap// The heap used to allocate dynamically-created instance objects, Mailbox_Object_next// The handle of the next dynamically-created instance object, or NULL, Mailbox_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Mailbox_Module_getMask// Returns the diagnostics mask for this module, Mailbox_Module_hasMask// Test whether this module has a diagnostics mask, Mailbox_Module_heap// The heap from which this module allocates memory, Mailbox_Module_id// Get this module's unique id, Mailbox_Module_setMask// Set the diagnostics mask for this module, Mailbox_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Mailbox_Object * | Mailbox_Handle// Client reference to an instance object;
typedef struct | Mailbox_MbxElem// The header used to save each Mailbox message ...
typedef struct | Mailbox_Object// Opaque internal representation of an instance object Mailbox_Object;
typedef struct | Mailbox_Params// Instance config-params structure ...
typedef struct | Mailbox_Struct// Opaque client structure large enough to hold an instance object Mailbox_Struct;
Constants
extern const Assert_Id | Mailbox_A_invalidBufSize// Assert raised when the bufSize parameter is too small;
DETAILS
The Mailbox module makes available a set of functions that manipulate mailbox objects accessed through handles of type Mailbox_Handle.
pend() is used to wait for a message from a mailbox. The timeout parameter to Mailbox_pend allows the task to wait until a timeout specified in terms of system clock ticks. A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message. A timeout value of BIOS_NO_WAIT causes Mailbox_pend to return immediately. Mailbox_pend's return value indicates whether the mailbox was signaled successfully.
When a Mailbox has been configured with a readerEvent Event object and a task has returned from Event.pend() with the corresponding readerEventId, then BIOS_NO_WAIT should be passed to Mailbox_pend() to retrieve the message.
NOTE: Since only a single reader can pend on a readerEvent Event object, a Mailbox configured with a readerEvent Event object does not support multiple readers.
post() is used to send a message to a mailbox. The timeout parameter to Mailbox_post specifies the amount of time the calling task waits if the mailbox is full.
When a Mailbox has been configured with a writerEvent Event object and a task has returned from Event.pend() with the corresponding writerEventId, then BIOS_NO_WAIT should be passed to Mailbox_post() knowing that the message will be successfully posted.
NOTE: Since only a single writer can pend on a writerEvent Event object, a Mailbox configured with a writerEvent Event object does not support multiple writers.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getNumFreeMsgs | Y | Y | Y | N | N
getNumPendingMsgs | Y | Y | Y | N | N
pend | Y* | Y* | Y | N | N
post | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Mailbox_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Mailbox_Module_startupDone() returns FALSE).
  • *: Yes but only for a timeout value of zero.
struct Mailbox_MbxElem
index URL

The header used to save each Mailbox message

C synopsis target-domain
typedef struct Mailbox_MbxElem {
     Queue_Elem elem;
} Mailbox_MbxElem;
DETAILS
Mailbox messages are stored in a queue that requires a header in front of each message. This structure defines that header and its size must be factored into the total data size requirements for a mailbox instance.
config Mailbox_A_invalidBufSize // module-wide
index URL

Assert raised when the bufSize parameter is too small

C synopsis target-domain
extern const Assert_Id Mailbox_A_invalidBufSize;
DETAILS
This assert is raised when bufSize is too small to handle (size of messages + sizeof(MbxElem)) * number of messages. See ti.sysbios.knl.MailBox.buf for more information on the buf parameter.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Mailbox_Module_id();
// Get this module's unique id
Bool Mailbox_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Mailbox_Module_heap();
// The heap from which this module allocates memory
Bool Mailbox_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Mailbox_Module_getMask();
// Returns the diagnostics mask for this module
Void Mailbox_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Mailbox_Object Mailbox_Object;
// Opaque internal representation of an instance object
typedef Mailbox_Object *Mailbox_Handle;
// Client reference to an instance object
typedef struct Mailbox_Struct Mailbox_Struct;
// Opaque client structure large enough to hold an instance object
Mailbox_Handle Mailbox_handle(Mailbox_Struct *structP);
// Convert this instance structure pointer into an instance handle
Mailbox_Struct *Mailbox_struct(Mailbox_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Mailbox_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Ptr buf;
    // The address of the buffer used for creating messages
    UInt bufSize;
    // The size of the buffer that 'buf' references
     IHeap_Handle heap;
    // The IHeap instance used for dynamic creates
     Event_Handle readerEvent;
    // Mailbox not empty event if using Events. Default is null
    UInt readerEventId;
    // Mailbox not empty event Id if using Events. Default is 1
     Event_Handle writerEvent;
    // Mailbox not full event if using Events. Default is null
    UInt writerEventId;
    // Mailbox not full event Id if using Events
} Mailbox_Params;
Void Mailbox_Params_init(Mailbox_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Mailbox_buf // instance
index URL

The address of the buffer used for creating messages

C synopsis target-domain
struct Mailbox_Params {
     ...
    Ptr buf;
DETAILS
This property is only used for dynamically created Mailboxes. If set to 'null', the messages will be allocated from the heap during runtime, otherwise the user may set this to a buffer of their creation to be used for allocating the messages.
The module will split the buf into ti.sysbios.knl.Mailbox.numMsgs number of blocks (one block per Mailbox message).
Please note that if the buffer is user supplied, then it is the user's responsibility to ensure that it is aligned properly and is also large enough to contain ti.sysbios.knl.Mailbox.numMsgs number of blocks. The size of each block is defined as follows:
      sizeof(Mailbox_MbxElem) + msgSize
Since the buffer must be a aligned properly, it may be necessary to 'round up' the total size of the buffer to the next multiple of the alignment for odd sized messages.
SEE
MbxElem
config Mailbox_bufSize // instance
index URL

The size of the buffer that 'buf' references

C synopsis target-domain
struct Mailbox_Params {
     ...
    UInt bufSize;
DETAILS
This property is only used for dynamically created Mailboxes.
config Mailbox_heap // instance
index URL

The IHeap instance used for dynamic creates

C synopsis target-domain
struct Mailbox_Params {
     ...
     IHeap_Handle heap;
DETAILS
This heap is used only for dynamic instances is ignored for static instances.
config Mailbox_readerEvent // instance
index URL

Mailbox not empty event if using Events. Default is null

C synopsis target-domain
struct Mailbox_Params {
     ...
     Event_Handle readerEvent;
DETAILS
Posted whenever a mailbox is written to. Reader task pends on this event. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
config Mailbox_readerEventId // instance
index URL

Mailbox not empty event Id if using Events. Default is 1

C synopsis target-domain
struct Mailbox_Params {
     ...
    UInt readerEventId;
DETAILS
Posted whenever a mailbox is written to. Reader task pends on this eventId. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
config Mailbox_writerEvent // instance
index URL

Mailbox not full event if using Events. Default is null

C synopsis target-domain
struct Mailbox_Params {
     ...
     Event_Handle writerEvent;
DETAILS
Posted whenever a mailbox is read from. Writer task pends on this event. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
config Mailbox_writerEventId // instance
index URL

Mailbox not full event Id if using Events

C synopsis target-domain
struct Mailbox_Params {
     ...
    UInt writerEventId;
DETAILS
Posted whenever a mailbox is read from. Writer task pends on this eventId. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
Instance Creation
index URL

C synopsis target-domain
Mailbox_Handle Mailbox_create(SizeT msgSize, UInt numMsgs, const Mailbox_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Mailbox_construct(Mailbox_Struct *structP, SizeT msgSize, UInt numMsgs, const Mailbox_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
msgSize — size of message
numMsgs — length of mailbox
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Mailbox_create creates a mailbox object which is initialized to contain numMsgs messages of size msgSize.
Instance Deletion
index URL

C synopsis target-domain
Void Mailbox_delete(Mailbox_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Mailbox_destruct(Mailbox_Struct *structP);
// Finalize the instance object inside the provided structure
Mailbox_getNumFreeMsgs() // instance
index URL

Get the number messages available for use

C synopsis target-domain
Int Mailbox_getNumFreeMsgs(Mailbox_Handle handle);
ARGUMENTS
handle — handle of a previously-created Mailbox instance object
Mailbox_getNumPendingMsgs() // instance
index URL

Get the number of messages that are ready to be read

C synopsis target-domain
Int Mailbox_getNumPendingMsgs(Mailbox_Handle handle);
ARGUMENTS
handle — handle of a previously-created Mailbox instance object
Mailbox_pend() // instance
index URL

Wait for a message from mailbox

C synopsis target-domain
Bool Mailbox_pend(Mailbox_Handle handle, Ptr msg, UInt timeout);
ARGUMENTS
handle — handle of a previously-created Mailbox instance object
msg — message pointer
timeout — maximum duration in system clock ticks
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
If the mailbox is not empty, Mailbox_pend copies the first message into msg and returns TRUE. Otherwise, Mailbox_pend suspends the execution of the current task until Mailbox_post is called or the timeout expires.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a message.
A timeout value of BIOS_NO_WAIT causes Mailbox_pend to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_pend() to retrieve a message after Event_pend() is called outside of Mailbox_pend to wait on an incoming message.
Mailbox_pend's return value indicates whether the mailbox was signaled successfully.
Mailbox_post() // instance
index URL

Post a message to mailbox

C synopsis target-domain
Bool Mailbox_post(Mailbox_Handle handle, Ptr msg, UInt timeout);
ARGUMENTS
handle — handle of a previously-created Mailbox instance object
msg — message pointer
timeout — maximum duration in system clock ticks
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
Mailbox_post checks to see if there are any free message slots before copying msg into the mailbox. Mailbox_post readies the first task (if any) waiting on the mailbox. If the mailbox is full and a timeout is specified the task remains suspended until Mailbox_pend is called or the timeout expires.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for a free slot.
A timeout value of BIOS_NO_WAIT causes Mailbox_post to return immediately.
The timeout value of BIOS_NO_WAIT should be passed to Mailbox_post() to post a message after Event_pend() is called outside of Mailbox_post to wait on an available message buffer.
Mailbox_post's return value indicates whether the msg was copied or not.
Instance Built-Ins
index URL

C synopsis target-domain
Int Mailbox_Object_count();
// The number of statically-created instance objects
Mailbox_Handle Mailbox_Object_get(Mailbox_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Mailbox_Handle Mailbox_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Mailbox_Handle Mailbox_Object_next(Mailbox_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Mailbox_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Mailbox_Handle_label(Mailbox_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Mailbox_Handle_name(Mailbox_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Mailbox.xdc
var Mailbox = xdc.useModule('ti.sysbios.knl.Mailbox');
module-wide constants & types
    var obj = new Mailbox.MbxElem// The header used to save each Mailbox message;
        obj.elem = Queue.Elem ...
module-wide config parameters
     Mailbox.A_invalidBufSize// Assert raised when the bufSize parameter is too small = Assert.Desc {
        msg: "Mailbox_create's bufSize parameter is invalid (too small)"
    };
     Mailbox.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Mailbox.Params// Instance config-params object;
        params.buf// The address of the buffer used for creating messages = Ptr null;
        params.bufSize// The size of the buffer that 'buf' references = UInt 0;
        params.heap// The IHeap instance used for dynamic creates = IHeap.Handle null;
        params.readerEvent// Mailbox not empty event if using Events. Default is null = Event.Handle null;
        params.readerEventId// Mailbox not empty event Id if using Events. Default is 1 = UInt 1;
        params.sectionName// Section name for the buffer managed by the instance = String null;
        params.writerEvent// Mailbox not full event if using Events. Default is null = Event.Handle null;
        params.writerEventId// Mailbox not full event Id if using Events = UInt 1;
per-instance creation
    var inst = Mailbox.create// Create an instance-object(SizeT msgSize, UInt numMsgs, params);
struct Mailbox.MbxElem
index URL

The header used to save each Mailbox message

XDCscript usage meta-domain
var obj = new Mailbox.MbxElem;
    obj.elem = Queue.Elem ...
DETAILS
Mailbox messages are stored in a queue that requires a header in front of each message. This structure defines that header and its size must be factored into the total data size requirements for a mailbox instance.
C SYNOPSIS
Mailbox_MbxElem
config Mailbox.A_invalidBufSize // module-wide
index URL

Assert raised when the bufSize parameter is too small

XDCscript usage meta-domain
Mailbox.A_invalidBufSize = Assert.Desc {
    msg: "Mailbox_create's bufSize parameter is invalid (too small)"
};
DETAILS
This assert is raised when bufSize is too small to handle (size of messages + sizeof(MbxElem)) * number of messages. See ti.sysbios.knl.MailBox.buf for more information on the buf parameter.
C SYNOPSIS
Mailbox_A_invalidBufSize
metaonly config Mailbox.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Mailbox.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Mailbox.Params;
// Instance config-params object
    params.buf = Ptr null;
    // The address of the buffer used for creating messages
    params.bufSize = UInt 0;
    // The size of the buffer that 'buf' references
    params.heap = IHeap.Handle null;
    // The IHeap instance used for dynamic creates
    params.readerEvent = Event.Handle null;
    // Mailbox not empty event if using Events. Default is null
    params.readerEventId = UInt 1;
    // Mailbox not empty event Id if using Events. Default is 1
    params.sectionName = String null;
    // Section name for the buffer managed by the instance
    params.writerEvent = Event.Handle null;
    // Mailbox not full event if using Events. Default is null
    params.writerEventId = UInt 1;
    // Mailbox not full event Id if using Events
config Mailbox.buf // instance
index URL

The address of the buffer used for creating messages

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.buf = Ptr null;
DETAILS
This property is only used for dynamically created Mailboxes. If set to 'null', the messages will be allocated from the heap during runtime, otherwise the user may set this to a buffer of their creation to be used for allocating the messages.
The module will split the buf into ti.sysbios.knl.Mailbox.numMsgs number of blocks (one block per Mailbox message).
Please note that if the buffer is user supplied, then it is the user's responsibility to ensure that it is aligned properly and is also large enough to contain ti.sysbios.knl.Mailbox.numMsgs number of blocks. The size of each block is defined as follows:
      sizeof(Mailbox_MbxElem) + msgSize
Since the buffer must be a aligned properly, it may be necessary to 'round up' the total size of the buffer to the next multiple of the alignment for odd sized messages.
SEE
MbxElem
C SYNOPSIS
null
config Mailbox.bufSize // instance
index URL

The size of the buffer that 'buf' references

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.bufSize = UInt 0;
DETAILS
This property is only used for dynamically created Mailboxes.
C SYNOPSIS
null
config Mailbox.heap // instance
index URL

The IHeap instance used for dynamic creates

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.heap = IHeap.Handle null;
DETAILS
This heap is used only for dynamic instances is ignored for static instances.
C SYNOPSIS
null
config Mailbox.readerEvent // instance
index URL

Mailbox not empty event if using Events. Default is null

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.readerEvent = Event.Handle null;
DETAILS
Posted whenever a mailbox is written to. Reader task pends on this event. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
C SYNOPSIS
null
config Mailbox.readerEventId // instance
index URL

Mailbox not empty event Id if using Events. Default is 1

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.readerEventId = UInt 1;
DETAILS
Posted whenever a mailbox is written to. Reader task pends on this eventId. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
C SYNOPSIS
null
config Mailbox.writerEvent // instance
index URL

Mailbox not full event if using Events. Default is null

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.writerEvent = Event.Handle null;
DETAILS
Posted whenever a mailbox is read from. Writer task pends on this event. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
C SYNOPSIS
null
config Mailbox.writerEventId // instance
index URL

Mailbox not full event Id if using Events

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.writerEventId = UInt 1;
DETAILS
Posted whenever a mailbox is read from. Writer task pends on this eventId. Note that Semaphore.supportsEvents has to be set to true for Mailbox to support Events.
C SYNOPSIS
null
metaonly config Mailbox.sectionName // instance
index URL

Section name for the buffer managed by the instance

XDCscript usage meta-domain
var params = new Mailbox.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Mailbox.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Mailbox.create(SizeT msgSize, UInt numMsgs, params);
// Create an instance-object
ARGUMENTS
msgSize — size of message
numMsgs — length of mailbox
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Mailbox_create creates a mailbox object which is initialized to contain numMsgs messages of size msgSize.
generated on Fri, 17 Jun 2011 00:23:57 GMT


module ti.sysbios.knl.Semaphore
index URL

Semaphore Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Semaphore manager makes available a set of functions that manipulate semaphore objects. Semaphores can be used for task synchronization and mutual exclusion. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Semaphore.xdc
#include <ti/sysbios/knl/Semaphore.h>
Functions
Void | Semaphore_construct// Initialize a new instance object inside the provided structure(Semaphore_Struct *structP, Int count, const Semaphore_Params *params);
Semaphore_Handle | Semaphore_create// Allocate and initialize a new instance object and return its handle(Int count, const Semaphore_Params *params, Error_Block *eb);
Void | Semaphore_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Semaphore_Handle *handleP);
Void | Semaphore_destruct// Finalize the instance object inside the provided structure(Semaphore_Struct *structP);
Int | Semaphore_getCount// Get current semaphore count(Semaphore_Handle handle);
Void | Semaphore_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Semaphore_Params *params);
Bool | Semaphore_pend// Wait for a semaphore(Semaphore_Handle handle, UInt timeout);
Void | Semaphore_post// Signal a semaphore(Semaphore_Handle handle);
Void | Semaphore_registerEvent// Register an Event Object with a semaphore(Semaphore_Handle handle, Event_Handle event, UInt eventId);
Void | Semaphore_reset// Reset semaphore count(Semaphore_Handle handle, Int count);
Functions common to all target instances
 | Semaphore_handle// Convert this instance structure pointer into an instance handle, Semaphore_Handle_label// The label associated with this instance object, Semaphore_Handle_name// The name of this instance object, Semaphore_Object_count// The number of statically-created instance objects, Semaphore_Object_first// The handle of the first dynamically-created instance object, or NULL, Semaphore_Object_get// The handle of the i-th statically-created instance object (array == NULL), Semaphore_Object_heap// The heap used to allocate dynamically-created instance objects, Semaphore_Object_next// The handle of the next dynamically-created instance object, or NULL, Semaphore_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Semaphore_Module_getMask// Returns the diagnostics mask for this module, Semaphore_Module_hasMask// Test whether this module has a diagnostics mask, Semaphore_Module_heap// The heap from which this module allocates memory, Semaphore_Module_id// Get this module's unique id, Semaphore_Module_setMask// Set the diagnostics mask for this module, Semaphore_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Semaphore_Object * | Semaphore_Handle// Client reference to an instance object;
typedef enum | Semaphore_Mode// Types of semaphores ...
typedef struct | Semaphore_Object// Opaque internal representation of an instance object Semaphore_Object;
typedef struct | Semaphore_Params// Instance config-params structure ...
typedef struct | Semaphore_Struct// Opaque client structure large enough to hold an instance object Semaphore_Struct;
Constants
extern const Assert_Id | Semaphore_A_badContext// Assert raised if an operation is invalid in the current calling context;
extern const Assert_Id | Semaphore_A_noEvents// Assert raised if application uses Event but it's not supported;
extern const Log_Event | Semaphore_LM_pend// Logged on calls to Semaphore_pend();
extern const Log_Event | Semaphore_LM_post// Logged on calls to Semaphore_post();
extern const Bool | Semaphore_supportsEvents// Support Semaphores with Events?;
DETAILS
The Semaphore manager makes available a set of functions that manipulate semaphore objects. Semaphores can be used for task synchronization and mutual exclusion.
Semaphores can be counting semaphores or binary semaphores. Counting semaphores keep track of the number of times the semaphore has been posted with post(). This is useful, for example, if you have a group of resources that are shared between tasks. Such tasks might call pend() to see if a resource is available before using one.
Binary semaphores can have only two states: available (count = 1) and unavailable (count = 0). They can be used to share a single resource between tasks. They can also be used for a basic signaling mechanism, where the semaphore can be posted multiple times. Binary semaphores do not keep track of the count; they simply track whether the semaphore has been posted or not.
The Mailbox module uses a counting semaphore internally to manage the count of free (or full) mailbox elements. Another example of a counting semaphore is an ISR that might fill multiple buffers of data for consumption by a task. After filling each buffer, the ISR puts the buffer on a queue and calls post(). The task waiting for the data calls pend(), which simply decrements the semaphore count and returns or blocks if the count is 0. The semaphore count thus tracks the number of full buffers available for the task.
pend() is used to wait for a semaphore. The timeout parameter allows the task to wait until a timeout, wait indefinitely, or not wait at all. The return value is used to indicate if the semaphore was signaled successfully.
post() is used to signal a semaphore. If a task is waiting for the semaphore, post() removes the task from the semaphore queue and puts it on the ready queue. If no tasks are waiting, post() simply increments the semaphore count and returns. For a binary semaphore the count is always set to one.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
Params_init | Y | Y | Y | Y | Y
construct | N | N | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getCount | Y | Y | Y | Y | Y
pend | N | N | Y | N | N
post | Y | Y | Y | Y | N
registerEvent | N | N | Y | Y | Y
reset | N | N | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Semaphore_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Semaphore_Module_startupDone() returns FALSE).
enum Semaphore_Mode
index URL

Types of semaphores

C synopsis target-domain
typedef enum Semaphore_Mode {
    Semaphore_Mode_COUNTING,
    // Counting semaphore
    Semaphore_Mode_BINARY
    // Binary Semaphore
} Semaphore_Mode;
config Semaphore_A_badContext // module-wide
index URL

Assert raised if an operation is invalid in the current calling context

C synopsis target-domain
extern const Assert_Id Semaphore_A_badContext;
DETAILS
Asserted when pend is called with non-zero timeout from other than a Task context.
config Semaphore_A_noEvents // module-wide
index URL

Assert raised if application uses Event but it's not supported

C synopsis target-domain
extern const Assert_Id Semaphore_A_noEvents;
DETAILS
This assertion is triggered by create if supportsEvents is false and an ti.sysbios.knl.Event object is passed to create.
config Semaphore_LM_pend // module-wide
index URL

Logged on calls to Semaphore_pend()

C synopsis target-domain
extern const Log_Event Semaphore_LM_pend;
config Semaphore_LM_post // module-wide
index URL

Logged on calls to Semaphore_post()

C synopsis target-domain
extern const Log_Event Semaphore_LM_post;
config Semaphore_supportsEvents // module-wide
index URL

Support Semaphores with Events?

C synopsis target-domain
extern const Bool Semaphore_supportsEvents;
DETAILS
The default for this parameter is false.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Semaphore_Module_id();
// Get this module's unique id
Bool Semaphore_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Semaphore_Module_heap();
// The heap from which this module allocates memory
Bool Semaphore_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Semaphore_Module_getMask();
// Returns the diagnostics mask for this module
Void Semaphore_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Semaphore_Object Semaphore_Object;
// Opaque internal representation of an instance object
typedef Semaphore_Object *Semaphore_Handle;
// Client reference to an instance object
typedef struct Semaphore_Struct Semaphore_Struct;
// Opaque client structure large enough to hold an instance object
Semaphore_Handle Semaphore_handle(Semaphore_Struct *structP);
// Convert this instance structure pointer into an instance handle
Semaphore_Struct *Semaphore_struct(Semaphore_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Semaphore_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     Event_Handle event;
    // Event instance to use if non-NULL
    UInt eventId;
    // eventId if using Events
     Semaphore_Mode mode;
    // Semaphore mode
} Semaphore_Params;
Void Semaphore_Params_init(Semaphore_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Semaphore_event // instance
index URL

Event instance to use if non-NULL

C synopsis target-domain
struct Semaphore_Params {
     ...
     Event_Handle event;
DETAILS
The default value of this parameter is null. If event is non-null:
  • Event_post(sem->event, sem->eventId) will be invoked when Semaphore_post() is called.
  • Event_pend(sem->event, 0, sem->eventId, timeout) will be invoked when Semaphore_pend() is called.
config Semaphore_eventId // instance
index URL

eventId if using Events

C synopsis target-domain
struct Semaphore_Params {
     ...
    UInt eventId;
DETAILS
The default for this parameters is 1.
config Semaphore_mode // instance
index URL

Semaphore mode

C synopsis target-domain
struct Semaphore_Params {
     ...
     Semaphore_Mode mode;
DETAILS
When mode is BINARY, the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
The default for this parameter is COUNTING.
Instance Creation
index URL

C synopsis target-domain
Semaphore_Handle Semaphore_create(Int count, const Semaphore_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Semaphore_construct(Semaphore_Struct *structP, Int count, const Semaphore_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
count — initial semaphore count
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new Semaphore object which is initialized to count.
Instance Deletion
index URL

C synopsis target-domain
Void Semaphore_delete(Semaphore_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Semaphore_destruct(Semaphore_Struct *structP);
// Finalize the instance object inside the provided structure
Semaphore_getCount() // instance
index URL

Get current semaphore count

C synopsis target-domain
Int Semaphore_getCount(Semaphore_Handle handle);
ARGUMENTS
handle — handle of a previously-created Semaphore instance object
RETURNS
current semaphore count
DETAILS
This function returns the current value of the semaphore specified by the handle.
Semaphore_pend() // instance
index URL

Wait for a semaphore

C synopsis target-domain
Bool Semaphore_pend(Semaphore_Handle handle, UInt timeout);
ARGUMENTS
handle — handle of a previously-created Semaphore instance object
timeout — return after this many system time units
RETURNS
TRUE if successful, FALSE if timeout
DETAILS
If the semaphore count is greater than zero (available), this function decrements the count and returns TRUE. If the semaphore count is zero (unavailable), this function suspends execution of the current task until post() is called or the timeout expires.
A timeout value of BIOS_WAIT_FOREVER causes the task to wait indefinitely for its semaphore to be posted.
A timeout value of BIOS_NO_WAIT causes Semaphore_pend to return immediately.
Semaphore_post() // instance
index URL

Signal a semaphore

C synopsis target-domain
Void Semaphore_post(Semaphore_Handle handle);
ARGUMENTS
handle — handle of a previously-created Semaphore instance object
DETAILS
Readies the first task waiting for the semaphore. If no task is waiting, this function simply increments the semaphore count and returns. In the case of a binary semaphore, the count has a maximum value of one.
Semaphore_registerEvent() // instance
index URL

Register an Event Object with a semaphore

C synopsis target-domain
Void Semaphore_registerEvent(Semaphore_Handle handle, Event_Handle event, UInt eventId);
ARGUMENTS
handle — handle of a previously-created Semaphore instance object
event — Ptr to Event Object
eventId — Event ID
DETAILS
Ordinarily, an Event object and eventId are configured at Semaphore create time.
This API is provided so that Semaphore-using middleware can support implicit Event posting without having to be retrofitted.
After the Event object and eventId are registered with the Semaphore:
Event_post(event, eventId) will be invoked when Semaphore_post(sem) is called.
Event_pend(event, eventId, 0, timeout) will be invoked when Semaphore_pend(sem, timeout) is called.
Semaphore_reset() // instance
index URL

Reset semaphore count

C synopsis target-domain
Void Semaphore_reset(Semaphore_Handle handle, Int count);
ARGUMENTS
handle — handle of a previously-created Semaphore instance object
count — semaphore count
DETAILS
Resets the semaphore count to count. No task switch occurs when calling SEM_reset.
CONSTRAINTS
count must be greater than or equal to 0.
No tasks should be waiting on the semaphore when Semaphore_reset is called.
Semaphore_reset cannot be called by a Hwi or a Swi.
Instance Built-Ins
index URL

C synopsis target-domain
Int Semaphore_Object_count();
// The number of statically-created instance objects
Semaphore_Handle Semaphore_Object_get(Semaphore_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Semaphore_Handle Semaphore_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Semaphore_Handle Semaphore_Object_next(Semaphore_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Semaphore_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Semaphore_Handle_label(Semaphore_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Semaphore_Handle_name(Semaphore_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Semaphore.xdc
var Semaphore = xdc.useModule('ti.sysbios.knl.Semaphore');
module-wide constants & types
    values of type Semaphore.Mode// Types of semaphores
        const Semaphore.Mode_COUNTING// Counting semaphore;
        const Semaphore.Mode_BINARY// Binary Semaphore;
module-wide config parameters
     Semaphore.A_badContext// Assert raised if an operation is invalid in the current calling context = Assert.Desc {
        msg: "A_badContext: bad calling context. Must be called from a Task."
    };
     Semaphore.A_noEvents// Assert raised if application uses Event but it's not supported = Assert.Desc {
        msg: "A_noEvents: The Event.supportsEvents flag is disabled."
    };
     Semaphore.LM_pend// Logged on calls to Semaphore_pend() = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"
    };
     Semaphore.LM_post// Logged on calls to Semaphore_post() = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_post: sem: 0x%x, count: %d"
    };
     Semaphore.supportsEvents// Support Semaphores with Events? = Bool false;
     Semaphore.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Semaphore.Params// Instance config-params object;
        params.event// Event instance to use if non-NULL = Event.Handle null;
        params.eventId// eventId if using Events = UInt 1;
        params.mode// Semaphore mode = Semaphore.Mode Semaphore.Mode_COUNTING;
per-instance creation
    var inst = Semaphore.create// Create an instance-object(Int count, params);
enum Semaphore.Mode
index URL

Types of semaphores

XDCscript usage meta-domain
values of type Semaphore.Mode
    const Semaphore.Mode_COUNTING;
    // Counting semaphore
    const Semaphore.Mode_BINARY;
    // Binary Semaphore
C SYNOPSIS
Semaphore_Mode
config Semaphore.A_badContext // module-wide
index URL

Assert raised if an operation is invalid in the current calling context

XDCscript usage meta-domain
Semaphore.A_badContext = Assert.Desc {
    msg: "A_badContext: bad calling context. Must be called from a Task."
};
DETAILS
Asserted when pend is called with non-zero timeout from other than a Task context.
C SYNOPSIS
Semaphore_A_badContext
config Semaphore.A_noEvents // module-wide
index URL

Assert raised if application uses Event but it's not supported

XDCscript usage meta-domain
Semaphore.A_noEvents = Assert.Desc {
    msg: "A_noEvents: The Event.supportsEvents flag is disabled."
};
DETAILS
This assertion is triggered by create if supportsEvents is false and an ti.sysbios.knl.Event object is passed to create.
C SYNOPSIS
Semaphore_A_noEvents
config Semaphore.LM_pend // module-wide
index URL

Logged on calls to Semaphore_pend()

XDCscript usage meta-domain
Semaphore.LM_pend = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"
};
C SYNOPSIS
Semaphore_LM_pend
config Semaphore.LM_post // module-wide
index URL

Logged on calls to Semaphore_post()

XDCscript usage meta-domain
Semaphore.LM_post = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_post: sem: 0x%x, count: %d"
};
C SYNOPSIS
Semaphore_LM_post
config Semaphore.supportsEvents // module-wide
index URL

Support Semaphores with Events?

XDCscript usage meta-domain
Semaphore.supportsEvents = Bool false;
DETAILS
The default for this parameter is false.
C SYNOPSIS
Semaphore_supportsEvents
metaonly config Semaphore.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Semaphore.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Semaphore.Params;
// Instance config-params object
    params.event = Event.Handle null;
    // Event instance to use if non-NULL
    params.eventId = UInt 1;
    // eventId if using Events
    params.mode = Semaphore.Mode Semaphore.Mode_COUNTING;
    // Semaphore mode
config Semaphore.event // instance
index URL

Event instance to use if non-NULL

XDCscript usage meta-domain
var params = new Semaphore.Params;
...
params.event = Event.Handle null;
DETAILS
The default value of this parameter is null. If event is non-null:
  • Event_post(sem->event, sem->eventId) will be invoked when Semaphore_post() is called.
  • Event_pend(sem->event, 0, sem->eventId, timeout) will be invoked when Semaphore_pend() is called.
C SYNOPSIS
null
config Semaphore.eventId // instance
index URL

eventId if using Events

XDCscript usage meta-domain
var params = new Semaphore.Params;
...
params.eventId = UInt 1;
DETAILS
The default for this parameters is 1.
C SYNOPSIS
null
config Semaphore.mode // instance
index URL

Semaphore mode

XDCscript usage meta-domain
var params = new Semaphore.Params;
...
params.mode = Semaphore.Mode Semaphore.Mode_COUNTING;
DETAILS
When mode is BINARY, the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
The default for this parameter is COUNTING.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Semaphore.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Semaphore.create(Int count, params);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new Semaphore object which is initialized to count.
generated on Fri, 17 Jun 2011 00:23:57 GMT


module ti.sysbios.knl.Swi
index URL

Software Interrupt Manager

  • C synopsis
  • Individual elements
  • DETAILS
  • HOOK FUNCTIONS
  • XDCscript usage
  • Individual elements
The Swi module manages software interrupt service routines, which are patterned after hardware interrupt service routines. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Swi.xdc
#include <ti/sysbios/knl/Swi.h>
Functions
Void | Swi_andn// Clear bits in Swi's trigger; post if trigger becomes 0(Swi_Handle handle, UInt mask);
Void | Swi_construct// Initialize a new instance object inside the provided structure(Swi_Struct *structP, Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
Swi_Handle | Swi_create// Allocate and initialize a new instance object and return its handle(Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
Void | Swi_dec// Decrement Swi's trigger value; post if trigger becomes 0(Swi_Handle handle);
Void | Swi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Swi_Handle *handleP);
Void | Swi_destruct// Finalize the instance object inside the provided structure(Swi_Struct *structP);
UInt | Swi_disable// Disable Swi Scheduling();
Swi_FuncPtr | Swi_getFunc// Get Swi function and arguments(Swi_Handle handle, UArg *arg0, UArg *arg1);
Ptr | Swi_getHookContext// Get hook instance's context pointer for a Swi(Swi_Handle handle, Int id);
UInt | Swi_getPri// Return a Swi's priority(Swi_Handle handle);
UInt | Swi_getTrigger// Return the trigger value of the currently executing Swi();
Void | Swi_inc// Increment Swi's trigger value and post the Swi(Swi_Handle handle);
Void | Swi_or// Or mask with value contained in Swi's trigger and post the Swi(Swi_Handle handle, UInt mask);
Void | Swi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Swi_Params *params);
Void | Swi_post// Unconditionally post a software interrupt(Swi_Handle handle);
Void | Swi_restore// Restore Swi Scheduling state(UInt key);
Swi_Handle | Swi_self// Return address of currently executing Swi object();
Void | Swi_setHookContext// Set hook instance's context for a swi(Swi_Handle handle, Int id, Ptr hookContext);
Functions common to all target instances
 | Swi_handle// Convert this instance structure pointer into an instance handle, Swi_Handle_label// The label associated with this instance object, Swi_Handle_name// The name of this instance object, Swi_Object_count// The number of statically-created instance objects, Swi_Object_first// The handle of the first dynamically-created instance object, or NULL, Swi_Object_get// The handle of the i-th statically-created instance object (array == NULL), Swi_Object_heap// The heap used to allocate dynamically-created instance objects, Swi_Object_next// The handle of the next dynamically-created instance object, or NULL, Swi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Swi_Module_getMask// Returns the diagnostics mask for this module, Swi_Module_hasMask// Test whether this module has a diagnostics mask, Swi_Module_heap// The heap from which this module allocates memory, Swi_Module_id// Get this module's unique id, Swi_Module_setMask// Set the diagnostics mask for this module, Swi_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Swi_FuncPtr// Swi function type definition)(UArg,UArg);
typedef Swi_Object * | Swi_Handle// Client reference to an instance object;
typedef struct | Swi_HookSet// Swi hook set type definition ...
typedef struct | Swi_Object// Opaque internal representation of an instance object Swi_Object;
typedef struct | Swi_Params// Instance config-params structure ...
typedef struct | Swi_Struct// Opaque client structure large enough to hold an instance object Swi_Struct;
Constants
extern const Assert_Id | Swi_A_badPriority// Assertion raised if a Swi's priority is out of range;
extern const Assert_Id | Swi_A_swiDisabled// Assertion raised if Swi_create is called and runtime Swi creation is disabled;
extern const Log_Event | Swi_LD_end// The event logged just after returning from a Swi's function;
extern const Log_Event | Swi_LM_begin// The event logged just prior to invoking a Swi's function;
extern const Log_Event | Swi_LM_post// The event logged when Swi_post() is called;
extern const UInt | Swi_numPriorities// Number of Swi priorities supported;
DETAILS
The Swi module manages software interrupt service routines, which are patterned after hardware interrupt service routines.
SYS/BIOS manages four distinct levels of execution threads: hardware interrupt service routines, software interrupt routines, tasks, and background idle functions. A software interrupt is an object that encapsulates a function to be executed and a priority. Software interrupts are prioritized, preempt tasks, and are preempted by hardware interrupt service routines.
Each software interrupt has a priority level. A software interrupt preempts any lower-priority software interrupt currently executing.
A target program uses an API call to post a Swi object. This causes the Swi module to schedule execution of the software interrupt's function. When a Swi is posted by an API call, the Swi object's function is not executed immediately. Instead, the function is scheduled for execution. SYS/BIOS uses the Swi's priority to determine whether to preempt the thread currently running. Note that if a Swi is posted several times before it begins running, (because Hwis and higher priority interrupts are running,) when the Swi does eventually run, it will run only one time.
Software interrupts can be posted for execution with a call to post or a number of other Swi functions. Each Swi object has a "trigger" which is used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function. andn and dec post the Swi if the trigger value transitions to 0. or and inc also modify the trigger value. (or sets bits, and andn clears bits.)
The disable and restore operations allow you to post several Swis and enable them all for execution at the same time. The Swi priorities then determine which Swi runs first.
All Swis run to completion; you cannot suspend a Swi while it waits for something (for example, a device) to be ready. So, you can use the trigger to tell the Swi when all the devices and other conditions it relies on are ready. Within a Swi processing function, a call to Swi_getTrigger returns the value of the trigger when the Swi started running. Note that the trigger is automatically reset to its original value when a Swi runs; however, getTrigger will return the saved trigger value from when the Swi started execution.
All Swis run with interrupts globally enabled (ie GIE = 1). Therefore, any Swi module API that results in a Swi being made ready to run (ie post, inc, andn, or, restore, or enable) will subsequently also cause interrupts to be enabled while the Swi function executes. Upon return from the Swi function, global interrupts are restored to their previous enabled/disabled state.
A Swi preempts any currently running Swi with a lower priority. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted. Hwis in turn preempt any currently running Swi, allowing the target to respond quickly to hardware peripherals.
Swi threads are executed using the ISR (or "Hwi") stack. Thus they share the ISR stack with Hwi threads.
disable also disables the Task scheduler. Therefore, Task pre-emption and blocking is disabled while the Swi scheduler is disabled. restore will re-enable and invoke the Task scheduler if the Task scheduler was not disabled prior to invoking disable. The currently ready highest priority task will be immediately switched to or continue to run when the lowest order restore invocation re-enables the Swi scheduler.
In the following example, the newly created task is not switched to until after the Swi_restore() call since Task scheduling is disabled while Swi scheduling is disabled:
  key = Swi_disable();
  // create a task of higher priority than the current task thread
  myTaskParams.priority = Task_getPri(Task_self()) + 1;
  myTask = Task_create(myTaskFunc, &myTaskParams, NULL);
  Swi_restore(key);
HOOK FUNCTIONS
Sets of hook functions can be specified for the Swi module. Each set contains these hook functions:
  • Register: A function called before all statically-created Swis are initialized at runtime.
  • Create: A function that is called when a Swi is created. This includes Swis that are created statically and those created dynamically using create.
  • Ready: A function that is called when any Swi becomes ready to run.
  • Begin: A function that is called just prior to running a Swi.
  • End: A function that is called just after a Swi finishes.
  • Delete: A function that is called when a Swi is deleted at run-time with delete.
Hook functions can only be configured statically.
If you define more than one set of hook functions, all the functions of a particular type will be run when a Swi triggers that type of hook.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to setHookContext and getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use setHookContext or getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete Functions
The create and delete functions are called whenever a Swi is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).
  Void myCreateFxn(Swi_Handle swi, Error_Block *eb);

  Void myDeleteFxn(Swi_Handle swi);
Ready, Begin, and End Functions
The ready, begin and end functions are all called with interrupts enabled. The ready function is called when a Swi is posted and made ready to run. The begin function is called right before the function associated with the given Swi is run. The end function is called right after this function returns.
  Void myReady(Swi_Handle swi);

  Void myBegin(Swi_Handle swi);

  Void myEnd(Swi_Handle swi);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | N
getTrigger | Y | Y | N | N | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | N
self | Y | Y | N | N | N
andn | Y | Y | Y | Y | N
construct | N | N | Y | Y | N
dec | Y | Y | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getHookContext | Y | Y | Y | Y | N
getPri | Y | Y | Y | Y | N
getFunc | Y | Y | Y | Y | N
inc | Y | Y | Y | Y | N
or | Y | Y | Y | Y | N
post | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Swi_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Swi_Module_startupDone() returns FALSE).
typedef Swi_FuncPtr
index URL

Swi function type definition

C synopsis target-domain
typedef Void (*Swi_FuncPtr)(UArg,UArg);
DETAILS
All Swi functions are passed two uninterpreted arguments of type UArg and have no return value.
struct Swi_HookSet
index URL

Swi hook set type definition

C synopsis target-domain
typedef struct Swi_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(Swi_Handle,Error_Block*);
    Void (*readyFxn)(Swi_Handle);
    Void (*beginFxn)(Swi_Handle);
    Void (*endFxn)(Swi_Handle);
    Void (*deleteFxn)(Swi_Handle);
} Swi_HookSet;
DETAILS
This structure defines the set of hook functions that can be specified for the Swi module.
See Hook Functions for details.
config Swi_A_badPriority // module-wide
index URL

Assertion raised if a Swi's priority is out of range

C synopsis target-domain
extern const Assert_Id Swi_A_badPriority;
DETAILS
Swi priorities must be in the range of 0 and numPriorities-1.
config Swi_A_swiDisabled // module-wide
index URL

Assertion raised if Swi_create is called and runtime Swi creation is disabled

C synopsis target-domain
extern const Assert_Id Swi_A_swiDisabled;
SEE
{@link ti.sysbios.BIOS#swiEnabled}
config Swi_LD_end // module-wide
index URL

The event logged just after returning from a Swi's function

C synopsis target-domain
extern const Log_Event Swi_LD_end;
config Swi_LM_begin // module-wide
index URL

The event logged just prior to invoking a Swi's function

C synopsis target-domain
extern const Log_Event Swi_LM_begin;
config Swi_LM_post // module-wide
index URL

The event logged when Swi_post() is called

C synopsis target-domain
extern const Log_Event Swi_LM_post;
config Swi_numPriorities // module-wide
index URL

Number of Swi priorities supported

C synopsis target-domain
extern const UInt Swi_numPriorities;
DETAILS
The maximum number of priorities supported is target-specific and depends on the number of bits in a UInt data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For 28x, 55x, and MSP430 devices, the maximum number of priorities is 16.
Swi_disable() // module-wide
index URL

Disable Swi Scheduling

C synopsis target-domain
UInt Swi_disable();
RETURNS
opaque key for use with Swi_restore()
DETAILS
disable and restore control Swi scheduling. disable disables all other Swi functions from running until restore is called. Hardware interrupts can still run.
disable and restore allow you to ensure that statements that must be performed together during critical processing are not preempted by other Swis or Tasks.
The value of the key returned is opaque to applications and is meant to be passed to Swi_restore().
In the following example, the critical section cannot be preempted by any Swis.
  key = Swi_disable();
      `critical section`
  Swi_restore(key);
CONSTRAINTS
Swi_disable also disables the Task scheduler. Swi_restore will re-enable and invoke the Task scheduler if the Task scheduler was not disabled prior to invoking Swi_disable().
Swi_getTrigger() // module-wide
index URL

Return the trigger value of the currently executing Swi

C synopsis target-domain
UInt Swi_getTrigger();
RETURNS
trigger value
DETAILS
Swi_getTrigger returns the value that Swi's trigger had when the Swi started running. SYS/BIOS saves the trigger value internally, so that Swi_getTrigger can access it at any point within a Swi object's function, and then automatically resets the trigger to its initial value.
Swi_getTrigger should only be called within a function run by a Swi object.
When called from within the context of a Swi, the value returned by Swi_getTrigger is zero if the Swi was posted by a call to Swi_andn, or Swi_dec. Therefore, Swi_getTrigger provides relevant information only if the Swi was posted by a call to Swi_inc, Swi_or, Swi_orHook, or Swi_post.
This API is called within a Swi object's function to use the trigger value that caused the function to run. For example, if you use Swi_or or Swi_inc to post a Swi, different trigger values can require different processing.
  swicount = Swi_getTrigger();
Swi_restore() // module-wide
index URL

Restore Swi Scheduling state

C synopsis target-domain
Void Swi_restore(UInt key);
ARGUMENTS
key — key to restore previous Swi scheduler state
DETAILS
Swi_restore restores the Swi scheduler to the locked/unlocked state it was in when Swi_disable was called. If the scheduler becomes unlocked and Swis of sufficient priority have been made ready to run by any of the posting APIs, then they are run at this time.
Swi_disable and Swi_restore control software interrupt processing. Swi_disable disables all other Swi functions from running until Swi_restore is called. Hardware interrupts can still run.
Swi_disable and Swi_restore allow you to ensure that statements that must be performed together during critical processing are not pre-empted by other Swis.
In the following example, the critical section cannot be preempted by any Swis:
  key = Swi_disable();
      `critical section`
  Swi_restore(key);
CONSTRAINTS
Swi_restore will also re-enable and invoke the Task scheduler if the Task scheduler was not disabled prior to invoking Swi_disable().
The post discussion regarding global interrupts applies to this API.
Swi_self() // module-wide
index URL

Return address of currently executing Swi object

C synopsis target-domain
Swi_Handle Swi_self();
RETURNS
handle of currently running Swi
DETAILS
Swi_self returns the handle of the currently executing Swi.
For example, you can call Swi_self as follows if you want a Swi to repost itself:
  Swi_post(Swi_self());
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Swi_Module_id();
// Get this module's unique id
Bool Swi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Swi_Module_heap();
// The heap from which this module allocates memory
Bool Swi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Swi_Module_getMask();
// Returns the diagnostics mask for this module
Void Swi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Swi_Object Swi_Object;
// Opaque internal representation of an instance object
typedef Swi_Object *Swi_Handle;
// Client reference to an instance object
typedef struct Swi_Struct Swi_Struct;
// Opaque client structure large enough to hold an instance object
Swi_Handle Swi_handle(Swi_Struct *structP);
// Convert this instance structure pointer into an instance handle
Swi_Struct *Swi_struct(Swi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Swi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg0;
    // Swi function argument 0
    UArg arg1;
    // Swi function argument 1
    UInt priority;
    // Swi priority
    UInt trigger;
    // Initial Swi trigger value
} Swi_Params;
Void Swi_Params_init(Swi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Swi_arg0 // instance
index URL

Swi function argument 0

C synopsis target-domain
struct Swi_Params {
     ...
    UArg arg0;
DETAILS
The default value of this optional parameter is 0.
SEE
FuncPtr
config Swi_arg1 // instance
index URL

Swi function argument 1

C synopsis target-domain
struct Swi_Params {
     ...
    UArg arg1;
DETAILS
The default value of this optional parameter is 0.
SEE
FuncPtr
config Swi_priority // instance
index URL

Swi priority

C synopsis target-domain
struct Swi_Params {
     ...
    UInt priority;
DETAILS
Each software interrupt has a priority level, 0 to (numPriorities - 1). A software interrupt preempts any lower-priority software interrupt currently executing. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted.
The default value of this optional parameter is ~0, which yields a Swi with the highest priority: (numPriorities - 1).
config Swi_trigger // instance
index URL

Initial Swi trigger value

C synopsis target-domain
struct Swi_Params {
     ...
    UInt trigger;
DETAILS
The default value of this optional parameter is 0.
Each Swi object has a "trigger" used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function.
The andn and dec functions post the Swi if the trigger value transitions to 0. The or and inc functions also modify the trigger value. (or sets bits, and andn clears bits.)
Instance Creation
index URL

C synopsis target-domain
Swi_Handle Swi_create(Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Swi_construct(Swi_Struct *structP, Swi_FuncPtr fxn, const Swi_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
fxn — Swi Function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Swi_create creates a new Swi object.
The following C code sets Swi parameters and creates two Swi objects:
  Void main()
  {
      Swi_Params swiParams;

      Swi_Params_init(&swiParams);
      swiParams.arg0 = 1;
      swiParams.arg1 = 0;
      swiParams.priority = 2;
      swiParams.trigger = 0;

      swi0 = Swi_create(swi0Fxn, &swiParams, NULL);

      swiParams.arg0 = 2;
      swiParams.arg1 = 0;
      swiParams.priority = 1;
      swiParams.trigger = 3;

      swi1 = Swi_create(swi1Fxn, &swiParams, NULL);

      BIOS_start();
  }
The following XDCscript statements set Swi parameters and create two Swi objects:
  var Swi = xdc.useModule('ti.sysbios.knl.Swi');

  var swiParams = new Swi.Params();
  swiParams.arg0 = 1;
  swiParams.arg1 = 0;
  swiParams.priority = 2;
  swiParams.trigger = 0;
  Program.global.swi0 = Swi.create('&swi0Fxn', swiParams);

  swiParams.arg0 = 2;
  swiParams.priority = 1;
  swiParams.trigger = 3;
  Program.global.swi1 = Swi.create('&swi1Fxn', swiParams);
Instance Deletion
index URL

C synopsis target-domain
Void Swi_delete(Swi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Swi_destruct(Swi_Struct *structP);
// Finalize the instance object inside the provided structure
Swi_andn() // instance
index URL

Clear bits in Swi's trigger; post if trigger becomes 0

C synopsis target-domain
Void Swi_andn(Swi_Handle handle, UInt mask);
ARGUMENTS
handle — handle of a previously-created Swi instance object
mask — inverse value to be ANDed
DETAILS
Swi_andn is used to conditionally post a software interrupt. Swi_andn clears the bits specified by a mask from Swi's internal trigger. If the Swi's trigger becomes 0, Swi_andn posts the Swi. The bitwise logical operation performed is:
  trigger = trigger AND (NOT MASK)
If multiple conditions that all be met before a Swi can run, you should use a different bit in the trigger for each condition. When a condition is met, clear the bit for that condition.
For example, if two events must happen before a Swi is to be triggered, the initial trigger value of the Swi can be 3 (binary 0011). One call to Swi_andn can have a mask value of 2 (binary 0010), and another call to Swi_andn can have a mask value of 1 (binary 0001). After both calls have been made, the trigger value will be 0.
  Swi_andn(swi0, 2);  // clear bit 1
  Swi_andn(swi0, 1);  // clear bit 0
Swi_andn results in a context switch if the Swi's trigger becomes zero and the Swi has higher priority than the currently executing thread.
You specify a Swi's initial trigger value at Swi creation time. The trigger value is automatically reset when the Swi executes.
CONSTRAINTS
The post discussion regarding global interrupts applies to this API.
Swi_dec() // instance
index URL

Decrement Swi's trigger value; post if trigger becomes 0

C synopsis target-domain
Void Swi_dec(Swi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Swi instance object
DETAILS
Swi_dec is used to conditionally post a software interrupt. Swi_dec decrements the value in Swi's trigger by 1. If Swi's trigger value becomes 0, Swi_dec posts the Swi. You can increment a trigger value by using Swi_inc, which always posts the Swi.
For example, you would use Swi_dec if you wanted to post a Swi after a number of occurrences of an event.
  // swi0's trigger is configured to start at 3
  Swi_dec(swi0);      // trigger = 2
  Swi_dec(swi0);      // trigger = 1
  Swi_dec(swi0);      // trigger = 0
You specify a Swi's initial trigger value at Swi creation time. The trigger value is automatically reset when the Swi executes.
Swi_dec results in a context switch if the Swi's trigger becomes zero and the Swi has higher priority than the currently executing thread.
CONSTRAINTS
The post discussion regarding global interrupts applies to this API.
Swi_getFunc() // instance
index URL

Get Swi function and arguments

C synopsis target-domain
Swi_FuncPtr Swi_getFunc(Swi_Handle handle, UArg *arg0, UArg *arg1);
ARGUMENTS
handle — handle of a previously-created Swi instance object
arg0 — pointer for returning Swi's first function argument
arg1 — pointer for returning Swi's second function argument
RETURNS
Swi function
DETAILS
If either arg0 or arg1 is NULL, then the corresponding argument is not returned.
Swi_getHookContext() // instance
index URL

Get hook instance's context pointer for a Swi

C synopsis target-domain
Ptr Swi_getHookContext(Swi_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Swi instance object
RETURNS
hook instance's context pointer for Swi
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Swi_Handle mySwi;
  Int myHookSetId1;

  pEnv = Swi_getHookContext(swi, myHookSetId1);

  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
                (ULong)pEnv, (ULong)Timestamp_get32());

  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
Swi_getPri() // instance
index URL

Return a Swi's priority

C synopsis target-domain
UInt Swi_getPri(Swi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Swi instance object
RETURNS
Priority of Swi
DETAILS
Swi_getPri returns the priority of the Swi passed in as the argument.
Swi_inc() // instance
index URL

Increment Swi's trigger value and post the Swi

C synopsis target-domain
Void Swi_inc(Swi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Swi instance object
DETAILS
Swi_inc increments the value in Swi's trigger by 1 and posts the Swi regardless of the resulting trigger value. You can decrement a trigger value using Swi_dec, which only posts the Swi if the trigger value is 0.
If a Swi is posted several times before it has a chance to begin executing (i.e. when Hwis or higher priority Swis are running) the Swi only runs one time. If this situation occurs, you can use Swi_inc to post the Swi. Within the Swi's function, you could then use Swi_getTrigger to find out how many times this Swi has been posted since the last time it was executed.
You specify a Swi's initial trigger value at Swi creation time. The trigger value is automatically reset when the Swi executes. To get the trigger value, use Swi_getTrigger.
Swi_inc results in a context switch if the Swi is higher priority than the currently executing thread.
CONSTRAINTS
The post discussion regarding global interrupts applies to this API.
Swi_or() // instance
index URL

Or mask with value contained in Swi's trigger and post the Swi

C synopsis target-domain
Void Swi_or(Swi_Handle handle, UInt mask);
ARGUMENTS
handle — handle of a previously-created Swi instance object
mask — value to be ORed
DETAILS
Swi_or is used to post a software interrupt. Swi_or sets the bits specified by a mask in Swi's trigger. Swi_or posts the Swi regardless of the resulting trigger value. The bitwise logical operation performed on the trigger value is:
  trigger = trigger OR mask
You specify a Swi's initial trigger value at Swi creation time. The trigger value is automatically reset when the Swi executes. To get the trigger value, use Swi_getTrigger.
For example, you might use Swi_or to post a Swi if any of three events should cause a Swi to be executed, but you want the Swi's function to be able to tell which event occurred. Each event would correspond to a different bit in the trigger.
Swi_or results in a context switch if the Swi is higher priority than the currently executing thread.
CONSTRAINTS
The post discussion regarding global interrupts applies to this API.
Swi_post() // instance
index URL

Unconditionally post a software interrupt

C synopsis target-domain
Void Swi_post(Swi_Handle handle);
ARGUMENTS
handle — handle of a previously-created Swi instance object
DETAILS
Swi_post is used to post a software interrupt regardless of the trigger value. No change is made to the Swi object's trigger value.
Swi_post results in a context switch if the Swi is higher priority than the currently executing thread.
CONSTRAINTS
Swis are ALWAYS run with interrupts enabled. If a Swi is made ready to run as a consequence of this API, interrupts will be globally enabled while the Swi function executes, regardless of the prior globally enabled/disabled state of interrupts. Upon return from this API, the global interrupt enabled/disabled state is restored to its previous value.
Swi_setHookContext() // instance
index URL

Set hook instance's context for a swi

C synopsis target-domain
Void Swi_setHookContext(Swi_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Swi instance object
id — hook instance's ID
hookContext — value to write to context
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Swi_Handle mySwi;
  Int myHookSetId1;

  pEnv = Swi_getHookContext(swi, myHookSetId1);

  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
                (ULong)pEnv, (ULong)Timestamp_get32());

  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
Instance Built-Ins
index URL

C synopsis target-domain
Int Swi_Object_count();
// The number of statically-created instance objects
Swi_Handle Swi_Object_get(Swi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Swi_Handle Swi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Swi_Handle Swi_Object_next(Swi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Swi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Swi_Handle_label(Swi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Swi_Handle_name(Swi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Swi.xdc
var Swi = xdc.useModule('ti.sysbios.knl.Swi');
module-wide constants & types
    var obj = new Swi.HookSet// Swi hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(Swi.Handle,Error.Block*) ...
        obj.readyFxn = Void(*)(Swi.Handle) ...
        obj.beginFxn = Void(*)(Swi.Handle) ...
        obj.endFxn = Void(*)(Swi.Handle) ...
        obj.deleteFxn = Void(*)(Swi.Handle) ...
module-wide config parameters
     Swi.A_badPriority// Assertion raised if a Swi's priority is out of range = Assert.Desc {
        msg: "A_badPriority: An invalid Swi priority was used."
    };
     Swi.A_swiDisabled// Assertion raised if Swi_create is called and runtime Swi creation is disabled = Assert.Desc {
        msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
    };
     Swi.LD_end// The event logged just after returning from a Swi's function = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_end: swi: 0x%x"
    };
     Swi.LM_begin// The event logged just prior to invoking a Swi's function = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
    };
     Swi.LM_post// The event logged when Swi_post() is called = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
    };
     Swi.numPriorities// Number of Swi priorities supported = UInt 16;
     Swi.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     Swi.addHookSet// Add hook functions to be called by the Swi scheduler(Swi.HookSet hookSet) returns Void
per-instance config parameters
    var params = new Swi.Params// Instance config-params object;
        params.arg0// Swi function argument 0 = UArg 0;
        params.arg1// Swi function argument 1 = UArg 0;
        params.priority// Swi priority = UInt ~0;
        params.trigger// Initial Swi trigger value = UInt 0;
per-instance creation
    var inst = Swi.create// Create an instance-object(Void(*)(UArg,UArg) fxn, params);
struct Swi.HookSet
index URL

Swi hook set type definition

XDCscript usage meta-domain
var obj = new Swi.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(Swi.Handle,Error.Block*) ...
    obj.readyFxn = Void(*)(Swi.Handle) ...
    obj.beginFxn = Void(*)(Swi.Handle) ...
    obj.endFxn = Void(*)(Swi.Handle) ...
    obj.deleteFxn = Void(*)(Swi.Handle) ...
DETAILS
This structure defines the set of hook functions that can be specified for the Swi module.
See Hook Functions for details.
C SYNOPSIS
Swi_HookSet
config Swi.A_badPriority // module-wide
index URL

Assertion raised if a Swi's priority is out of range

XDCscript usage meta-domain
Swi.A_badPriority = Assert.Desc {
    msg: "A_badPriority: An invalid Swi priority was used."
};
DETAILS
Swi priorities must be in the range of 0 and numPriorities-1.
C SYNOPSIS
Swi_A_badPriority
config Swi.A_swiDisabled // module-wide
index URL

Assertion raised if Swi_create is called and runtime Swi creation is disabled

XDCscript usage meta-domain
Swi.A_swiDisabled = Assert.Desc {
    msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
};
SEE
{@link ti.sysbios.BIOS#swiEnabled}
C SYNOPSIS
Swi_A_swiDisabled
config Swi.LD_end // module-wide
index URL

The event logged just after returning from a Swi's function

XDCscript usage meta-domain
Swi.LD_end = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_end: swi: 0x%x"
};
C SYNOPSIS
Swi_LD_end
config Swi.LM_begin // module-wide
index URL

The event logged just prior to invoking a Swi's function

XDCscript usage meta-domain
Swi.LM_begin = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
};
C SYNOPSIS
Swi_LM_begin
config Swi.LM_post // module-wide
index URL

The event logged when Swi_post() is called

XDCscript usage meta-domain
Swi.LM_post = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
};
C SYNOPSIS
Swi_LM_post
config Swi.numPriorities // module-wide
index URL

Number of Swi priorities supported

XDCscript usage meta-domain
Swi.numPriorities = UInt 16;
DETAILS
The maximum number of priorities supported is target-specific and depends on the number of bits in a UInt data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For 28x, 55x, and MSP430 devices, the maximum number of priorities is 16.
C SYNOPSIS
Swi_numPriorities
metaonly config Swi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Swi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly Swi.addHookSet() // module-wide
index URL

Add hook functions to be called by the Swi scheduler

XDCscript usage meta-domain
Swi.addHookSet(Swi.HookSet hookSet) returns Void
ARGUMENTS
hookSet — structure of type HookSet
DETAILS
This function is used in a config file to add a set of functions that are called before or after significant points within the Swi scheduler.
Configures a set of hook functions for the Swi module. Each set contains these hook functions:
  • Register: A function called before all statically-created Swis are initialized at runtime.
  • Create: A function that is called when a Swi is created. This includes Swis that are created statically and those created dynamically using create.
  • Ready: A function that is called when any Swi becomes ready to run.
  • Begin: A function that is called just prior to running a Swi.
  • End: A function that is called just after a Swi finishes.
  • Delete: A function that is called when a Swi is deleted at run-time with delete.
See Hook Functions for more details.
HookSet structure elements may be omitted, in which case those elements will not exist.
For example, the following configuration code defines a HookSet:
  // Hook Set 1
  Swi.addHookSet({
     registerFxn: '&myRegister1',
     createFxn:   '&myCreate1',
     readyFxn:    '&myReady1',
     beginFxn:    '&myBegin1',
     endFxn:      '&myEnd1',
     deleteFxn:   '&myDelete1'
  });
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Swi.Params;
// Instance config-params object
    params.arg0 = UArg 0;
    // Swi function argument 0
    params.arg1 = UArg 0;
    // Swi function argument 1
    params.priority = UInt ~0;
    // Swi priority
    params.trigger = UInt 0;
    // Initial Swi trigger value
config Swi.arg0 // instance
index URL

Swi function argument 0

XDCscript usage meta-domain
var params = new Swi.Params;
...
params.arg0 = UArg 0;
DETAILS
The default value of this optional parameter is 0.
SEE
FuncPtr
C SYNOPSIS
null
config Swi.arg1 // instance
index URL

Swi function argument 1

XDCscript usage meta-domain
var params = new Swi.Params;
...
params.arg1 = UArg 0;
DETAILS
The default value of this optional parameter is 0.
SEE
FuncPtr
C SYNOPSIS
null
config Swi.priority // instance
index URL

Swi priority

XDCscript usage meta-domain
var params = new Swi.Params;
...
params.priority = UInt ~0;
DETAILS
Each software interrupt has a priority level, 0 to (numPriorities - 1). A software interrupt preempts any lower-priority software interrupt currently executing. When multiple Swis of the same priority level have been posted, their respective Swi functions are executed in the order the Swis were posted.
The default value of this optional parameter is ~0, which yields a Swi with the highest priority: (numPriorities - 1).
C SYNOPSIS
null
config Swi.trigger // instance
index URL

Initial Swi trigger value

XDCscript usage meta-domain
var params = new Swi.Params;
...
params.trigger = UInt 0;
DETAILS
The default value of this optional parameter is 0.
Each Swi object has a "trigger" used either to determine whether to post the Swi or as a value that can be evaluated within the Swi's function.
The andn and dec functions post the Swi if the trigger value transitions to 0. The or and inc functions also modify the trigger value. (or sets bits, and andn clears bits.)
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Swi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Swi.create(Void(*)(UArg,UArg) fxn, params);
// Create an instance-object
ARGUMENTS
fxn — Swi Function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Swi_create creates a new Swi object.
The following C code sets Swi parameters and creates two Swi objects:
  Void main()
  {
      Swi_Params swiParams;

      Swi_Params_init(&swiParams);
      swiParams.arg0 = 1;
      swiParams.arg1 = 0;
      swiParams.priority = 2;
      swiParams.trigger = 0;

      swi0 = Swi_create(swi0Fxn, &swiParams, NULL);

      swiParams.arg0 = 2;
      swiParams.arg1 = 0;
      swiParams.priority = 1;
      swiParams.trigger = 3;

      swi1 = Swi_create(swi1Fxn, &swiParams, NULL);

      BIOS_start();
  }
The following XDCscript statements set Swi parameters and create two Swi objects:
  var Swi = xdc.useModule('ti.sysbios.knl.Swi');

  var swiParams = new Swi.Params();
  swiParams.arg0 = 1;
  swiParams.arg1 = 0;
  swiParams.priority = 2;
  swiParams.trigger = 0;
  Program.global.swi0 = Swi.create('&swi0Fxn', swiParams);

  swiParams.arg0 = 2;
  swiParams.priority = 1;
  swiParams.trigger = 3;
  Program.global.swi1 = Swi.create('&swi1Fxn', swiParams);
generated on Fri, 17 Jun 2011 00:23:57 GMT


module ti.sysbios.knl.Task
index URL

Task Manager

  • C synopsis
  • Individual elements
  • DETAILS
  • TASK DELETION
  • STACK ALIGNMENT
  • HOOK FUNCTIONS
  • XDCscript usage
  • Individual elements
The Task module makes available a set of functions that manipulate task objects accessed through pointers of type Handle. Tasks represent independent threads of control that conceptually execute functions in parallel within a single C program; in reality, concurrency is achieved by switching the processor from one task to another. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Task.xdc
#include <ti/sysbios/knl/Task.h>
Functions
Void | Task_construct// Initialize a new instance object inside the provided structure(Task_Struct *structP, Task_FuncPtr fxn, const Task_Params *params, Error_Block *eb);
Task_Handle | Task_create// Allocate and initialize a new instance object and return its handle(Task_FuncPtr fxn, const Task_Params *params, Error_Block *eb);
Void | Task_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Task_Handle *handleP);
Void | Task_destruct// Finalize the instance object inside the provided structure(Task_Struct *structP);
UInt | Task_disable// Disable the task scheduler();
Void | Task_exit// Terminate execution of the current task();
Ptr | Task_getEnv// Get task environment pointer(Task_Handle handle);
Ptr | Task_getHookContext// Get hook set's context for a task(Task_Handle handle, Int id);
Task_Handle | Task_getIdleTask// returns a handle to idle task object();
Task_Mode | Task_getMode// Retrieve the Mode of a task(Task_Handle handle);
Int | Task_getPri// Get task priority(Task_Handle handle);
Void | Task_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Task_Params *params);
Void | Task_restore// Restore Task scheduling state(UInt key);
Task_Handle | Task_self// Returns a handle to the currently executing Task object();
macro Task_Handle | Task_selfMacro// Returns a handle to the currently executing Task object();
Void | Task_setEnv// Set task environment(Task_Handle handle, Ptr env);
Void | Task_setHookContext// Set hook instance's context for a task(Task_Handle handle, Int id, Ptr hookContext);
UInt | Task_setPri// Set a task's priority(Task_Handle handle, Int newpri);
Void | Task_sleep// Delay execution of the current task(UInt nticks);
Void | Task_stat// Retrieve the status of a task(Task_Handle handle, Task_Stat *statbuf);
Void | Task_yield// Yield processor to equal priority task();
Functions common to all target instances
 | Task_handle// Convert this instance structure pointer into an instance handle, Task_Handle_label// The label associated with this instance object, Task_Handle_name// The name of this instance object, Task_Object_count// The number of statically-created instance objects, Task_Object_first// The handle of the first dynamically-created instance object, or NULL, Task_Object_get// The handle of the i-th statically-created instance object (array == NULL), Task_Object_heap// The heap used to allocate dynamically-created instance objects, Task_Object_next// The handle of the next dynamically-created instance object, or NULL, Task_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Task_Module_getMask// Returns the diagnostics mask for this module, Task_Module_hasMask// Test whether this module has a diagnostics mask, Task_Module_heap// The heap from which this module allocates memory, Task_Module_id// Get this module's unique id, Task_Module_setMask// Set the diagnostics mask for this module, Task_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Task_AllBlockedFuncPtr// "All Task Blocked" function type definition)(Void);
typedef Void | (*Task_FuncPtr// Task function type definition)(UArg,UArg);
typedef Task_Object * | Task_Handle// Client reference to an instance object;
typedef struct | Task_HookSet// Task hook set type definition ...
typedef enum | Task_Mode// Task execution modes ...
typedef struct | Task_Object// Opaque internal representation of an instance object Task_Object;
typedef struct | Task_Params// Instance config-params structure ...
typedef struct | Task_Stat// Task Status Buffer ...
typedef struct | Task_Struct// Opaque client structure large enough to hold an instance object Task_Struct;
Constants
extern const Task_AllBlockedFuncPtr | Task_allBlockedFunc// Function to call while all tasks are blocked;
extern const Assert_Id | Task_A_badPriority// Asserted in Task_create;
extern const Assert_Id | Task_A_badTaskState// Asserted in Task_delete;
extern const Assert_Id | Task_A_badThreadType// Asserted in Task_create and Task_delete;
extern const Assert_Id | Task_A_badTimeout// Asserted in Task_sleep;
extern const Assert_Id | Task_A_noPendElem// Asserted in Task_delete;
extern const Assert_Id | Task_A_taskDisabled// Asserted in Task_create;
extern const IHeap_Handle | Task_defaultStackHeap// Default Mem heap used for all dynamically created task stacks;
extern const SizeT | Task_defaultStackSize// Default stack size (in MAUs) used for all tasks;
extern const Bool | Task_deleteTerminatedTasks// Automatically delete terminated tasks;
extern const Error_Id | Task_E_spOutOfBounds// Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack;
extern const Error_Id | Task_E_stackOverflow// Error raised when a stack overflow (or corruption) is detected;
extern const Task_HookSet | Task_hooks// Const array that holds the HookSet objects[length];
extern const Bool | Task_initStackFlag// Initialize stack with known value for stack checking at runtime (see checkStackFlag);
extern const Log_Event | Task_LD_block// Logged when a task is blocked (ie Semaphore_pend());
extern const Log_Event | Task_LD_exit// Logged when Task functions fall thru the bottom or when Task_exit() is explicitly called;
extern const Log_Event | Task_LD_ready// Logged when a task is made ready to run (ie Semaphore_post());
extern const Log_Event | Task_LM_setPri// Logged on calls to Task_setPri;
extern const Log_Event | Task_LM_sleep// Logged on calls to Task_sleep;
extern const Log_Event | Task_LM_switch// Logged on every task switch;
extern const Log_Event | Task_LM_yield// Logged on calls to Task_yield;
extern const UInt | Task_numPriorities// Number of Task priorities supported. Default is 16;
DETAILS
The Task module makes available a set of functions that manipulate task objects accessed through pointers of type Handle. Tasks represent independent threads of control that conceptually execute functions in parallel within a single C program; in reality, concurrency is achieved by switching the processor from one task to another.
When you create a task, it is provided with its own run-time stack, used for storing local variables as well as for further nesting of function calls. Each stack must be large enough to handle normal subroutine calls and one task preemption context. A task preemption context is the context that gets saved when one task preempts another as a result of an interrupt thread readying a higher-priority task.
All tasks executing within a single program share a common set of global variables, accessed according to the standard rules of scope defined for C functions.
Each task is in one of five modes of execution at any point in time: running, ready, blocked, terminated, or inactive. By design, there is always one (and only one) task currently running, even if it is only the idle task managed internally by Task. The current task can be suspended from execution by calling certain Task functions, as well as functions provided by other modules like the Semaphore or Event Modules. The current task can also terminate its own execution. In either case, the processor is switched to the highest priority task that is ready to run.
You can assign numeric priorities to tasks. Tasks are readied for execution in strict priority order; tasks of the same priority are scheduled on a first-come, first-served basis. The priority of the currently running task is never lower than the priority of any ready task. Conversely, the running task is preempted and re-scheduled for execution whenever there exists some ready task of higher priority.
TASK DELETION
Any dynamically created task that is not in the Task_Mode_RUNNING state (ie not the currently running task) can be deleted using the delete API.
Task_delete() removes the task from all internal queues and calls Memory_free() to free the task object and stack. Memory_free() must acquire a lock to the memory before proceeding. If another task already holds a lock to the memory, then there is a context switch.
You can specify application-wide Delete hook functions that run whenever a task is deleted. See the discussion of Hook Functions below for details.
Note: Unless the mode of the deleted task is Task_Mode_TERMINATED, Task_delete should be called with care. For example, if the task has obtained exclusive access to a resource, deleting the task makes the resource unavailable.
Task_delete() constraints:
  • The task cannot be the currently executing task (Task_self()).
  • Task_delete cannot be called from a Swi or Hwi.
  • No check is performed to prevent Task_delete from being used on a statically-created object. If a program attempts to delete a task object that was created statically, the Memory_free() call will result in an assertion failure in its corresponding Heap manager, causing the application to exit.
STACK ALIGNMENT
Stack size parameters for both static and dynamic tasks are rounded up to the nearest integer multiple of a target-specific alignment requirement.
In the case of Task's which are created with a user-provided stack, both the base address and the stackSize are aligned. The base address is increased to the nearest aligned address. The stack size is decreased accordingly and then rounded down to the nearest integer multiple of the target-specific required alignment.
HOOK FUNCTIONS
Sets of hook functions can be specified for the Task module. Each set can contains these hook functions:
  • Register: A function called before any statically created tasks are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
  • Create: A function that is called when a task is created. This includes tasks that are created statically and those created dynamically using create or construct. The create hook is called outside of a Task_disable/enable block and before the task has been added to the ready list.
  • Ready: A function that is called when a task becomes ready to run. The ready hook is called from within a Task_disable/enable block with interrupts enabled.
  • Switch: A function that is called just before a task switch occurs. The 'prev' and 'next' task handles are passed to the Switch hook. 'prev' is set to NULL for the initial task switch that occurs during SYS/BIOS startup. The Switch hook is called from within a Task_disable/enable block with interrupts enabled.
  • Exit: A function that is called when a task exits using exit. The exit hook is passed the handle of the exiting task. The exit hook is called outside of a Task_disable/enable block and before the task has been removed from the kernel lists.
  • Delete: A function that is called when any task is deleted at run-time with delete. The delete hook is called outside of a Task_disable/enable block.
Hook functions can only be configured statically.
If you define more than one set of hook functions, all the functions of a particular type will be run when a Swi triggers that type of hook.
Register Function
The Register function is provided to allow a hook set to store its hookset ID. This id can be passed to setHookContext and getHookContext to set or get hookset-specific context. The Register function must be specified if the hook implementation needs to use setHookContext or getHookContext. The registerFxn hook function is called during system initialization before interrupts have been enabled.
  Void myRegisterFxn(Int id);
Create and Delete Functions
The create and delete functions are called whenever a Task is created or deleted. They are called with interrupts enabled (unless called at boot time or from main()).
  Void myCreateFxn(Task_Handle task, Error_Block *eb);

  Void myDeleteFxn(Task_Handle task);
Switch Function
If a switch function is specified, it is invoked just before the new task is switched to. The switch function is called with interrupts enabled.
This function can be used to save/restore additional task context (for example, external hardware registers), to check for task stack overflow, to monitor the time used by each task, etc.
  Void mySwitchFxn(Task_Handle prev, Task_Handle next);
To properly handle the switch to the first task your switchFxn should check for "prev == NULL" before using prev:
  Void mySwitchFxn(Task_Handle prev, Task_Handle next)
  {
      if (prev != NULL) {
          ...
      }
      ...
  }
Ready Function
If a ready function is specified, it is invoked whenever a task is made ready to run. The ready function is called with interrupts enabled (unless called at boot time or from main()).
  Void myReadyFxn(Task_Handle task);
Exit Function
If an exit function is specified, it is invoked when a task exits (via call to Task_exit() or when a task returns from its' main function). The Exit Function is called with interrupts enabled.
  Void myExitFxn(Task_Handle task);

Calling Context

Function | Hwi | Swi | Task | Main | Startup
create | N | N | Y | Y | N
disable | Y | Y | Y | Y | N
exit | N | N | Y | N | N
getIdleTask | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | Y
restore | Y | Y | Y | Y | N
self | Y | Y | Y | Y | N
sleep | N | N | Y | N | N
yield | Y | Y | Y | N | N
construct | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | N | N | Y | Y | N
getEnv | Y | Y | Y | Y | N
getHookContext | Y | Y | Y | Y | N
getMode | Y | Y | Y | Y | N
getPri | Y | Y | Y | Y | N
setEnv | Y | Y | Y | Y | N
setHookContext | Y | Y | Y | Y | N
setPri | Y | Y | Y | N | N
stat | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Task_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Task_Module_startupDone() returns FALSE).
enum Task_Mode
index URL

Task execution modes

C synopsis target-domain
typedef enum Task_Mode {
    Task_Mode_RUNNING,
    // Task is currently executing
    Task_Mode_READY,
    // Task is scheduled for execution
    Task_Mode_BLOCKED,
    // Task is suspended from execution
    Task_Mode_TERMINATED,
    // Task is terminated from execution
    Task_Mode_INACTIVE
    // Task is on inactive task list
} Task_Mode;
DETAILS
These enumerations are the range of modes or states that a task can be in. A task's current mode can be gotten using stat.
typedef Task_AllBlockedFuncPtr
index URL

"All Task Blocked" function type definition

C synopsis target-domain
typedef Void (*Task_AllBlockedFuncPtr)(Void);
typedef Task_FuncPtr
index URL

Task function type definition

C synopsis target-domain
typedef Void (*Task_FuncPtr)(UArg,UArg);
struct Task_HookSet
index URL

Task hook set type definition

C synopsis target-domain
typedef struct Task_HookSet {
    Void (*registerFxn)(Int);
    Void (*createFxn)(Task_Handle,Error_Block*);
    Void (*readyFxn)(Task_Handle);
    Void (*switchFxn)(Task_Handle,Task_Handle);
    Void (*exitFxn)(Task_Handle);
    Void (*deleteFxn)(Task_Handle);
} Task_HookSet;
DETAILS
Sets of hook functions can be specified for the Task module. See Hook Functions for details.
struct Task_Stat
index URL

Task Status Buffer

C synopsis target-domain
typedef struct Task_Stat {
    Int priority;
    // Task priority
    Ptr stack;
    // Task stack
    SizeT stackSize;
    // Task stack size
     IHeap_Handle stackHeap;
    // Heap used to alloc stack
    Ptr env;
    // Global environment struct
     Task_Mode mode;
    // Task's current mode
    Ptr sp;
    // Task's current stack pointer
    SizeT used;
    // max # of words used on stack
} Task_Stat;
DETAILS
Passed to and filled in by stat;
config Task_A_badPriority // module-wide
index URL

Asserted in Task_create

C synopsis target-domain
extern const Assert_Id Task_A_badPriority;
config Task_A_badTaskState // module-wide
index URL

Asserted in Task_delete

C synopsis target-domain
extern const Assert_Id Task_A_badTaskState;
config Task_A_badThreadType // module-wide
index URL

Asserted in Task_create and Task_delete

C synopsis target-domain
extern const Assert_Id Task_A_badThreadType;
config Task_A_badTimeout // module-wide
index URL

Asserted in Task_sleep

C synopsis target-domain
extern const Assert_Id Task_A_badTimeout;
config Task_A_noPendElem // module-wide
index URL

Asserted in Task_delete

C synopsis target-domain
extern const Assert_Id Task_A_noPendElem;
config Task_A_taskDisabled // module-wide
index URL

Asserted in Task_create

C synopsis target-domain
extern const Assert_Id Task_A_taskDisabled;
config Task_E_spOutOfBounds // module-wide
index URL

Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack

C synopsis target-domain
extern const Error_Id Task_E_spOutOfBounds;
DETAILS
This error is raised by kernel's stack checking function. This function checks the SPs before every task switch to make sure they point within the task's stack.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stack pointers.
config Task_E_stackOverflow // module-wide
index URL

Error raised when a stack overflow (or corruption) is detected

C synopsis target-domain
extern const Error_Id Task_E_stackOverflow;
DETAILS
This error is raised by kernel's stack checking function. This function checks the stacks before every task switch to make sure that reserved word at top of stack has not been modified.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stacks.
config Task_LD_block // module-wide
index URL

Logged when a task is blocked (ie Semaphore_pend())

C synopsis target-domain
extern const Log_Event Task_LD_block;
config Task_LD_exit // module-wide
index URL

Logged when Task functions fall thru the bottom or when Task_exit() is explicitly called

C synopsis target-domain
extern const Log_Event Task_LD_exit;
config Task_LD_ready // module-wide
index URL

Logged when a task is made ready to run (ie Semaphore_post())

C synopsis target-domain
extern const Log_Event Task_LD_ready;
config Task_LM_setPri // module-wide
index URL

Logged on calls to Task_setPri

C synopsis target-domain
extern const Log_Event Task_LM_setPri;
config Task_LM_sleep // module-wide
index URL

Logged on calls to Task_sleep

C synopsis target-domain
extern const Log_Event Task_LM_sleep;
config Task_LM_switch // module-wide
index URL

Logged on every task switch

C synopsis target-domain
extern const Log_Event Task_LM_switch;
config Task_LM_yield // module-wide
index URL

Logged on calls to Task_yield

C synopsis target-domain
extern const Log_Event Task_LM_yield;
config Task_allBlockedFunc // module-wide
index URL

Function to call while all tasks are blocked

C synopsis target-domain
extern const Task_AllBlockedFuncPtr Task_allBlockedFunc;
DETAILS
This function will be called repeatedly while no tasks are ready to run.
Ordinarily (in applications that have tasks ready to run at startup), the function will run in the context of the last task to block.
In an application where there are no tasks ready to run when BIOS_start() is called, the allBlockedFunc function is called within the BIOS_start() thread which runs on the system/ISR stack.
By default, allBlockedFunc is initialized to point to an internal function that simply returns.
By adding the following lines to the config script, the Idle functions will run whenever all tasks are blocked:
  Task.enableIdleTask = false;
  Task.allBlockedFunc = Idle.run;
SEE
enableIdleTask
CONSTRAINTS
The configured allBlockedFunc is designed to be called repeatedly. It must return in order for the task scheduler to check if all tasks are STILL blocked and if not, run the highest priority task currently ready to run.
The configured allBlockedFunc function is called with interrupts disabled. If your function must run with interrupts enabled, surround the body of your code with Hwi_enable()/Hwi_restore() function calls per the following example:
  Void yourFunc() {
      UInt hwiKey;

      hwiKey = Hwi_enable();

      ...         // your code here

      Hwi_restore(hwiKey);
  }
config Task_defaultStackHeap // module-wide
index URL

Default Mem heap used for all dynamically created task stacks

C synopsis target-domain
extern const IHeap_Handle Task_defaultStackHeap;
DETAILS
Default is null.
config Task_defaultStackSize // module-wide
index URL

Default stack size (in MAUs) used for all tasks

C synopsis target-domain
extern const SizeT Task_defaultStackSize;
DETAILS
Default is obtained from the family-specific TaskSupport module (e.g. ti.sysbios.family.arm.m3.TaskSupport, ti.sysbios.family.c62.TaskSupport).
config Task_deleteTerminatedTasks // module-wide
index URL

Automatically delete terminated tasks

C synopsis target-domain
extern const Bool Task_deleteTerminatedTasks;
DETAILS
If this feature is enabled, an Idle function is installed that deletes dynamically created Tasks that have terminated either by falling through their task function or by explicitly calling Task_exit().
A list of terminated Tasks that were created dynmically is maintained internally. Each invocation of the installed Idle function deletes the first Task on this list. This one-at-a-time process continues until the list is empty.
NOTE
This feature is disabled by default.
If this feature is enable, the user's application must not also delete terminated tasks or undefined and/or potentially catastrophic behavior will result.
config Task_hooks // module-wide
index URL

Const array that holds the HookSet objects

C synopsis target-domain
extern const Task_HookSet Task_hooks[length];
DETAILS
See Hook Functions for details about HookSets.
config Task_initStackFlag // module-wide
index URL

Initialize stack with known value for stack checking at runtime (see checkStackFlag)

C synopsis target-domain
extern const Bool Task_initStackFlag;
DETAILS
This is also useful for inspection of stack in debugger or core dump utilities. Default is true.
config Task_numPriorities // module-wide
index URL

Number of Task priorities supported. Default is 16

C synopsis target-domain
extern const UInt Task_numPriorities;
DETAILS
The maximum number of priorities supported is target specific and depends on the number of bits in a UInt data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For 28x, 55x, and MSP430 devices, the maximum number of priorities is 16.
Task_disable() // module-wide
index URL

Disable the task scheduler

C synopsis target-domain
UInt Task_disable();
RETURNS
key for use with restore
DETAILS
disable and restore control Task scheduling. disable disables all other Tasks from running until restore is called. Hardware and Software interrupts can still run.
disable and restore allow you to ensure that statements that must be performed together during critical processing are not preempted by other Tasks.
The value of the key returned is opaque to applications and is meant to be passed to Task_restore().
In the following example, the critical section is not preempted by any Tasks.
  key = Task_disable();
      `critical section`
  Task_restore(key);
You can also use disable and restore to create several Tasks and allow them to be invoked in priority order.
disable calls can be nested.
CONSTRAINTS
Do not call any function that can cause the current task to block within a disable/restore block. For example, Semaphore_pend (if timeout is non-zero), sleep, yield, and Memory_alloc can all cause blocking.
Task_exit() // module-wide
index URL

Terminate execution of the current task

C synopsis target-domain
Void Task_exit();
DETAILS
Task_exit terminates execution of the current task, changing its mode from Mode_RUNNING to Mode_TERMINATED. If all tasks have been terminated, or if all remaining tasks have their vitalTaskFlag attribute set to FALSE, then SYS/BIOS terminates the program as a whole by calling the function System_exit with a status code of 0.
Task_exit is automatically called whenever a task returns from its top-level function.
Exit Hooks (see exitFxn in HookSet) can be used to provide functions that run whenever a task is terminated. The exitFxn Hooks are called before the task has been blocked and marked Mode_TERMINATED. See Hook Functions for more information.
Any SYS/BIOS function can be called from an Exit Hook function.
Calling self within an Exit function returns the task being exited. Your Exit function declaration should be similar to the following:
  Void myExitFxn(Void);
A task switch occurs when calling Task_exit unless the program as a whole is terminated
CONSTRAINTS
Task_exit cannot be called from a Swi or Hwi.
Task_exit cannot be called from the program's main() function.
Task_getIdleTask() // module-wide
index URL

returns a handle to idle task object

C synopsis target-domain
Task_Handle Task_getIdleTask();
Task_restore() // module-wide
index URL

Restore Task scheduling state

C synopsis target-domain
Void Task_restore(UInt key);
ARGUMENTS
key — key to restore previous Task scheduler state
DETAILS
disable and restore control Task scheduling disable disables all other Tasks from running until restore is called. Hardware and Software interrupts can still run.
disable and restore allow you to ensure that statements that must be performed together during critical processing are not preempted.
In the following example, the critical section is not preempted by any Tasks.
  key = Task_disable();
      `critical section`
  Task_restore(key);
You can also use disable and restore to create several Tasks and allow them to be performed in priority order.
disable calls can be nested.
restore returns with interrupts enabled if the key unlocks the scheduler
CONSTRAINTS
Do not call any function that can cause the current task to block within a disable/restore block. For example, Semaphore_pend() (if timeout is non-zero), sleep, yield, and Memory_alloc can all cause blocking.
restore internally calls Hwi_enable() if the key passed to it results in the unlocking of the Task scheduler (ie if this is root Task_disable/Task_restore pair).
Task_self() // module-wide
index URL

Returns a handle to the currently executing Task object

C synopsis target-domain
Task_Handle Task_self();
RETURNS
address of currently executing task object
DETAILS
Task_self returns the object handle for the currently executing task. This function is useful when inspecting the object or when the current task changes its own priority through setPri.
No task switch occurs when calling Task_self.
Task_self will return NULL until Tasking is initiated at the end of BIOS_start().
Task_selfMacro() // module-wide
index URL

Returns a handle to the currently executing Task object

C synopsis target-domain
macro Task_Handle Task_selfMacro();
RETURNS
address of currently executing task object
DETAILS
Task_selfMacro is identical to self but is implemented as and inline macro.
Task_sleep() // module-wide
index URL

Delay execution of the current task

C synopsis target-domain
Void Task_sleep(UInt nticks);
ARGUMENTS
nticks — number of system clock ticks to sleep
DETAILS
Task_sleep changes the current task's mode from Mode_RUNNING to Mode_BLOCKED, and delays its execution for nticks increments of the system clock. The actual time delayed can be up to 1 system clock tick less than nticks due to granularity in system timekeeping and the time elapsed per tick is determined by Clock_tickPeriod.
After the specified period of time has elapsed, the task reverts to the Mode_READY mode and is scheduled for execution.
A task switch always occurs when calling Task_sleep if nticks > 0.
CONSTRAINTS
Task_sleep cannot be called from a Swi or Hwi, or within a disable / restore block.
Task_sleep cannot be called from the program's main() function.
Task_sleep should not be called from within an Idle function. Doing so prevents analysis tools from gathering run-time information.
nticks cannot be BIOS_WAIT_FOREVER.
Task_yield() // module-wide
index URL

Yield processor to equal priority task

C synopsis target-domain
Void Task_yield();
DETAILS
Task_yield yields the processor to another task of equal priority.
A task switch occurs when you call Task_yield if there is an equal priority task ready to run.
Tasks of higher priority preempt the currently running task without the need for a call to Task_yield. If only lower-priority tasks are ready to run when you call Task_yield, the current task continues to run. Control does not pass to a lower-priority task.
CONSTRAINTS
When called within an Hwi, the code sequence calling Task_yield must be invoked by the Hwi dispatcher.
Task_yield cannot be called from the program's main() function.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Task_Module_id();
// Get this module's unique id
Bool Task_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Task_Module_heap();
// The heap from which this module allocates memory
Bool Task_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Task_Module_getMask();
// Returns the diagnostics mask for this module
Void Task_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Task_Object Task_Object;
// Opaque internal representation of an instance object
typedef Task_Object *Task_Handle;
// Client reference to an instance object
typedef struct Task_Struct Task_Struct;
// Opaque client structure large enough to hold an instance object
Task_Handle Task_handle(Task_Struct *structP);
// Convert this instance structure pointer into an instance handle
Task_Struct *Task_struct(Task_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Task_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg0;
    // Task function argument. Default is 0
    UArg arg1;
    // Task function argument. Default is 0
    Ptr env;
    // Environment data struct
    Int priority;
    // Task priority (0 to numPriorities-1 or -1). Default is 1
    Ptr stack;
    // Task stack pointer. Default = null
     IHeap_Handle stackHeap;
    // Mem heap used for dynamically created task stack
    SizeT stackSize;
    // Task stack size in MAUs
    Bool vitalTaskFlag;
    // Exit system immediately when the last task with this flag set to TRUE has terminated
} Task_Params;
Void Task_Params_init(Task_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Task_arg0 // instance
index URL

Task function argument. Default is 0

C synopsis target-domain
struct Task_Params {
     ...
    UArg arg0;
config Task_arg1 // instance
index URL

Task function argument. Default is 0

C synopsis target-domain
struct Task_Params {
     ...
    UArg arg1;
config Task_env // instance
index URL

Environment data struct

C synopsis target-domain
struct Task_Params {
     ...
    Ptr env;
config Task_priority // instance
index URL

Task priority (0 to numPriorities-1 or -1). Default is 1

C synopsis target-domain
struct Task_Params {
     ...
    Int priority;
config Task_stack // instance
index URL

Task stack pointer. Default = null

C synopsis target-domain
struct Task_Params {
     ...
    Ptr stack;
DETAILS
Null indicates that the stack is to be allocated by create().
Example: To statically initialize "tsk0"'s stack to a literal address, use the following syntax:
      Program.global.tsk0.stack = $addr(literal);
config Task_stackHeap // instance
index URL

Mem heap used for dynamically created task stack

C synopsis target-domain
struct Task_Params {
     ...
     IHeap_Handle stackHeap;
DETAILS
The default value of NULL means that the module config defaultStackHeap is used.
config Task_stackSize // instance
index URL

Task stack size in MAUs

C synopsis target-domain
struct Task_Params {
     ...
    SizeT stackSize;
DETAILS
The default value of 0 means that the module config defaultStackSize is used.
config Task_vitalTaskFlag // instance
index URL

Exit system immediately when the last task with this flag set to TRUE has terminated

C synopsis target-domain
struct Task_Params {
     ...
    Bool vitalTaskFlag;
DETAILS
Default is true.
Instance Creation
index URL

C synopsis target-domain
Task_Handle Task_create(Task_FuncPtr fxn, const Task_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Task_construct(Task_Struct *structP, Task_FuncPtr fxn, const Task_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
fxn — Task Function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Task_create creates a new task object. If successful, Task_create returns the handle of the new task object. If unsuccessful, Task_create returns NULL unless it aborts.
The fxn parameter uses the FuncPtr type to pass a pointer to the function the Task object should run. For example, if myFxn is a function in your program, your C code can create a Task object to call that function as follows:
  Task_Params taskParams;

  // Create task with priority 15
  Task_Params_init(&taskParams);
  taskParams.stackSize = 512;
  taskParams.priority = 15;
  Task_create((Task_FuncPtr)myFxn, &taskParams, &eb);
The following statements statically create a task in the configuration file:
  var params = new Task.Params;
  params.instance.name = "tsk0";
  params.arg0 = 1;
  params.arg1 = 2;
  params.priority = 1;
  Task.create('&tsk0_func', params);
If NULL is passed instead of a pointer to an actual Task_Params struct, a default set of parameters is used. The "eb" is an error block that you can use to handle errors that may occur during Task object creation.
The newly created task is placed in Mode_READY mode, and is scheduled to begin concurrent execution of the following function call:
  (*fxn)(arg1, arg2);
As a result of being made ready to run, the task runs any application-wide Ready functions that have been specified.
Task_exit is automatically called if and when the task returns from fxn.
Create Hook Functions
You can specify application-wide Create hook functions in your config file that run whenever a task is created. This includes tasks that are created statically and those created dynamically using Task_create.
For Task objects created statically, Create functions are called during the Task module initialization phase of the program startup process prior to main().
For Task objects created dynamically, Create functions are called after the task handle has been initialized but before the task has been placed on its ready queue.
Any SYS/BIOS function can be called from Create functions. SYS/BIOS passes the task handle of the task being created to each of the Create functions.
All Create function declarations should be similar to this:
  Void myCreateFxn(Task_Handle task);
CONSTRAINTS
  • The fxn parameter and the name attribute cannot be NULL.
  • The priority attribute must be less than or equal to (numPriorities - 1) and greater than or equal to one (1) (priority 0 is owned by the Idle task).
  • The priority can be less than zero (0) for tasks that should not execute.
  • The stackHeap attribute must identify a valid memory Heap.
Instance Deletion
index URL

C synopsis target-domain
Void Task_delete(Task_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Task_destruct(Task_Struct *structP);
// Finalize the instance object inside the provided structure
Task_getEnv() // instance
index URL

Get task environment pointer

C synopsis target-domain
Ptr Task_getEnv(Task_Handle handle);
ARGUMENTS
handle — handle of a previously-created Task instance object
RETURNS
task environment pointer
DETAILS
Task_getEnv returns the environment pointer of the specified task. The environment pointer references an arbitrary application-defined data structure.
If your program uses multiple hook sets, getHookContext allows you to get environment pointers you have set for a particular hook set and Task object combination.
Task_getHookContext() // instance
index URL

Get hook set's context for a task

C synopsis target-domain
Ptr Task_getHookContext(Task_Handle handle, Int id);
ARGUMENTS
handle — handle of a previously-created Task instance object
id — hook set ID
RETURNS
hook set context for task
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Task_Handle myTask;
  Int myHookSetId1;

  pEnv = Task_getHookContext(task, myHookSetId1);

  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
                (ULong)pEnv, (ULong)Timestamp_get32());

  Task_setHookContext(task, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
Task_getMode() // instance
index URL

Retrieve the Mode of a task

C synopsis target-domain
Task_Mode Task_getMode(Task_Handle handle);
ARGUMENTS
handle — handle of a previously-created Task instance object
Task_getPri() // instance
index URL

Get task priority

C synopsis target-domain
Int Task_getPri(Task_Handle handle);
ARGUMENTS
handle — handle of a previously-created Task instance object
RETURNS
task priority
DETAILS
Task_getPri returns the priority of the referenced task.
Task_setEnv() // instance
index URL

Set task environment

C synopsis target-domain
Void Task_setEnv(Task_Handle handle, Ptr env);
ARGUMENTS
handle — handle of a previously-created Task instance object
env — task environment pointer
DETAILS
Task_setEnv sets the task environment pointer to env. The environment pointer references an arbitrary application-defined data structure.
If your program uses multiple hook sets, setHookContext allows you to set environment pointers for any hook set and Task object combination.
Task_setHookContext() // instance
index URL

Set hook instance's context for a task

C synopsis target-domain
Void Task_setHookContext(Task_Handle handle, Int id, Ptr hookContext);
ARGUMENTS
handle — handle of a previously-created Task instance object
id — hook set ID
hookContext — value to write to context
DETAILS
For example, this C code gets the HookContext, prints it, and sets a new value for the HookContext.
  Ptr pEnv;
  Task_Handle myTask;
  Int myHookSetId1;

  pEnv = Task_getHookContext(task, myHookSetId1);

  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
                (ULong)pEnv, (ULong)Timestamp_get32());

  Task_setHookContext(task, myHookSetId1, (Ptr)0xc0de1);
See Hook Functions for more details.
Task_setPri() // instance
index URL

Set a task's priority

C synopsis target-domain
UInt Task_setPri(Task_Handle handle, Int newpri);
ARGUMENTS
handle — handle of a previously-created Task instance object
newpri — task's new priority
RETURNS
task's old priority
DETAILS
Task_setpri sets the execution priority of task to newpri, and returns that task's old priority value. Raising or lowering a task's priority does not necessarily force preemption and re-scheduling of the caller: tasks in the Mode_BLOCKED mode remain suspended despite a change in priority; and tasks in the Mode_READY mode gain control only if their new priority is greater than that of the currently executing task.
The maximum value of newpri is (numPriorities - 1). The minimum value of newpri is one (1) (The Idle task owns priority 0). If newpri is less than 0, the task is barred from further execution until its priority is raised at a later time by another task; if newpri equals (numPriorities - 1), execution of the task effectively locks out all other program activity, except for the handling of interrupts.
The current task can change its own priority (and possibly preempt its execution) by passing the output of self as the value of the task parameter.
A context switch occurs when calling Task_setpri if a currently running task priority is set lower than the priority of another currently ready task, or if another ready task is made to have a higher priority than the currently running task.
Task_setpri can be used for mutual exclusion.
If a task's new priority is different than its previous priority, then its relative placement in its new ready task priority queue can be different than the one it was removed from. This can effect the relative order in which it becomes the running task.
The effected task is placed at the head of its new priority queue if it is the currently running task. Otherwise it is placed at at the end of its new task priority queue.
CONSTRAINTS
newpri must be less than or equal to (numPriorities - 1).
The task cannot be in the Mode_TERMINATED mode.
The new priority should not be zero (0). This priority level is reserved for the Idle task.
Task_stat() // instance
index URL

Retrieve the status of a task

C synopsis target-domain
Void Task_stat(Task_Handle handle, Task_Stat *statbuf);
ARGUMENTS
handle — handle of a previously-created Task instance object
statbuf — pointer to task status structure
DETAILS
Task_stat retrieves attribute values and status information about a task.
Status information is returned through statbuf, which references a structure of type Stat.
When a task is preempted by a software or hardware interrupt, the task execution mode returned for that task by Task_stat is still Mode_RUNNING because the task runs when the preemption ends.
The current task can inquire about itself by passing the output of self as the first argument to Task_stat. However, the task stack pointer (sp) in the Stat structure is the value from the previous context switch.
Task_stat has a non-deterministic execution time. As such, it is not recommended to call this API from Swis or Hwis.
CONSTRAINTS
statbuf cannot be NULL;
Instance Built-Ins
index URL

C synopsis target-domain
Int Task_Object_count();
// The number of statically-created instance objects
Task_Handle Task_Object_get(Task_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Task_Handle Task_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Task_Handle Task_Object_next(Task_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Task_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Task_Handle_label(Task_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Task_Handle_name(Task_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/knl/Task.xdc
var Task = xdc.useModule('ti.sysbios.knl.Task');
module-wide constants & types
    values of type Task.Mode// Task execution modes
        const Task.Mode_RUNNING// Task is currently executing;
        const Task.Mode_READY// Task is scheduled for execution;
        const Task.Mode_BLOCKED// Task is suspended from execution;
        const Task.Mode_TERMINATED// Task is terminated from execution;
        const Task.Mode_INACTIVE// Task is on inactive task list;
    var obj = new Task.HookSet// Task hook set type definition;
        obj.registerFxn = Void(*)(Int) ...
        obj.createFxn = Void(*)(Task.Handle,Error.Block*) ...
        obj.readyFxn = Void(*)(Task.Handle) ...
        obj.switchFxn = Void(*)(Task.Handle,Task.Handle) ...
        obj.exitFxn = Void(*)(Task.Handle) ...
        obj.deleteFxn = Void(*)(Task.Handle) ...
    var obj = new Task.Stat// Task Status Buffer;
        obj.priority// Task priority = Int ...
        obj.stack// Task stack = Ptr ...
        obj.stackSize// Task stack size = SizeT ...
        obj.stackHeap// Heap used to alloc stack = IHeap.Handle ...
        obj.env// Global environment struct = Ptr ...
        obj.mode// Task's current mode = Task.Mode ...
        obj.sp// Task's current stack pointer = Ptr ...
        obj.used// max # of words used on stack = SizeT ...
module-wide config parameters
     Task.A_badPriority// Asserted in Task_create = Assert.Desc {
        msg: "A_badPriority: An invalid task priority was used."
    };
     Task.A_badTaskState// Asserted in Task_delete = Assert.Desc {
        msg: "A_badTaskState: Can't delete a task in RUNNING state."
    };
     Task.A_badThreadType// Asserted in Task_create and Task_delete = Assert.Desc {
        msg: "A_badThreadType: Cannot create/delete a task from Hwi or Swi thread."
    };
     Task.A_badTimeout// Asserted in Task_sleep = Assert.Desc {
        msg: "A_badTimeout: Can't sleep FOREVER."
    };
     Task.A_noPendElem// Asserted in Task_delete = Assert.Desc {
        msg: "A_noPendElem: Not enough info to delete BLOCKED task."
    };
     Task.A_taskDisabled// Asserted in Task_create = Assert.Desc {
        msg: "A_taskDisabled: Cannot create a task when tasking is disabled."
    };
     Task.E_spOutOfBounds// Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack = Error.Desc {
        msg: "E_spOutOfBounds: Task 0x%x stack error, SP = 0x%x."
    };
     Task.E_stackOverflow// Error raised when a stack overflow (or corruption) is detected = Error.Desc {
        msg: "E_stackOverflow: Task 0x%x stack overflow."
    };
     Task.LD_block// Logged when a task is blocked (ie Semaphore_pend()) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_block: tsk: 0x%x, func: 0x%x"
    };
     Task.LD_exit// Logged when Task functions fall thru the bottom or when Task_exit() is explicitly called = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_exit: tsk: 0x%x, func: 0x%x"
    };
     Task.LD_ready// Logged when a task is made ready to run (ie Semaphore_post()) = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_ready: tsk: 0x%x, func: 0x%x, pri: %d"
    };
     Task.LM_setPri// Logged on calls to Task_setPri = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_setPri: tsk: 0x%x, func: 0x%x, oldPri: %d, newPri %d"
    };
     Task.LM_sleep// Logged on calls to Task_sleep = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_sleep: tsk: 0x%x, func: 0x%x, timeout: %d"
    };
     Task.LM_switch// Logged on every task switch = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_switch: oldtsk: 0x%x, oldfunc: 0x%x, newtsk: 0x%x, newfunc: 0x%x"
    };
     Task.LM_yield// Logged on calls to Task_yield = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_yield: tsk: 0x%x, func: 0x%x, currThread: %d"
    };
     Task.allBlockedFunc// Function to call while all tasks are blocked = Void(*)(Void) undefined;
     Task.defaultStackHeap// Default Mem heap used for all dynamically created task stacks = IHeap.Handle undefined;
     Task.defaultStackSize// Default stack size (in MAUs) used for all tasks = SizeT undefined;
     Task.deleteTerminatedTasks// Automatically delete terminated tasks = Bool false;
     Task.hooks// Const array that holds the HookSet objects = Task.HookSet[length] [ ];
     Task.initStackFlag// Initialize stack with known value for stack checking at runtime (see checkStackFlag) = Bool true;
     Task.numPriorities// Number of Task priorities supported. Default is 16 = UInt 16;
     Task.checkStackFlag// Check 'from' and 'to' task stacks before task context switch = Bool true;
     Task.common$// Common module configuration parameters = Types.Common$ undefined;
     Task.defaultStackSection// Default memory section used for all statically created task stacks = String undefined;
     Task.enableIdleTask// Create a task (of priority 0) to run the Idle functions in = Bool true;
     Task.idleTaskStackSection// Idle task stack section = String undefined;
     Task.idleTaskStackSize// Idle task stack size in MAUs = SizeT undefined;
     Task.idleTaskVitalTaskFlag// Idle task's vitalTaskFlag. (see vitalTaskFlag) = Bool true;
module-wide functions
     Task.addHookSet// addHookSet is used in a config file to add a hook set(Task.HookSet hook) returns Void
     Task.getNickName// (Any tskView) returns String
per-instance config parameters
    var params = new Task.Params// Instance config-params object;
        params.arg0// Task function argument. Default is 0 = UArg 0;
        params.arg1// Task function argument. Default is 0 = UArg 0;
        params.env// Environment data struct = Ptr null;
        params.priority// Task priority (0 to numPriorities-1 or -1). Default is 1 = Int 1;
        params.stack// Task stack pointer. Default = null = Ptr null;
        params.stackHeap// Mem heap used for dynamically created task stack = IHeap.Handle null;
        params.stackSection// Mem section used for statically created task stacks = String undefined;
        params.stackSize// Task stack size in MAUs = SizeT 0;
        params.vitalTaskFlag// Exit system immediately when the last task with this flag set to TRUE has terminated = Bool true;
per-instance creation
    var inst = Task.create// Create an instance-object(Void(*)(UArg,UArg) fxn, params);
enum Task.Mode
index URL

Task execution modes

XDCscript usage meta-domain
values of type Task.Mode
    const Task.Mode_RUNNING;
    // Task is currently executing
    const Task.Mode_READY;
    // Task is scheduled for execution
    const Task.Mode_BLOCKED;
    // Task is suspended from execution
    const Task.Mode_TERMINATED;
    // Task is terminated from execution
    const Task.Mode_INACTIVE;
    // Task is on inactive task list
DETAILS
These enumerations are the range of modes or states that a task can be in. A task's current mode can be gotten using stat.
C SYNOPSIS
Task_Mode
struct Task.HookSet
index URL

Task hook set type definition

XDCscript usage meta-domain
var obj = new Task.HookSet;
    obj.registerFxn = Void(*)(Int) ...
    obj.createFxn = Void(*)(Task.Handle,Error.Block*) ...
    obj.readyFxn = Void(*)(Task.Handle) ...
    obj.switchFxn = Void(*)(Task.Handle,Task.Handle) ...
    obj.exitFxn = Void(*)(Task.Handle) ...
    obj.deleteFxn = Void(*)(Task.Handle) ...
DETAILS
Sets of hook functions can be specified for the Task module. See Hook Functions for details.
C SYNOPSIS
Task_HookSet
struct Task.Stat
index URL

Task Status Buffer

XDCscript usage meta-domain
var obj = new Task.Stat;
    obj.priority = Int ...
    // Task priority
    obj.stack = Ptr ...
    // Task stack
    obj.stackSize = SizeT ...
    // Task stack size
    obj.stackHeap = IHeap.Handle ...
    // Heap used to alloc stack
    obj.env = Ptr ...
    // Global environment struct
    obj.mode = Task.Mode ...
    // Task's current mode
    obj.sp = Ptr ...
    // Task's current stack pointer
    obj.used = SizeT ...
    // max # of words used on stack
DETAILS
Passed to and filled in by stat;
C SYNOPSIS
Task_Stat
config Task.A_badPriority // module-wide
index URL

Asserted in Task_create

XDCscript usage meta-domain
Task.A_badPriority = Assert.Desc {
    msg: "A_badPriority: An invalid task priority was used."
};
C SYNOPSIS
Task_A_badPriority
config Task.A_badTaskState // module-wide
index URL

Asserted in Task_delete

XDCscript usage meta-domain
Task.A_badTaskState = Assert.Desc {
    msg: "A_badTaskState: Can't delete a task in RUNNING state."
};
C SYNOPSIS
Task_A_badTaskState
config Task.A_badThreadType // module-wide
index URL

Asserted in Task_create and Task_delete

XDCscript usage meta-domain
Task.A_badThreadType = Assert.Desc {
    msg: "A_badThreadType: Cannot create/delete a task from Hwi or Swi thread."
};
C SYNOPSIS
Task_A_badThreadType
config Task.A_badTimeout // module-wide
index URL

Asserted in Task_sleep

XDCscript usage meta-domain
Task.A_badTimeout = Assert.Desc {
    msg: "A_badTimeout: Can't sleep FOREVER."
};
C SYNOPSIS
Task_A_badTimeout
config Task.A_noPendElem // module-wide
index URL

Asserted in Task_delete

XDCscript usage meta-domain
Task.A_noPendElem = Assert.Desc {
    msg: "A_noPendElem: Not enough info to delete BLOCKED task."
};
C SYNOPSIS
Task_A_noPendElem
config Task.A_taskDisabled // module-wide
index URL

Asserted in Task_create

XDCscript usage meta-domain
Task.A_taskDisabled = Assert.Desc {
    msg: "A_taskDisabled: Cannot create a task when tasking is disabled."
};
C SYNOPSIS
Task_A_taskDisabled
config Task.E_spOutOfBounds // module-wide
index URL

Error raised when a task's stack pointer (SP) does not point somewhere within the task's stack

XDCscript usage meta-domain
Task.E_spOutOfBounds = Error.Desc {
    msg: "E_spOutOfBounds: Task 0x%x stack error, SP = 0x%x."
};
DETAILS
This error is raised by kernel's stack checking function. This function checks the SPs before every task switch to make sure they point within the task's stack.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stack pointers.
C SYNOPSIS
Task_E_spOutOfBounds
config Task.E_stackOverflow // module-wide
index URL

Error raised when a stack overflow (or corruption) is detected

XDCscript usage meta-domain
Task.E_stackOverflow = Error.Desc {
    msg: "E_stackOverflow: Task 0x%x stack overflow."
};
DETAILS
This error is raised by kernel's stack checking function. This function checks the stacks before every task switch to make sure that reserved word at top of stack has not been modified.
The stack checking logic is enabled by the initStackFlag and checkStackFlag configuration parameters. If both of these flags are set to true, the kernel will validate the stacks.
C SYNOPSIS
Task_E_stackOverflow
config Task.LD_block // module-wide
index URL

Logged when a task is blocked (ie Semaphore_pend())

XDCscript usage meta-domain
Task.LD_block = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_block: tsk: 0x%x, func: 0x%x"
};
C SYNOPSIS
Task_LD_block
config Task.LD_exit // module-wide
index URL

Logged when Task functions fall thru the bottom or when Task_exit() is explicitly called

XDCscript usage meta-domain
Task.LD_exit = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_exit: tsk: 0x%x, func: 0x%x"
};
C SYNOPSIS
Task_LD_exit
config Task.LD_ready // module-wide
index URL

Logged when a task is made ready to run (ie Semaphore_post())

XDCscript usage meta-domain
Task.LD_ready = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_ready: tsk: 0x%x, func: 0x%x, pri: %d"
};
C SYNOPSIS
Task_LD_ready
config Task.LM_setPri // module-wide
index URL

Logged on calls to Task_setPri

XDCscript usage meta-domain
Task.LM_setPri = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_setPri: tsk: 0x%x, func: 0x%x, oldPri: %d, newPri %d"
};
C SYNOPSIS
Task_LM_setPri
config Task.LM_sleep // module-wide
index URL

Logged on calls to Task_sleep

XDCscript usage meta-domain
Task.LM_sleep = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_sleep: tsk: 0x%x, func: 0x%x, timeout: %d"
};
C SYNOPSIS
Task_LM_sleep
config Task.LM_switch // module-wide
index URL

Logged on every task switch

XDCscript usage meta-domain
Task.LM_switch = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_switch: oldtsk: 0x%x, oldfunc: 0x%x, newtsk: 0x%x, newfunc: 0x%x"
};
C SYNOPSIS
Task_LM_switch
config Task.LM_yield // module-wide
index URL

Logged on calls to Task_yield

XDCscript usage meta-domain
Task.LM_yield = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_yield: tsk: 0x%x, func: 0x%x, currThread: %d"
};
C SYNOPSIS
Task_LM_yield
config Task.allBlockedFunc // module-wide
index URL

Function to call while all tasks are blocked

XDCscript usage meta-domain
Task.allBlockedFunc = Void(*)(Void) undefined;
DETAILS
This function will be called repeatedly while no tasks are ready to run.
Ordinarily (in applications that have tasks ready to run at startup), the function will run in the context of the last task to block.
In an application where there are no tasks ready to run when BIOS_start() is called, the allBlockedFunc function is called within the BIOS_start() thread which runs on the system/ISR stack.
By default, allBlockedFunc is initialized to point to an internal function that simply returns.
By adding the following lines to the config script, the Idle functions will run whenever all tasks are blocked:
  Task.enableIdleTask = false;
  Task.allBlockedFunc = Idle.run;
SEE
enableIdleTask
CONSTRAINTS
The configured allBlockedFunc is designed to be called repeatedly. It must return in order for the task scheduler to check if all tasks are STILL blocked and if not, run the highest priority task currently ready to run.
The configured allBlockedFunc function is called with interrupts disabled. If your function must run with interrupts enabled, surround the body of your code with Hwi_enable()/Hwi_restore() function calls per the following example:
  Void yourFunc() {
      UInt hwiKey;

      hwiKey = Hwi_enable();

      ...         // your code here

      Hwi_restore(hwiKey);
  }
C SYNOPSIS
Task_allBlockedFunc
config Task.defaultStackHeap // module-wide
index URL

Default Mem heap used for all dynamically created task stacks

XDCscript usage meta-domain
Task.defaultStackHeap = IHeap.Handle undefined;
DETAILS
Default is null.
C SYNOPSIS
Task_defaultStackHeap
config Task.defaultStackSize // module-wide
index URL

Default stack size (in MAUs) used for all tasks

XDCscript usage meta-domain
Task.defaultStackSize = SizeT undefined;
DETAILS
Default is obtained from the family-specific TaskSupport module (e.g. ti.sysbios.family.arm.m3.TaskSupport, ti.sysbios.family.c62.TaskSupport).
C SYNOPSIS
Task_defaultStackSize
config Task.deleteTerminatedTasks // module-wide
index URL

Automatically delete terminated tasks

XDCscript usage meta-domain
Task.deleteTerminatedTasks = Bool false;
DETAILS
If this feature is enabled, an Idle function is installed that deletes dynamically created Tasks that have terminated either by falling through their task function or by explicitly calling Task_exit().
A list of terminated Tasks that were created dynmically is maintained internally. Each invocation of the installed Idle function deletes the first Task on this list. This one-at-a-time process continues until the list is empty.
NOTE
This feature is disabled by default.
If this feature is enable, the user's application must not also delete terminated tasks or undefined and/or potentially catastrophic behavior will result.
C SYNOPSIS
Task_deleteTerminatedTasks
config Task.hooks // module-wide
index URL

Const array that holds the HookSet objects

XDCscript usage meta-domain
Task.hooks = Task.HookSet[length] [ ];
DETAILS
See Hook Functions for details about HookSets.
C SYNOPSIS
Task_hooks
config Task.initStackFlag // module-wide
index URL

Initialize stack with known value for stack checking at runtime (see checkStackFlag)

XDCscript usage meta-domain
Task.initStackFlag = Bool true;
DETAILS
This is also useful for inspection of stack in debugger or core dump utilities. Default is true.
C SYNOPSIS
Task_initStackFlag
config Task.numPriorities // module-wide
index URL

Number of Task priorities supported. Default is 16

XDCscript usage meta-domain
Task.numPriorities = UInt 16;
DETAILS
The maximum number of priorities supported is target specific and depends on the number of bits in a UInt data type. For 6x and ARM devices the maximum number of priorities is therefore 32. For 28x, 55x, and MSP430 devices, the maximum number of priorities is 16.
C SYNOPSIS
Task_numPriorities
metaonly config Task.checkStackFlag // module-wide
index URL

Check 'from' and 'to' task stacks before task context switch

XDCscript usage meta-domain
Task.checkStackFlag = Bool true;
DETAILS
The check consists of testing the top of stack value against its initial value (see initStackFlag). If it is no longer at this value, the assumption is that the task has overrun its stack. If the test fails, then the E_stackOverflow error is raised.
Runtime stack checking is only performed if initStackFlag is also true.
Default is true.
To enable or disable full stack checking, you should set both this flag and the ti.sysbios.hal.Hwi.checkStackFlag.
metaonly config Task.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Task.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Task.defaultStackSection // module-wide
index URL

Default memory section used for all statically created task stacks

XDCscript usage meta-domain
Task.defaultStackSection = String undefined;
DETAILS
The default stack section name is target/device specific. For C6x targets it is ".far:taskStackSection". For C28x targets it is ".taskStackSection". For all other targets it is ".bss:taskStackSection".
By default, all statically created task stacks are grouped together into the defaultStackSection and placed where ever the target specific defaultStackSection base section name (ie .bss, .far, .ebss) is placed.
To place all task stacks into a different memory segment, add the following to your config script:
  Program.sectMap[Task.defaultStackSection] = new Program.SectionSpec();
  Program.sectMap[Task.defaultStackSection].loadSegment =
                   "yourMemorySegment";
To group all task stacks into a different section AND place that section into a specific memory segment, add the following to your config script:
  Task.defaultStackSection = ".yourSectionName";
  Program.sectMap[Task.defaultStackSection] = new Program.SectionSpec();
  Program.sectMap[Task.defaultStackSection].loadSegment =
                   "yourMemorySegment";
Where "yourSectionName" can be just about anything, and "yourMemorySegment" must be a memory segment defined for your board.
metaonly config Task.enableIdleTask // module-wide
index URL

Create a task (of priority 0) to run the Idle functions in

XDCscript usage meta-domain
Task.enableIdleTask = Bool true;
DETAILS
When set to true, a task is created that continuously calls the Idle_run() function, which, in turn calls each of the configured Idle functions.
When set to false, no Idle Task is created and it is up to the user to call the Idle_run() function if the configured Idle functions need to be run. Or, by adding the following lines to the config script, the Idle functions will run whenever all tasks are blocked (Task.allBlockedFunc):
  Task.enableIdleTask = false;
  Task.allBlockedFunc = Idle.run;
Default is true.
SEE
idleTaskStackSize, idleTaskStackSection, idleTaskVitalTaskFlag, allBlockedFunc
metaonly config Task.idleTaskStackSection // module-wide
index URL

Idle task stack section

XDCscript usage meta-domain
Task.idleTaskStackSection = String undefined;
DETAILS
Default is inherited from module config defaultStackSection;
metaonly config Task.idleTaskStackSize // module-wide
index URL

Idle task stack size in MAUs

XDCscript usage meta-domain
Task.idleTaskStackSize = SizeT undefined;
DETAILS
Default is inherited from module config defaultStackSize.
metaonly config Task.idleTaskVitalTaskFlag // module-wide
index URL

Idle task's vitalTaskFlag. (see vitalTaskFlag)

XDCscript usage meta-domain
Task.idleTaskVitalTaskFlag = Bool true;
DETAILS
Default is true.
metaonly Task.addHookSet() // module-wide
index URL

addHookSet is used in a config file to add a hook set

XDCscript usage meta-domain
Task.addHookSet(Task.HookSet hook) returns Void
ARGUMENTS
hook — structure of type HookSet
DETAILS
Configures a set of hook functions for the Task module. Each set contains these hook functions:
  • Register: A function called before any statically created tasks are initialized at runtime. The register hook is called at boot time before main() and before interrupts are enabled.
  • Create: A function that is called when a task is created. This includes tasks that are created statically and those created dynamically using create or construct. The create hook is called outside of a Task_disable/enable block and before the task has been added to the ready list.
  • Ready: A function that is called when a task becomes ready to run. The ready hook is called from within a Task_disable/enable block with interrupts enabled.
  • Switch: A function that is called just before a task switch occurs. The 'prev' and 'next' task handles are passed to the Switch hook. 'prev' is set to NULL for the initial task switch that occurs during SYS/BIOS startup. The Switch hook is called from within a Task_disable/enable block with interrupts enabled.
  • Exit: A function that is called when a task exits using exit. The exit hook is passed the handle of the exiting task. The exit hook is called outside of a Task_disable/enable block and before the task has been removed from the kernel lists.
  • Delete: A function that is called when any task is deleted at run-time with delete. The delete hook is called outside of a Task_disable/enable block.
Hook functions can only be configured statically.
See Hook Functions for more details.
HookSet structure elements may be omitted, in which case those elements will not exist.
For example, the following configuration code defines a HookSet:
  // Hook Set 1
  Task.addHookSet({
     registerFxn: '&myRegister1',
     createFxn:   '&myCreate1',
     readyFxn:    '&myReady1',
     switchFxn:   '&mySwitch1',
     exitFxn:     '&myExit1',
     deleteFxn:   '&myDelete1'
  });
metaonly Task.getNickName() // module-wide
index URL
XDCscript usage meta-domain
Task.getNickName(Any tskView) returns String
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Task.Params;
// Instance config-params object
    params.arg0 = UArg 0;
    // Task function argument. Default is 0
    params.arg1 = UArg 0;
    // Task function argument. Default is 0
    params.env = Ptr null;
    // Environment data struct
    params.priority = Int 1;
    // Task priority (0 to numPriorities-1 or -1). Default is 1
    params.stack = Ptr null;
    // Task stack pointer. Default = null
    params.stackHeap = IHeap.Handle null;
    // Mem heap used for dynamically created task stack
    params.stackSection = String undefined;
    // Mem section used for statically created task stacks
    params.stackSize = SizeT 0;
    // Task stack size in MAUs
    params.vitalTaskFlag = Bool true;
    // Exit system immediately when the last task with this flag set to TRUE has terminated
config Task.arg0 // instance
index URL

Task function argument. Default is 0

XDCscript usage meta-domain
var params = new Task.Params;
...
params.arg0 = UArg 0;
C SYNOPSIS
null
config Task.arg1 // instance
index URL

Task function argument. Default is 0

XDCscript usage meta-domain
var params = new Task.Params;
...
params.arg1 = UArg 0;
C SYNOPSIS
null
config Task.env // instance
index URL

Environment data struct

XDCscript usage meta-domain
var params = new Task.Params;
...
params.env = Ptr null;
C SYNOPSIS
null
config Task.priority // instance
index URL

Task priority (0 to numPriorities-1 or -1). Default is 1

XDCscript usage meta-domain
var params = new Task.Params;
...
params.priority = Int 1;
C SYNOPSIS
null
config Task.stack // instance
index URL

Task stack pointer. Default = null

XDCscript usage meta-domain
var params = new Task.Params;
...
params.stack = Ptr null;
DETAILS
Null indicates that the stack is to be allocated by create().
Example: To statically initialize "tsk0"'s stack to a literal address, use the following syntax:
      Program.global.tsk0.stack = $addr(literal);
C SYNOPSIS
null
config Task.stackHeap // instance
index URL

Mem heap used for dynamically created task stack

XDCscript usage meta-domain
var params = new Task.Params;
...
params.stackHeap = IHeap.Handle null;
DETAILS
The default value of NULL means that the module config defaultStackHeap is used.
C SYNOPSIS
null
config Task.stackSize // instance
index URL

Task stack size in MAUs

XDCscript usage meta-domain
var params = new Task.Params;
...
params.stackSize = SizeT 0;
DETAILS
The default value of 0 means that the module config defaultStackSize is used.
C SYNOPSIS
null
config Task.vitalTaskFlag // instance
index URL

Exit system immediately when the last task with this flag set to TRUE has terminated

XDCscript usage meta-domain
var params = new Task.Params;
...
params.vitalTaskFlag = Bool true;
DETAILS
Default is true.
C SYNOPSIS
null
metaonly config Task.stackSection // instance
index URL

Mem section used for statically created task stacks

XDCscript usage meta-domain
var params = new Task.Params;
...
params.stackSection = String undefined;
DETAILS
Default is inherited from module config defaultStackSection.
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Task.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Task.create(Void(*)(UArg,UArg) fxn, params);
// Create an instance-object
ARGUMENTS
fxn — Task Function
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Task_create creates a new task object. If successful, Task_create returns the handle of the new task object. If unsuccessful, Task_create returns NULL unless it aborts.
The fxn parameter uses the FuncPtr type to pass a pointer to the function the Task object should run. For example, if myFxn is a function in your program, your C code can create a Task object to call that function as follows:
  Task_Params taskParams;

  // Create task with priority 15
  Task_Params_init(&taskParams);
  taskParams.stackSize = 512;
  taskParams.priority = 15;
  Task_create((Task_FuncPtr)myFxn, &taskParams, &eb);
The following statements statically create a task in the configuration file:
  var params = new Task.Params;
  params.instance.name = "tsk0";
  params.arg0 = 1;
  params.arg1 = 2;
  params.priority = 1;
  Task.create('&tsk0_func', params);
If NULL is passed instead of a pointer to an actual Task_Params struct, a default set of parameters is used. The "eb" is an error block that you can use to handle errors that may occur during Task object creation.
The newly created task is placed in Mode_READY mode, and is scheduled to begin concurrent execution of the following function call:
  (*fxn)(arg1, arg2);
As a result of being made ready to run, the task runs any application-wide Ready functions that have been specified.
Task_exit is automatically called if and when the task returns from fxn.
Create Hook Functions
You can specify application-wide Create hook functions in your config file that run whenever a task is created. This includes tasks that are created statically and those created dynamically using Task_create.
For Task objects created statically, Create functions are called during the Task module initialization phase of the program startup process prior to main().
For Task objects created dynamically, Create functions are called after the task handle has been initialized but before the task has been placed on its ready queue.
Any SYS/BIOS function can be called from Create functions. SYS/BIOS passes the task handle of the task being created to each of the Create functions.
All Create function declarations should be similar to this:
  Void myCreateFxn(Task_Handle task);
CONSTRAINTS
  • The fxn parameter and the name attribute cannot be NULL.
  • The priority attribute must be less than or equal to (numPriorities - 1) and greater than or equal to one (1) (priority 0 is owned by the Idle task).
  • The priority can be less than zero (0) for tasks that should not execute.
  • The stackHeap attribute must identify a valid memory Heap.
generated on Fri, 17 Jun 2011 00:23:57 GMT


package ti.sysbios.rta
index URL

Contains modules that provide support for RTA tools in CCS

In order to use the Real-Time Analysis (RTA) tools in Code Composer Studio, your application must be configured to include support for RTA. SYS/BIOS 6 includes an RTA "Agent" module, ti.sysbios.rta.Agent, which retrieves Log data from the target and sends it to the host.
XDCspec declarations sourced in ti/sysbios/rta/package.xdc
package ti.sysbios.rta [2, 0, 0, 0] {
    module Agent;
    // The Agent module provides target support for RTA tools
    module SupportLogger;
    // The SupportLogger logs Task, Swi, and Hwi instance names so that the RTA tool in CCS 4 may associate the instance handles with their names
}
generated on Fri, 17 Jun 2011 00:24:03 GMT


module ti.sysbios.rta.Agent
index URL

The Agent module provides target support for RTA tools

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Agent consists of a Task, called the "RTA agent", which periodically takes all of the logs from all of the LoggerBuf instances in the system and sends them to the host over the configured transport. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/rta/Agent.xdc
#include <ti/sysbios/rta/Agent.h>
Functions common to all target modules
 | Agent_Module_getMask// Returns the diagnostics mask for this module, Agent_Module_hasMask// Test whether this module has a diagnostics mask, Agent_Module_heap// The heap from which this module allocates memory, Agent_Module_id// Get this module's unique id, Agent_Module_setMask// Set the diagnostics mask for this module, Agent_Module_startupDone// Test if this module has completed startup
Constants
extern const Assert_Id | Agent_A_invalidLogger// Assert if logger id in control command is invalid;
extern const String | Agent_commandStream// Stream name to be used for the RTA command stream;
extern const String | Agent_dataStream// Stream name to be used for the RTA data stream;
extern const Error_Id | Agent_E_badCommand// Error raised if Agent receives an invalid command;
extern const Log_Event | Agent_LD_cmdRcvd// Logged when the Agent receives a command;
extern const Log_Event | Agent_LD_recordsSent// Logged on every Stream_issue call from the Agent;
extern const Log_Event | Agent_LD_writeMask// Logged when a diags mask is changed;
extern const String | Agent_responseStream// Stream name to be used for the RTA response stream;
extern const Bool | Agent_supportControl// Whether RTA should support a control channel;
extern const Int | Agent_transferBufferSize// Size, in number of records, of the RTA agent's transfer buffer;
DETAILS
The Agent consists of a Task, called the "RTA agent", which periodically takes all of the logs from all of the LoggerBuf instances in the system and sends them to the host over the configured transport.
The agent sends records to the host from one LoggerBuf instance at a time--it will finish one LoggerBuf before moving on to the next one.
Before sending the records to the host, the agent will copy them into a transfer buffer. The size of this transfer buffer is configurable using the transferBufferSize parameter.
Because the application may generate logs faster than the agent can send them to the host, there is a limit to how many records the agent will send from one LoggerBuf before moving on to the next one. The limit is approximately the size of the LoggerBuf--the Agent will continue to fill and send transfer buffers of records until the number of records sent is >= the LoggerBuf size.
The rate at which the logs are sent up depends on two configuration parameters, period and agentPriority. The RTA agent pends on an Event instance until that Event is posted by a Clock instance with the configured period. Once the Event is posted, whether the RTA agent will run depends on the system's load as well as the agent's priority relative to other Tasks in the system; therefore the period does not guarantee that the Agent will run that often.
The configureSystemLog parameter allows the Agent to automatically configure logging for key SYS/BIOS system modules. This feature is enabled by default.
The RTA Agent also responds to commands from the host to configure logging dynamically on the target, such as changing modules' diagnostic masks and enabling or disabling loggers.

Automatic Transport Configuration

The RTA Agent requires a data transport to communicate with the host. The Agent will work with any transport which implements the ti.sdo.io.Stream. The Agent can automatically configure itself for one of a list of known transports. See the transport configuration parameter.

Manual Transport Configuration

To configure RTA to use a different transport, or to configure the transport yourself, select Transport_USER.
RTA requires two target-to-host Streams (one for sending up the Log records and another for sending up command responses), and one host-to-target Stream (for receiving commands). The IO stacks for these Streams are configured using the dataStream, commandStream, and responseStream parameters.

Example Manual Configuration with RTDX

The following code can be used as template for a manual configuration of RTA support using RTDX as the transport.
  var Agent = xdc.useModule('ti.sysbios.rta.Agent');

  // Bring in RTDX
  var RtdxModule = xdc.useModule('ti.rtdx.RtdxModule');
  var RtdxDvr = xdc.useModule('ti.rtdx.driver.RtdxDvr');
  var DriverTable = xdc.useModule('ti.sdo.io.DriverTable');

  // Add the RTDX Driver
  var rtdx = RtdxDvr.create();
  DriverTable.addMeta("/rtdx", rtdx);

  // Configure RTDX
  RtdxDvr.numInputChannels = 2;
  RtdxDvr.numOutputChannels = 2;

  RtdxModule.bufferSizeInWords = 4096;

  //Configure Agent to use RTDX
  Agent.dataStream = "/rtdx0";
  Agent.commandStream = "/rtdx1";
  Agent.responseStream = "/rtdx1";
config Agent_A_invalidLogger // module-wide
index URL

Assert if logger id in control command is invalid

C synopsis target-domain
extern const Assert_Id Agent_A_invalidLogger;
config Agent_E_badCommand // module-wide
index URL

Error raised if Agent receives an invalid command

C synopsis target-domain
extern const Error_Id Agent_E_badCommand;
config Agent_LD_cmdRcvd // module-wide
index URL

Logged when the Agent receives a command

C synopsis target-domain
extern const Log_Event Agent_LD_cmdRcvd;
config Agent_LD_recordsSent // module-wide
index URL

Logged on every Stream_issue call from the Agent

C synopsis target-domain
extern const Log_Event Agent_LD_recordsSent;
config Agent_LD_writeMask // module-wide
index URL

Logged when a diags mask is changed

C synopsis target-domain
extern const Log_Event Agent_LD_writeMask;
config Agent_commandStream // module-wide
index URL

Stream name to be used for the RTA command stream

C synopsis target-domain
extern const String Agent_commandStream;
DETAILS
Currently only RTDX is supported and this value should not be changed.
config Agent_dataStream // module-wide
index URL

Stream name to be used for the RTA data stream

C synopsis target-domain
extern const String Agent_dataStream;
DETAILS
Currently only RTDX is supported and this value should not be changed.
config Agent_responseStream // module-wide
index URL

Stream name to be used for the RTA response stream

C synopsis target-domain
extern const String Agent_responseStream;
DETAILS
Currently only RTDX is supported and this value should not be changed.
config Agent_supportControl // module-wide
index URL

Whether RTA should support a control channel

C synopsis target-domain
extern const Bool Agent_supportControl;
DETAILS
The RTA tools can send control commands down to the target to configure log settings. This parameter enables and disables that control feature.
Default is true.
config Agent_transferBufferSize // module-wide
index URL

Size, in number of records, of the RTA agent's transfer buffer

C synopsis target-domain
extern const Int Agent_transferBufferSize;
DETAILS
The Agent will first copy records into the transfer buffer, then send the entire transfer buffer to the host.
The Agent is "double-buffered"; it creates two buffers of the specified size so that one buffer may be filled while the other is being transmitted. This means that the memory footprint of the Agent's transfer buffers will be twice what is specified here.
Default is 85 records. On c6x targets a Log record is 48 bytes, so on c6x targets this default corresponds to a transfer buffer size just under 4KB. 4KB has been determined to be an optimum transfer size for RTDX.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Agent_Module_id();
// Get this module's unique id
Bool Agent_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Agent_Module_heap();
// The heap from which this module allocates memory
Bool Agent_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Agent_Module_getMask();
// Returns the diagnostics mask for this module
Void Agent_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/rta/Agent.xdc
var Agent = xdc.useModule('ti.sysbios.rta.Agent');
module-wide constants & types
    values of type Agent.Transport// The Transport enum lists the transports which the Agent is able to automatically configure. See the transport config parameter
        const Agent.Transport_RTDX// RTDX;
        const Agent.Transport_STOP_MODE_ONLY// Stop Mode Only;
        const Agent.Transport_USER// User-specified Stream driver;
module-wide config parameters
     Agent.A_invalidLogger// Assert if logger id in control command is invalid = Assert.Desc {
        msg: "A_invalidLogger: The logger id %d is invalid."
    };
     Agent.E_badCommand// Error raised if Agent receives an invalid command = Error.Desc {
        msg: "E_badCommand: Received invalid command, id: %d."
    };
     Agent.LD_cmdRcvd// Logged when the Agent receives a command = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
    };
     Agent.LD_recordsSent// Logged on every Stream_issue call from the Agent = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_recordsSent: Sent %d records from logger [%d] 0x%x"
    };
     Agent.LD_writeMask// Logged when a diags mask is changed = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
    };
     Agent.commandStream// Stream name to be used for the RTA command stream = String "/rtdx1";
     Agent.dataStream// Stream name to be used for the RTA data stream = String "/rtdx0";
     Agent.responseStream// Stream name to be used for the RTA response stream = String "/rtdx1";
     Agent.supportControl// Whether RTA should support a control channel = Bool true;
     Agent.transferBufferSize// Size, in number of records, of the RTA agent's transfer buffer = Int 85;
     Agent.agentStackSection// Memory section used for statically allocating Agent Task's stack = String "[Default]";
     Agent.agentStackSize// Agent Task stack size in MAUs = SizeT 1024;
     Agent.common$// Common module configuration parameters = Types.Common$ undefined;
     Agent.configureLoadLog// Deprecated = Bool true;
     Agent.configureSystemLog// Deprecated = Bool true;
     Agent.loadLoggerBufferSection// Section to place the Load LoggerBuf's buffer = String "[Default]";
     Agent.loadLoggerSize// Size (in MAUs) of logger used for the Load module Log events = SizeT 512;
     Agent.loadLogging// Enable the Load module event logging = Bool true;
     Agent.loadLoggingRuntimeControl// Specify whether load logging can be enabled / disabled at runtime = Bool true;
     Agent.mainLoggerBufferSection// Section to place the Main LoggerBuf's buffer = String "[Default]";
     Agent.mainLoggerSize// Size (in MAUs) of logger used for main and non-XDC modules Log events = SizeT 1024;
     Agent.mainLogging// Enable main and non-XDC modules event logging = Bool true;
     Agent.mainLoggingRuntimeControl// Specify whether main logging can be enabled / disabled at runtime = Bool true;
     Agent.numLoadRecords// Deprecated = Int 64;
     Agent.numSystemRecords// Deprecated = Int 64;
     Agent.periodInMs// Period in milliseconds of the RTA agent Task = Int 100;
     Agent.priority// Priority of the RTA agent Task = Int 1;
     Agent.sysbiosHwiLogging// Enable SYSBIOS Hwi module's event logging = Bool false;
     Agent.sysbiosHwiLoggingRuntimeControl// Specify whether Hwi logging can be enabled / disabled at runtime = Bool false;
     Agent.sysbiosLoggerBufferSection// Section to place the SYS/BIOS LoggerBuf's buffer = String "[Default]";
     Agent.sysbiosLoggerSize// Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events = SizeT 4096;
     Agent.sysbiosSwiLogging// Enable SYSBIOS Swi module's event logging = Bool false;
     Agent.sysbiosSwiLoggingRuntimeControl// Specify whether Swi logging can be enabled / disabled at runtime = Bool false;
     Agent.sysbiosTaskLogging// Enable SYSBIOS Task module's event logging = Bool true;
     Agent.sysbiosTaskLoggingRuntimeControl// Specify whether Task logging can be enabled / disabled at runtime = Bool true;
     Agent.transferBufferSection// Memory section used for the transfer buffer = String undefined;
     Agent.transport// The Agent can automatically configure RTA for a known data transport = Agent.Transport Agent.Transport_RTDX;
metaonly enum Agent.Transport
index URL

The Transport enum lists the transports which the Agent is able to automatically configure. See the transport config parameter

XDCscript usage meta-domain
values of type Agent.Transport
    const Agent.Transport_RTDX;
    // RTDX
    const Agent.Transport_STOP_MODE_ONLY;
    // Stop Mode Only
    const Agent.Transport_USER;
    // User-specified Stream driver
config Agent.A_invalidLogger // module-wide
index URL

Assert if logger id in control command is invalid

XDCscript usage meta-domain
Agent.A_invalidLogger = Assert.Desc {
    msg: "A_invalidLogger: The logger id %d is invalid."
};
C SYNOPSIS
Agent_A_invalidLogger
config Agent.E_badCommand // module-wide
index URL

Error raised if Agent receives an invalid command

XDCscript usage meta-domain
Agent.E_badCommand = Error.Desc {
    msg: "E_badCommand: Received invalid command, id: %d."
};
C SYNOPSIS
Agent_E_badCommand
config Agent.LD_cmdRcvd // module-wide
index URL

Logged when the Agent receives a command

XDCscript usage meta-domain
Agent.LD_cmdRcvd = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
};
C SYNOPSIS
Agent_LD_cmdRcvd
config Agent.LD_recordsSent // module-wide
index URL

Logged on every Stream_issue call from the Agent

XDCscript usage meta-domain
Agent.LD_recordsSent = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_recordsSent: Sent %d records from logger [%d] 0x%x"
};
C SYNOPSIS
Agent_LD_recordsSent
config Agent.LD_writeMask // module-wide
index URL

Logged when a diags mask is changed

XDCscript usage meta-domain
Agent.LD_writeMask = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
};
C SYNOPSIS
Agent_LD_writeMask
config Agent.commandStream // module-wide
index URL

Stream name to be used for the RTA command stream

XDCscript usage meta-domain
Agent.commandStream = String "/rtdx1";
DETAILS
Currently only RTDX is supported and this value should not be changed.
C SYNOPSIS
Agent_commandStream
config Agent.dataStream // module-wide
index URL

Stream name to be used for the RTA data stream

XDCscript usage meta-domain
Agent.dataStream = String "/rtdx0";
DETAILS
Currently only RTDX is supported and this value should not be changed.
C SYNOPSIS
Agent_dataStream
config Agent.responseStream // module-wide
index URL

Stream name to be used for the RTA response stream

XDCscript usage meta-domain
Agent.responseStream = String "/rtdx1";
DETAILS
Currently only RTDX is supported and this value should not be changed.
C SYNOPSIS
Agent_responseStream
config Agent.supportControl // module-wide
index URL

Whether RTA should support a control channel

XDCscript usage meta-domain
Agent.supportControl = Bool true;
DETAILS
The RTA tools can send control commands down to the target to configure log settings. This parameter enables and disables that control feature.
Default is true.
C SYNOPSIS
Agent_supportControl
config Agent.transferBufferSize // module-wide
index URL

Size, in number of records, of the RTA agent's transfer buffer

XDCscript usage meta-domain
Agent.transferBufferSize = Int 85;
DETAILS
The Agent will first copy records into the transfer buffer, then send the entire transfer buffer to the host.
The Agent is "double-buffered"; it creates two buffers of the specified size so that one buffer may be filled while the other is being transmitted. This means that the memory footprint of the Agent's transfer buffers will be twice what is specified here.
Default is 85 records. On c6x targets a Log record is 48 bytes, so on c6x targets this default corresponds to a transfer buffer size just under 4KB. 4KB has been determined to be an optimum transfer size for RTDX.
C SYNOPSIS
Agent_transferBufferSize
metaonly config Agent.agentStackSection // module-wide
index URL

Memory section used for statically allocating Agent Task's stack

XDCscript usage meta-domain
Agent.agentStackSection = String "[Default]";
DETAILS
If this parameter is not set then the Task.defaultStackSection is used. See the Task module for instructions on creating a stack section in a different memory segment.
metaonly config Agent.agentStackSize // module-wide
index URL

Agent Task stack size in MAUs

XDCscript usage meta-domain
Agent.agentStackSize = SizeT 1024;
DETAILS
The recommended size is 1024 bytes.
metaonly config Agent.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Agent.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Agent.configureLoadLog // module-wide
index URL

Deprecated

XDCscript usage meta-domain
Agent.configureLoadLog = Bool true;
metaonly config Agent.configureSystemLog // module-wide
index URL

Deprecated

XDCscript usage meta-domain
Agent.configureSystemLog = Bool true;
metaonly config Agent.loadLoggerBufferSection // module-wide
index URL

Section to place the Load LoggerBuf's buffer

XDCscript usage meta-domain
Agent.loadLoggerBufferSection = String "[Default]";
metaonly config Agent.loadLoggerSize // module-wide
index URL

Size (in MAUs) of logger used for the Load module Log events

XDCscript usage meta-domain
Agent.loadLoggerSize = SizeT 512;
DETAILS
To specify the size in number of records, instead of MAUs, use the following code:
  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

  // Set the load logger size to 50 records.
  Agent.loadLoggerSize = 50 * LoggerBuf.Entry.$sizeof();

  // Print the final size to see how much memory is used.
  print("Load Logger Size (MAUs): " + Agent.loadLoggerSize);
metaonly config Agent.loadLogging // module-wide
index URL

Enable the Load module event logging

XDCscript usage meta-domain
Agent.loadLogging = Bool true;
DETAILS
If this is false, the events will be disabled and cannot be enabled at runtime (ALWAYS_OFF). If this is true, the events will be enabled and can also be modified at runtime (RUNTIME_ON).
metaonly config Agent.loadLoggingRuntimeControl // module-wide
index URL

Specify whether load logging can be enabled / disabled at runtime

XDCscript usage meta-domain
Agent.loadLoggingRuntimeControl = Bool true;
DETAILS
This determines what diags settings are applied to the module's diags mask. If 'false', the diags bits will be configured as ALWAYS_OFF or ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
metaonly config Agent.mainLoggerBufferSection // module-wide
index URL

Section to place the Main LoggerBuf's buffer

XDCscript usage meta-domain
Agent.mainLoggerBufferSection = String "[Default]";
metaonly config Agent.mainLoggerSize // module-wide
index URL

Size (in MAUs) of logger used for main and non-XDC modules Log events

XDCscript usage meta-domain
Agent.mainLoggerSize = SizeT 1024;
DETAILS
To specify the size in number of records, instead of MAUs, use the following code:
  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

  // Set the main logger size to 50 records.
  Agent.mainLoggerSize = 50 * LoggerBuf.Entry.$sizeof();

  // Print the final size to see how much memory is used.
  print("Application Logger Size (MAUs): " + Agent.mainLoggerSize);
metaonly config Agent.mainLogging // module-wide
index URL

Enable main and non-XDC modules event logging

XDCscript usage meta-domain
Agent.mainLogging = Bool true;
metaonly config Agent.mainLoggingRuntimeControl // module-wide
index URL

Specify whether main logging can be enabled / disabled at runtime

XDCscript usage meta-domain
Agent.mainLoggingRuntimeControl = Bool true;
DETAILS
This determines what diags settings are applied to the module's diags mask. If 'false', the diags bits will be configured as ALWAYS_OFF or ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
metaonly config Agent.numLoadRecords // module-wide
index URL

Deprecated

XDCscript usage meta-domain
Agent.numLoadRecords = Int 64;
metaonly config Agent.numSystemRecords // module-wide
index URL

Deprecated

XDCscript usage meta-domain
Agent.numSystemRecords = Int 64;
metaonly config Agent.periodInMs // module-wide
index URL

Period in milliseconds of the RTA agent Task

XDCscript usage meta-domain
Agent.periodInMs = Int 100;
DETAILS
Configures how often the RTA agent will try to send logs to the host. The RTA agent sleeps by pending on an Event. A Clock instance periodically posts this Event, which in turn readies the RTA agent. This configuration parameter is used to determine the period of the Clock instance. The actual period will be a multiple of Clock ticks, so the period will be at least as long as one Clock tick.
This value does not guarantee that the RTA agent will run at this rate. Even if the period has expired, the RTA agent will not run until the current running Task has yielded and there are no other higher priority Tasks ready.
Default is 100ms.
metaonly config Agent.priority // module-wide
index URL

Priority of the RTA agent Task

XDCscript usage meta-domain
Agent.priority = Int 1;
DETAILS
Default is 1, the lowest priority.
metaonly config Agent.sysbiosHwiLogging // module-wide
index URL

Enable SYSBIOS Hwi module's event logging

XDCscript usage meta-domain
Agent.sysbiosHwiLogging = Bool false;
metaonly config Agent.sysbiosHwiLoggingRuntimeControl // module-wide
index URL

Specify whether Hwi logging can be enabled / disabled at runtime

XDCscript usage meta-domain
Agent.sysbiosHwiLoggingRuntimeControl = Bool false;
DETAILS
This determines what diags settings are applied to the module's diags mask. If 'false', the diags bits will be configured as ALWAYS_OFF or ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
metaonly config Agent.sysbiosLoggerBufferSection // module-wide
index URL

Section to place the SYS/BIOS LoggerBuf's buffer

XDCscript usage meta-domain
Agent.sysbiosLoggerBufferSection = String "[Default]";
metaonly config Agent.sysbiosLoggerSize // module-wide
index URL

Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events

XDCscript usage meta-domain
Agent.sysbiosLoggerSize = SizeT 4096;
DETAILS
To specify the size in number of records, instead of MAUs, use the following code:
  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

  // Set the SYS/BIOS logger size to 50 records.
  Agent.sysbiosLoggerSize = 50 * LoggerBuf.Entry.$sizeof();

  // Print the final size to see how much memory is used.
  print("SYS/BIOS Logger Size (MAUs): " + Agent.sysbiosLoggerSize);
metaonly config Agent.sysbiosSwiLogging // module-wide
index URL

Enable SYSBIOS Swi module's event logging

XDCscript usage meta-domain
Agent.sysbiosSwiLogging = Bool false;
metaonly config Agent.sysbiosSwiLoggingRuntimeControl // module-wide
index URL

Specify whether Swi logging can be enabled / disabled at runtime

XDCscript usage meta-domain
Agent.sysbiosSwiLoggingRuntimeControl = Bool false;
DETAILS
This determines what diags settings are applied to the module's diags mask. If 'false', the diags bits will be configured as ALWAYS_OFF or ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
metaonly config Agent.sysbiosTaskLogging // module-wide
index URL

Enable SYSBIOS Task module's event logging

XDCscript usage meta-domain
Agent.sysbiosTaskLogging = Bool true;
metaonly config Agent.sysbiosTaskLoggingRuntimeControl // module-wide
index URL

Specify whether Task logging can be enabled / disabled at runtime

XDCscript usage meta-domain
Agent.sysbiosTaskLoggingRuntimeControl = Bool true;
DETAILS
This determines what diags settings are applied to the module's diags mask. If 'false', the diags bits will be configured as ALWAYS_OFF or ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
metaonly config Agent.transferBufferSection // module-wide
index URL

Memory section used for the transfer buffer

XDCscript usage meta-domain
Agent.transferBufferSection = String undefined;
DETAILS
Default is .transferBufferSection which gets placed into the platform's data memory.
metaonly config Agent.transport // module-wide
index URL

The Agent can automatically configure RTA for a known data transport

XDCscript usage meta-domain
Agent.transport = Agent.Transport Agent.Transport_RTDX;
DETAILS
If the target does not support any transports, you may use 'STOP_MODE_ONLY' to retrieve RTA data when the target is halted.
If you want to use a transport which is not listed here, you can specify 'USER' and configure the transport for RTA yourself.
generated on Fri, 17 Jun 2011 00:24:03 GMT


module ti.sysbios.rta.SupportLogger
index URL

The SupportLogger logs Task, Swi, and Hwi instance names so that the RTA tool in CCS 4 may associate the instance handles with their names

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This logging is done using create hooks. The logs are placed in the SupportLogger's LoggerBuf instance, which is separate from other modules' LoggerBufs so that none of the records are overwritten. The number of entries in the LoggerBuf is configurable through createLogSize. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/rta/SupportLogger.xdc
#include <ti/sysbios/rta/SupportLogger.h>
Functions
Void | SupportLogger_hwiCreateHook// (IHwi_Handle hwi, Error_Block *eb);
Void | SupportLogger_swiCreateHook// (Swi_Handle swi, Error_Block *eb);
Void | SupportLogger_taskCreateHook// (Task_Handle task, Error_Block *eb);
Functions common to all target modules
 | SupportLogger_Module_getMask// Returns the diagnostics mask for this module, SupportLogger_Module_hasMask// Test whether this module has a diagnostics mask, SupportLogger_Module_heap// The heap from which this module allocates memory, SupportLogger_Module_id// Get this module's unique id, SupportLogger_Module_setMask// Set the diagnostics mask for this module, SupportLogger_Module_startupDone// Test if this module has completed startup
Constants
extern const Int | SupportLogger_createLogSize// Size of SupportLogger LoggerBuf in records. Allow one record per Task, Swi, and Hwi instance in the system;
extern const Log_Event | SupportLogger_LM_hwiCreate// Logged on Hwi create;
extern const Log_Event | SupportLogger_LM_swiCreate// Logged on Swi create;
extern const Log_Event | SupportLogger_LM_taskCreate// Logged on Task create;
extern const Log_Event | SupportLogger_LM_timestampFreq// Logged in Module_startup to record Timestamp freq;
DETAILS
This logging is done using create hooks. The logs are placed in the SupportLogger's LoggerBuf instance, which is separate from other modules' LoggerBufs so that none of the records are overwritten. The number of entries in the LoggerBuf is configurable through createLogSize.
The SupportLogger is also used to log the Timestamp frequency so that the RTA tool can convert the log event timestamps into seconds. This log occurs during module startup.
config SupportLogger_LM_hwiCreate // module-wide
index URL

Logged on Hwi create

C synopsis target-domain
extern const Log_Event SupportLogger_LM_hwiCreate;
config SupportLogger_LM_swiCreate // module-wide
index URL

Logged on Swi create

C synopsis target-domain
extern const Log_Event SupportLogger_LM_swiCreate;
config SupportLogger_LM_taskCreate // module-wide
index URL

Logged on Task create

C synopsis target-domain
extern const Log_Event SupportLogger_LM_taskCreate;
config SupportLogger_LM_timestampFreq // module-wide
index URL

Logged in Module_startup to record Timestamp freq

C synopsis target-domain
extern const Log_Event SupportLogger_LM_timestampFreq;
config SupportLogger_createLogSize // module-wide
index URL

Size of SupportLogger LoggerBuf in records. Allow one record per Task, Swi, and Hwi instance in the system

C synopsis target-domain
extern const Int SupportLogger_createLogSize;
SupportLogger_hwiCreateHook() // module-wide
index URL
C synopsis target-domain
Void SupportLogger_hwiCreateHook(IHwi_Handle hwi, Error_Block *eb);
SupportLogger_swiCreateHook() // module-wide
index URL
C synopsis target-domain
Void SupportLogger_swiCreateHook(Swi_Handle swi, Error_Block *eb);
SupportLogger_taskCreateHook() // module-wide
index URL
C synopsis target-domain
Void SupportLogger_taskCreateHook(Task_Handle task, Error_Block *eb);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SupportLogger_Module_id();
// Get this module's unique id
Bool SupportLogger_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SupportLogger_Module_heap();
// The heap from which this module allocates memory
Bool SupportLogger_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SupportLogger_Module_getMask();
// Returns the diagnostics mask for this module
Void SupportLogger_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/rta/SupportLogger.xdc
var SupportLogger = xdc.useModule('ti.sysbios.rta.SupportLogger');
module-wide config parameters
     SupportLogger.LM_hwiCreate// Logged on Hwi create = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_hwiCreate: hwi: 0x%x, name: %x %x %x %x %x %x %x"
    };
     SupportLogger.LM_swiCreate// Logged on Swi create = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_swiCreate: swi: 0x%x, name: %x %x %x %x %x %x %x"
    };
     SupportLogger.LM_taskCreate// Logged on Task create = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_taskCreate: task: 0x%x, name: %x %x %x %x %x %x %x"
    };
     SupportLogger.LM_timestampFreq// Logged in Module_startup to record Timestamp freq = Log.EventDesc {
        mask: Diags.USER1 | Diags.USER2,
        msg: "LM_timestampFreq: Timestamp Frequency hi: %d, lo: %d"
    };
     SupportLogger.createLogSize// Size of SupportLogger LoggerBuf in records. Allow one record per Task, Swi, and Hwi instance in the system = Int 32;
     SupportLogger.common$// Common module configuration parameters = Types.Common$ undefined;
config SupportLogger.LM_hwiCreate // module-wide
index URL

Logged on Hwi create

XDCscript usage meta-domain
SupportLogger.LM_hwiCreate = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_hwiCreate: hwi: 0x%x, name: %x %x %x %x %x %x %x"
};
C SYNOPSIS
SupportLogger_LM_hwiCreate
config SupportLogger.LM_swiCreate // module-wide
index URL

Logged on Swi create

XDCscript usage meta-domain
SupportLogger.LM_swiCreate = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_swiCreate: swi: 0x%x, name: %x %x %x %x %x %x %x"
};
C SYNOPSIS
SupportLogger_LM_swiCreate
config SupportLogger.LM_taskCreate // module-wide
index URL

Logged on Task create

XDCscript usage meta-domain
SupportLogger.LM_taskCreate = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_taskCreate: task: 0x%x, name: %x %x %x %x %x %x %x"
};
C SYNOPSIS
SupportLogger_LM_taskCreate
config SupportLogger.LM_timestampFreq // module-wide
index URL

Logged in Module_startup to record Timestamp freq

XDCscript usage meta-domain
SupportLogger.LM_timestampFreq = Log.EventDesc {
    mask: Diags.USER1 | Diags.USER2,
    msg: "LM_timestampFreq: Timestamp Frequency hi: %d, lo: %d"
};
C SYNOPSIS
SupportLogger_LM_timestampFreq
config SupportLogger.createLogSize // module-wide
index URL

Size of SupportLogger LoggerBuf in records. Allow one record per Task, Swi, and Hwi instance in the system

XDCscript usage meta-domain
SupportLogger.createLogSize = Int 32;
C SYNOPSIS
SupportLogger_createLogSize
metaonly config SupportLogger.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SupportLogger.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:03 GMT


package ti.sysbios.syncs
index URL

Contains modules that implement the ISync interface

This package contains implementations of xdc.runtime.knl.ISync that use modules in the ti.sysbios.knl package for the implementation.
XDCspec declarations sourced in ti/sysbios/syncs/package.xdc
package ti.sysbios.syncs [2, 0, 0, 0] {
    module SyncEvent;
    // Implements ISync using events
    module SyncSem;
    // Implements ISyncs using semaphores
    module SyncSwi;
    // Implements ISync using Swis
}
generated on Fri, 17 Jun 2011 00:24:01 GMT


module ti.sysbios.syncs.SyncEvent
index URL

Implements ISync using events

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Event [ more ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncEvent.xdc
#include <ti/sysbios/syncs/SyncEvent.h>
Functions
Void | SyncEvent_construct// Initialize a new instance object inside the provided structure(SyncEvent_Struct *structP, const SyncEvent_Params *params);
SyncEvent_Handle | SyncEvent_create// Allocate and initialize a new instance object and return its handle(const SyncEvent_Params *params, Error_Block *eb);
Void | SyncEvent_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncEvent_Handle *handleP);
Void | SyncEvent_destruct// Finalize the instance object inside the provided structure(SyncEvent_Struct *structP);
Void | SyncEvent_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncEvent_Params *params);
Functions common to all ISync modules
Bool | SyncEvent_query// Query for a particular quality(SyncEvent_Handle handle, Int qual);
Void | SyncEvent_signal// Called at completion of an activity(SyncEvent_Handle handle);
Int | SyncEvent_wait// Called to wait/poll for completion of an activity(SyncEvent_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncEvent_handle// Convert this instance structure pointer into an instance handle, SyncEvent_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncEvent_Handle_label// The label associated with this instance object, SyncEvent_Handle_name// The name of this instance object, SyncEvent_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncEvent_Object_count// The number of statically-created instance objects, SyncEvent_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncEvent_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncEvent_Object_heap// The heap used to allocate dynamically-created instance objects, SyncEvent_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncEvent_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncEvent_Module_getMask// Returns the diagnostics mask for this module, SyncEvent_Module_hasMask// Test whether this module has a diagnostics mask, SyncEvent_Module_heap// The heap from which this module allocates memory, SyncEvent_Module_id// Get this module's unique id, SyncEvent_Module_setMask// Set the diagnostics mask for this module, SyncEvent_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncEvent_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncEvent_Q_BLOCKING// Blocking quality (Int)1
#define | SyncEvent_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncEvent_Object * | SyncEvent_Handle// Client reference to an instance object;
typedef struct | SyncEvent_Object// Opaque internal representation of an instance object SyncEvent_Object;
typedef struct | SyncEvent_Params// Instance config-params structure ...
typedef struct | SyncEvent_Struct// Opaque client structure large enough to hold an instance object SyncEvent_Struct;
typedef enum | SyncEvent_WaitStatus// Error codes returned by ISync_wait ...
Constants
extern const Assert_Id | SyncEvent_A_nullHandle// Assert when baseHandle is null;
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Event
This module uses ti.sysbios.knl.Event.post to implement xdc.runtime.knl.ISync.signal
The implementation of xdc.runtime.knl.ISync.wait is empty and returns FALSE for timeout, since with events the pend call is made outside.
Modules like ti.sdo.io.Stream use an ISync.Handle for selecting the synchronization mechanism. This allows Stream to be independent of the synchronization mechanism.
An instance of SyncEvent requires an Event.Handle. When given a null Event.Handle, SynEvent will assert.
const SyncEvent_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncEvent_NO_WAIT (UInt)0
const SyncEvent_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncEvent_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncEvent_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncEvent_WAIT_FOREVER (UInt)~(0)
enum SyncEvent_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncEvent_WaitStatus {
    SyncEvent_WaitStatus_ERROR,
    SyncEvent_WaitStatus_TIMEOUT,
    SyncEvent_WaitStatus_SUCCESS
} SyncEvent_WaitStatus;
config SyncEvent_A_nullHandle // module-wide
index URL

Assert when baseHandle is null

C synopsis target-domain
extern const Assert_Id SyncEvent_A_nullHandle;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncEvent_Module_id();
// Get this module's unique id
Bool SyncEvent_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncEvent_Module_heap();
// The heap from which this module allocates memory
Bool SyncEvent_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncEvent_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncEvent_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncEvent_Object SyncEvent_Object;
// Opaque internal representation of an instance object
typedef SyncEvent_Object *SyncEvent_Handle;
// Client reference to an instance object
typedef struct SyncEvent_Struct SyncEvent_Struct;
// Opaque client structure large enough to hold an instance object
SyncEvent_Handle SyncEvent_handle(SyncEvent_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncEvent_Struct *SyncEvent_struct(SyncEvent_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncEvent_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     Event_Handle event;
    // Event handle must be provided
    UInt eventId;
    // Event id to be when signal() gets invoked
} SyncEvent_Params;
Void SyncEvent_Params_init(SyncEvent_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SyncEvent_event // instance
index URL

Event handle must be provided

C synopsis target-domain
struct SyncEvent_Params {
     ...
     Event_Handle event;
config SyncEvent_eventId // instance
index URL

Event id to be when signal() gets invoked

C synopsis target-domain
struct SyncEvent_Params {
     ...
    UInt eventId;
Instance Creation
index URL

C synopsis target-domain
SyncEvent_Handle SyncEvent_create(const SyncEvent_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncEvent_construct(SyncEvent_Struct *structP, const SyncEvent_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncEvent_delete(SyncEvent_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncEvent_destruct(SyncEvent_Struct *structP);
// Finalize the instance object inside the provided structure
SyncEvent_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncEvent_query(SyncEvent_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncEvent instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncEvent_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncEvent_signal(SyncEvent_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncEvent instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncEvent_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncEvent_wait(SyncEvent_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncEvent instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncEvent_Handle_upCast(SyncEvent_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncEvent_Handle SyncEvent_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncEvent_Object_count();
// The number of statically-created instance objects
SyncEvent_Handle SyncEvent_Object_get(SyncEvent_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncEvent_Handle SyncEvent_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncEvent_Handle SyncEvent_Object_next(SyncEvent_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncEvent_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncEvent_Handle_label(SyncEvent_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncEvent_Handle_name(SyncEvent_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/syncs/SyncEvent.xdc
var SyncEvent = xdc.useModule('ti.sysbios.syncs.SyncEvent');
module-wide constants & types
    const SyncEvent.NO_WAIT// Used to specify no waiting = 0;
    const SyncEvent.Q_BLOCKING// Blocking quality = 1;
    const SyncEvent.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncEvent.WaitStatus// Error codes returned by ISync_wait
        const SyncEvent.WaitStatus_ERROR;
        const SyncEvent.WaitStatus_TIMEOUT;
        const SyncEvent.WaitStatus_SUCCESS;
module-wide config parameters
     SyncEvent.A_nullHandle// Assert when baseHandle is null = Assert.Desc {
        msg: "A_nullHandle: Null handle passed to create"
    };
     SyncEvent.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncEvent.Params// Instance config-params object;
        params.event// Event handle must be provided = Event.Handle null;
        params.eventId// Event id to be when signal() gets invoked = UInt Event.Id_00;
per-instance creation
    var inst = SyncEvent.create// Create an instance-object(params);
const SyncEvent.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncEvent.NO_WAIT = 0;
C SYNOPSIS
SyncEvent_NO_WAIT
const SyncEvent.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncEvent.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncEvent_Q_BLOCKING
const SyncEvent.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncEvent.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncEvent_WAIT_FOREVER
enum SyncEvent.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncEvent.WaitStatus
    const SyncEvent.WaitStatus_ERROR;
    const SyncEvent.WaitStatus_TIMEOUT;
    const SyncEvent.WaitStatus_SUCCESS;
C SYNOPSIS
SyncEvent_WaitStatus
config SyncEvent.A_nullHandle // module-wide
index URL

Assert when baseHandle is null

XDCscript usage meta-domain
SyncEvent.A_nullHandle = Assert.Desc {
    msg: "A_nullHandle: Null handle passed to create"
};
C SYNOPSIS
SyncEvent_A_nullHandle
metaonly config SyncEvent.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncEvent.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncEvent.Params;
// Instance config-params object
    params.event = Event.Handle null;
    // Event handle must be provided
    params.eventId = UInt Event.Id_00;
    // Event id to be when signal() gets invoked
config SyncEvent.event // instance
index URL

Event handle must be provided

XDCscript usage meta-domain
var params = new SyncEvent.Params;
...
params.event = Event.Handle null;
C SYNOPSIS
null
config SyncEvent.eventId // instance
index URL

Event id to be when signal() gets invoked

XDCscript usage meta-domain
var params = new SyncEvent.Params;
...
params.eventId = UInt Event.Id_00;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncEvent.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncEvent.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:01 GMT


module ti.sysbios.syncs.SyncSem
index URL

Implements ISyncs using semaphores

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Semaphore [ more ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncSem.xdc
#include <ti/sysbios/syncs/SyncSem.h>
Functions
Void | SyncSem_construct// Initialize a new instance object inside the provided structure(SyncSem_Struct *structP, const SyncSem_Params *params, Error_Block *eb);
SyncSem_Handle | SyncSem_create// Allocate and initialize a new instance object and return its handle(const SyncSem_Params *params, Error_Block *eb);
Void | SyncSem_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncSem_Handle *handleP);
Void | SyncSem_destruct// Finalize the instance object inside the provided structure(SyncSem_Struct *structP);
Void | SyncSem_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncSem_Params *params);
Functions common to all ISync modules
Bool | SyncSem_query// Query for a particular quality(SyncSem_Handle handle, Int qual);
Void | SyncSem_signal// Called at completion of an activity(SyncSem_Handle handle);
Int | SyncSem_wait// Called to wait/poll for completion of an activity(SyncSem_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncSem_handle// Convert this instance structure pointer into an instance handle, SyncSem_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncSem_Handle_label// The label associated with this instance object, SyncSem_Handle_name// The name of this instance object, SyncSem_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncSem_Object_count// The number of statically-created instance objects, SyncSem_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncSem_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncSem_Object_heap// The heap used to allocate dynamically-created instance objects, SyncSem_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncSem_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncSem_Module_getMask// Returns the diagnostics mask for this module, SyncSem_Module_hasMask// Test whether this module has a diagnostics mask, SyncSem_Module_heap// The heap from which this module allocates memory, SyncSem_Module_id// Get this module's unique id, SyncSem_Module_setMask// Set the diagnostics mask for this module, SyncSem_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncSem_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncSem_Q_BLOCKING// Blocking quality (Int)1
#define | SyncSem_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncSem_Object * | SyncSem_Handle// Client reference to an instance object;
typedef struct | SyncSem_Object// Opaque internal representation of an instance object SyncSem_Object;
typedef struct | SyncSem_Params// Instance config-params structure ...
typedef struct | SyncSem_Struct// Opaque client structure large enough to hold an instance object SyncSem_Struct;
typedef enum | SyncSem_WaitStatus// Error codes returned by ISync_wait ...
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Semaphore
This module uses ti.sysbios.knl.Semaphore.pend to implement xdc.runtime.knl.ISync.wait and ti.sysbios.knl.Semaphore.post to implement xdc.runtime.knl.ISync.signal.
Modules like ti.sdo.io.Stream use an ISync.Handle for selecting the synchronization mechanism. This allows Stream to be independent of the synchronization mechanism.
An instance of SyncSem requires a Semaphore.Handle. When given a null Semaphore.Handle, SynSem will create a Semaphore for its use. Note that the underlying Semaphore has to be binary in nature and initialized as being unavailable.
const SyncSem_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncSem_NO_WAIT (UInt)0
const SyncSem_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncSem_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncSem_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncSem_WAIT_FOREVER (UInt)~(0)
enum SyncSem_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncSem_WaitStatus {
    SyncSem_WaitStatus_ERROR,
    SyncSem_WaitStatus_TIMEOUT,
    SyncSem_WaitStatus_SUCCESS
} SyncSem_WaitStatus;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncSem_Module_id();
// Get this module's unique id
Bool SyncSem_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncSem_Module_heap();
// The heap from which this module allocates memory
Bool SyncSem_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncSem_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncSem_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncSem_Object SyncSem_Object;
// Opaque internal representation of an instance object
typedef SyncSem_Object *SyncSem_Handle;
// Client reference to an instance object
typedef struct SyncSem_Struct SyncSem_Struct;
// Opaque client structure large enough to hold an instance object
SyncSem_Handle SyncSem_handle(SyncSem_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncSem_Struct *SyncSem_struct(SyncSem_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncSem_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     Semaphore_Handle sem;
    // Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance
} SyncSem_Params;
Void SyncSem_Params_init(SyncSem_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SyncSem_sem // instance
index URL

Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance

C synopsis target-domain
struct SyncSem_Params {
     ...
     Semaphore_Handle sem;
Instance Creation
index URL

C synopsis target-domain
SyncSem_Handle SyncSem_create(const SyncSem_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncSem_construct(SyncSem_Struct *structP, const SyncSem_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncSem_delete(SyncSem_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncSem_destruct(SyncSem_Struct *structP);
// Finalize the instance object inside the provided structure
SyncSem_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncSem_query(SyncSem_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncSem_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncSem_signal(SyncSem_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncSem_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncSem_wait(SyncSem_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncSem_Handle_upCast(SyncSem_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncSem_Handle SyncSem_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncSem_Object_count();
// The number of statically-created instance objects
SyncSem_Handle SyncSem_Object_get(SyncSem_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncSem_Handle SyncSem_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncSem_Handle SyncSem_Object_next(SyncSem_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncSem_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncSem_Handle_label(SyncSem_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncSem_Handle_name(SyncSem_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/syncs/SyncSem.xdc
var SyncSem = xdc.useModule('ti.sysbios.syncs.SyncSem');
module-wide constants & types
    const SyncSem.NO_WAIT// Used to specify no waiting = 0;
    const SyncSem.Q_BLOCKING// Blocking quality = 1;
    const SyncSem.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncSem.WaitStatus// Error codes returned by ISync_wait
        const SyncSem.WaitStatus_ERROR;
        const SyncSem.WaitStatus_TIMEOUT;
        const SyncSem.WaitStatus_SUCCESS;
module-wide config parameters
     SyncSem.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncSem.Params// Instance config-params object;
        params.sem// Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance = Semaphore.Handle null;
per-instance creation
    var inst = SyncSem.create// Create an instance-object(params);
const SyncSem.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncSem.NO_WAIT = 0;
C SYNOPSIS
SyncSem_NO_WAIT
const SyncSem.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncSem.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncSem_Q_BLOCKING
const SyncSem.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncSem.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncSem_WAIT_FOREVER
enum SyncSem.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncSem.WaitStatus
    const SyncSem.WaitStatus_ERROR;
    const SyncSem.WaitStatus_TIMEOUT;
    const SyncSem.WaitStatus_SUCCESS;
C SYNOPSIS
SyncSem_WaitStatus
metaonly config SyncSem.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncSem.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncSem.Params;
// Instance config-params object
    params.sem = Semaphore.Handle null;
    // Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance
config SyncSem.sem // instance
index URL

Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance

XDCscript usage meta-domain
var params = new SyncSem.Params;
...
params.sem = Semaphore.Handle null;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncSem.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncSem.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:01 GMT


module ti.sysbios.syncs.SyncSwi
index URL

Implements ISync using Swis

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Swi [ more ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncSwi.xdc
#include <ti/sysbios/syncs/SyncSwi.h>
Functions
Void | SyncSwi_construct// Initialize a new instance object inside the provided structure(SyncSwi_Struct *structP, const SyncSwi_Params *params);
SyncSwi_Handle | SyncSwi_create// Allocate and initialize a new instance object and return its handle(const SyncSwi_Params *params, Error_Block *eb);
Void | SyncSwi_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncSwi_Handle *handleP);
Void | SyncSwi_destruct// Finalize the instance object inside the provided structure(SyncSwi_Struct *structP);
Void | SyncSwi_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncSwi_Params *params);
Functions common to all ISync modules
Bool | SyncSwi_query// Query for a particular quality(SyncSwi_Handle handle, Int qual);
Void | SyncSwi_signal// Called at completion of an activity(SyncSwi_Handle handle);
Int | SyncSwi_wait// Called to wait/poll for completion of an activity(SyncSwi_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncSwi_handle// Convert this instance structure pointer into an instance handle, SyncSwi_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncSwi_Handle_label// The label associated with this instance object, SyncSwi_Handle_name// The name of this instance object, SyncSwi_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncSwi_Object_count// The number of statically-created instance objects, SyncSwi_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncSwi_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncSwi_Object_heap// The heap used to allocate dynamically-created instance objects, SyncSwi_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncSwi_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncSwi_Module_getMask// Returns the diagnostics mask for this module, SyncSwi_Module_hasMask// Test whether this module has a diagnostics mask, SyncSwi_Module_heap// The heap from which this module allocates memory, SyncSwi_Module_id// Get this module's unique id, SyncSwi_Module_setMask// Set the diagnostics mask for this module, SyncSwi_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncSwi_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncSwi_Q_BLOCKING// Blocking quality (Int)1
#define | SyncSwi_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncSwi_Object * | SyncSwi_Handle// Client reference to an instance object;
typedef struct | SyncSwi_Object// Opaque internal representation of an instance object SyncSwi_Object;
typedef struct | SyncSwi_Params// Instance config-params structure ...
typedef struct | SyncSwi_Struct// Opaque client structure large enough to hold an instance object SyncSwi_Struct;
typedef enum | SyncSwi_WaitStatus// Error codes returned by ISync_wait ...
Constants
extern const Assert_Id | SyncSwi_A_nullHandle// Assert when baseHandle is null;
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Swi
This module uses ti.sysbios.knl.Swi.post to implement xdc.runtime.knl.ISync.signal The implementation of xdc.runtime.knl.ISync.wait is empty and returns FALSE for timeout, since Swis are asynchronous in nature.
Modules like ti.sdo.io.Stream use an ISync.Handle for selecting the synchronization mechanism. This allows Stream to be independent of the synchronization mechanism.
An instance of SyncSwi requires an Swi.Handle. When given a null Swi.Handle, SynSwi will assert.
const SyncSwi_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncSwi_NO_WAIT (UInt)0
const SyncSwi_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncSwi_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncSwi_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncSwi_WAIT_FOREVER (UInt)~(0)
enum SyncSwi_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncSwi_WaitStatus {
    SyncSwi_WaitStatus_ERROR,
    SyncSwi_WaitStatus_TIMEOUT,
    SyncSwi_WaitStatus_SUCCESS
} SyncSwi_WaitStatus;
config SyncSwi_A_nullHandle // module-wide
index URL

Assert when baseHandle is null

C synopsis target-domain
extern const Assert_Id SyncSwi_A_nullHandle;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncSwi_Module_id();
// Get this module's unique id
Bool SyncSwi_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncSwi_Module_heap();
// The heap from which this module allocates memory
Bool SyncSwi_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncSwi_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncSwi_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncSwi_Object SyncSwi_Object;
// Opaque internal representation of an instance object
typedef SyncSwi_Object *SyncSwi_Handle;
// Client reference to an instance object
typedef struct SyncSwi_Struct SyncSwi_Struct;
// Opaque client structure large enough to hold an instance object
SyncSwi_Handle SyncSwi_handle(SyncSwi_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncSwi_Struct *SyncSwi_struct(SyncSwi_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncSwi_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     Swi_Handle swi;
    // Swi handle to be used
} SyncSwi_Params;
Void SyncSwi_Params_init(SyncSwi_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SyncSwi_swi // instance
index URL

Swi handle to be used

C synopsis target-domain
struct SyncSwi_Params {
     ...
     Swi_Handle swi;
Instance Creation
index URL

C synopsis target-domain
SyncSwi_Handle SyncSwi_create(const SyncSwi_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncSwi_construct(SyncSwi_Struct *structP, const SyncSwi_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncSwi_delete(SyncSwi_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncSwi_destruct(SyncSwi_Struct *structP);
// Finalize the instance object inside the provided structure
SyncSwi_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncSwi_query(SyncSwi_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncSwi instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncSwi_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncSwi_signal(SyncSwi_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncSwi instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncSwi_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncSwi_wait(SyncSwi_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncSwi instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncSwi_Handle_upCast(SyncSwi_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncSwi_Handle SyncSwi_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncSwi_Object_count();
// The number of statically-created instance objects
SyncSwi_Handle SyncSwi_Object_get(SyncSwi_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncSwi_Handle SyncSwi_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncSwi_Handle SyncSwi_Object_next(SyncSwi_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncSwi_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncSwi_Handle_label(SyncSwi_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncSwi_Handle_name(SyncSwi_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/syncs/SyncSwi.xdc
var SyncSwi = xdc.useModule('ti.sysbios.syncs.SyncSwi');
module-wide constants & types
    const SyncSwi.NO_WAIT// Used to specify no waiting = 0;
    const SyncSwi.Q_BLOCKING// Blocking quality = 1;
    const SyncSwi.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncSwi.WaitStatus// Error codes returned by ISync_wait
        const SyncSwi.WaitStatus_ERROR;
        const SyncSwi.WaitStatus_TIMEOUT;
        const SyncSwi.WaitStatus_SUCCESS;
module-wide config parameters
     SyncSwi.A_nullHandle// Assert when baseHandle is null = Assert.Desc {
        msg: "A_nullHandle: Null handle passed to create"
    };
     SyncSwi.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncSwi.Params// Instance config-params object;
        params.swi// Swi handle to be used = Swi.Handle null;
per-instance creation
    var inst = SyncSwi.create// Create an instance-object(params);
const SyncSwi.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncSwi.NO_WAIT = 0;
C SYNOPSIS
SyncSwi_NO_WAIT
const SyncSwi.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncSwi.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncSwi_Q_BLOCKING
const SyncSwi.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncSwi.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncSwi_WAIT_FOREVER
enum SyncSwi.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncSwi.WaitStatus
    const SyncSwi.WaitStatus_ERROR;
    const SyncSwi.WaitStatus_TIMEOUT;
    const SyncSwi.WaitStatus_SUCCESS;
C SYNOPSIS
SyncSwi_WaitStatus
config SyncSwi.A_nullHandle // module-wide
index URL

Assert when baseHandle is null

XDCscript usage meta-domain
SyncSwi.A_nullHandle = Assert.Desc {
    msg: "A_nullHandle: Null handle passed to create"
};
C SYNOPSIS
SyncSwi_A_nullHandle
metaonly config SyncSwi.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncSwi.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncSwi.Params;
// Instance config-params object
    params.swi = Swi.Handle null;
    // Swi handle to be used
config SyncSwi.swi // instance
index URL

Swi handle to be used

XDCscript usage meta-domain
var params = new SyncSwi.Params;
...
params.swi = Swi.Handle null;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncSwi.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncSwi.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:01 GMT


package ti.sysbios.timers
index URL

Contains various timer modules

This package contains Timer modules that manage the timer peripherals available on various devices. For the IDs, names, and base addresses of supported devices, see the following Timer Mapping Tables: [ more ... ]
XDCspec declarations sourced in ti/sysbios/timers/package.xdc
package ti.sysbios.timers [2, 0, 0, 0] {
}
DETAILS
This package contains Timer modules that manage the timer peripherals available on various devices. For the IDs, names, and base addresses of supported devices, see the following Timer Mapping Tables:
  • DMTimer Timer Mapping Table
  • GPTimer Timer Mapping Table
  • Timer64 Timer Mapping Table
The Timer modules let you use and configure various timers that exist on a particular device. This is achieved by specifying a timer ID when calling Timer_create().
By default, the ti.sysbios.knl.Clock module statically configures a ti.sysbios.hal.Timer timer instance to provide the periodic 1 ms tick interrupt. If you want to use a custom configured timer for the Clock module's tick source, use the following example configuration as a guide:
  var Clock = xdc.useModule('ti.sysbios.knl.Clock');

  // Tell the Clock module that YOU are providing the periodic interrupt
  Clock.tickSource = Clock.TickSource_USER;

  // this example uses the ti.sysbios.timers.dmtimer.Timer module
  var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');

  // create a dmtimer config parameter object
  var timerParams = new Timer.Params();

  // make sure you set the period to 1000 us (1ms)
  timerParams.period = 1000;

  // custom dmtimer config parameters here...
  timerParams.twer.ovf_wup_ena = 1;

  // Create the timer.
  // This example uses timer id 3.
  // The timer interrupt handler must be set to 'Clock.tick'.
  Timer.create(3, Clock.tick, timerParams);
generated on Fri, 17 Jun 2011 00:22:35 GMT


package ti.sysbios.timers.dmtimer
index URL

Contains specifications for the DMTimer

XDCspec declarations sourced in ti/sysbios/timers/dmtimer/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.timers.dmtimer [2, 0, 0, 0] {
    module Timer;
    // Timer Peripheral Manager
    module TimestampProvider;
}
generated on Fri, 17 Jun 2011 00:22:41 GMT


module ti.sysbios.timers.dmtimer.Timer
index URL

Timer Peripheral Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Timer module manages the Dual Mode timer (dmtimer) peripherals available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/timers/dmtimer/Timer.xdc
#include <ti/sysbios/timers/dmtimer/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
typedef struct | Timer_Tclr// Control Register (TCLR) ...
typedef struct | Timer_Tier// Interrupt Enable Register (TIER) ...
typedef struct | Timer_TiocpCfg// L4 interface Configuration Register (TIOCP_CFG) ...
typedef struct | Timer_Tsicr// L4 Interface Synchronization Control Register (TSICR) ...
typedef struct | Timer_Twer// WakepUp Enable Register (TWER) ...
Constants
extern const Bits32 | Timer_anyMask// Available mask to be used when select = Timer_ANY. Set in xs file;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
DETAILS
This Timer module manages the Dual Mode timer (dmtimer) peripherals available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information).
The dmtimer Timer module supports the timer in 'one shot', 'continuous', and 'dynamic' modes.
In 'one shot' mode, a timer function will "fire" (run) when the timer period expires (counts up to zero). In 'one shot' mode this will only happen once.
In 'continuous' mode, the specified timer function will "fire" every time the period expires, throughout the lifetime of the program. When the period expires in 'continuous mode', the period is then reset to its original value and then begins counting up to zero again. At this point the timer function will fire again and the cycle repeats itself.
In 'dynamic' mode, the specified timer function will "fire" every time the period expires. But the period of the timer can be changed dynamically, to correspond to the next tick interrupt needed from the timer. The timer will continually count upwards, and the timer's compare mode is used to generate an interrupt when a specific threshold count is reached. This mode is used by the SYS/BIOS Clock module, for implementing dynamic tick suppression, which reduces the number of interrupts from the timer to the minimum required for currently scheduled timeouts.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getFunc | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).

Timer Mapping Tables

The Timer module allows the user to use and configure the various timers that exist on a particular device. This is achieved by specifying a timer ID when calling ti.sysbios.hal.Timer.Timer_create. However, the timer ID specified may not always map to that timer; for example, specifying an ID value of 1 does not necessarily mean that this will map to "GPTimer1". These tables are provided to show which timers map to which timer IDs.

Timer Mapping Tables
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Tclr
index URL

Control Register (TCLR)

C synopsis target-domain
typedef struct Timer_Tclr {
    Bits32 ptv;
    // Trigger output mode
    Bits8 pre;
    // Prescalar enable
    Bits8 ce;
    // Compare enable
    Bits8 scpwm;
    // Pulse-width modulation
    Bits16 tcm;
    // Transition capture mode
    Bits16 trg;
    // Trigger output mode
    Bits8 pt;
    // Pulse or toggle select bit
    Bits8 captmode;
    // Capture mode select bit
    Bits8 gpocfg;
    // PWM output/event detection input pin
} Timer_Tclr;
struct Timer_Tier
index URL

Interrupt Enable Register (TIER)

C synopsis target-domain
typedef struct Timer_Tier {
    Bits8 mat_it_ena;
    // Enable match interrupt
    Bits8 ovf_it_ena;
    // Enable overflow interrupt
    Bits8 tcar_it_ena;
    // Enable capture interrupt
} Timer_Tier;
struct Timer_TiocpCfg
index URL

L4 interface Configuration Register (TIOCP_CFG)

C synopsis target-domain
typedef struct Timer_TiocpCfg {
    Bits8 idlemode;
    // 0=force-idle;1=no-idle;2=Smart-idle;3=Smart-idle
    Bits8 emufree;
    // 0=counter frozen; 1=counter free-running
    Bits8 softreset;
    // 0=normal mode; 1=soft reset
} Timer_TiocpCfg;
struct Timer_Tsicr
index URL

L4 Interface Synchronization Control Register (TSICR)

C synopsis target-domain
typedef struct Timer_Tsicr {
    Bits8 sft;
    // Reset software functional registers
    Bits8 posted;
    // Posted mode selection
} Timer_Tsicr;
struct Timer_Twer
index URL

WakepUp Enable Register (TWER)

C synopsis target-domain
typedef struct Timer_Twer {
    Bits8 mat_wup_ena;
    // Enable match wake-up
    Bits8 ovf_wup_ena;
    // Enable overflow wake-up
    Bits8 tcar_wup_ena;
    // Enable capture wake-up
} Timer_Twer;
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

C synopsis target-domain
extern const Bits32 Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
     Timer_Tclr tclr;
    //
     Timer_Tier tier;
    //
     Timer_TiocpCfg tiocpCfg;
    //
    UInt32 tmar;
    //
     Timer_Tsicr tsicr;
    //
     Timer_Twer twer;
    //
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
config Timer_tclr // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tclr tclr;
config Timer_tier // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tier tier;
config Timer_tiocpCfg // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_TiocpCfg tiocpCfg;
config Timer_tmar // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 tmar;
config Timer_tsicr // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tsicr tsicr;
config Timer_twer // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Twer twer;
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/timers/dmtimer/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Tclr// Control Register (TCLR);
        obj.ptv// Trigger output mode = Bits32 ...
        obj.pre// Prescalar enable = Bits8 ...
        obj.ce// Compare enable = Bits8 ...
        obj.scpwm// Pulse-width modulation = Bits8 ...
        obj.tcm// Transition capture mode = Bits16 ...
        obj.trg// Trigger output mode = Bits16 ...
        obj.pt// Pulse or toggle select bit = Bits8 ...
        obj.captmode// Capture mode select bit = Bits8 ...
        obj.gpocfg// PWM output/event detection input pin = Bits8 ...
    var obj = new Timer.Tier// Interrupt Enable Register (TIER);
        obj.mat_it_ena// Enable match interrupt = Bits8 ...
        obj.ovf_it_ena// Enable overflow interrupt = Bits8 ...
        obj.tcar_it_ena// Enable capture interrupt = Bits8 ...
    var obj = new Timer.TimerSetting// Timer Settings;
        obj.master// specifies whether this is the master = Bool ...
        obj.baseAddr// specify the base address = Ptr ...
        obj.intNum// specify which interrupt vector = Int ...
        obj.name// specify the timer name = String ...
    var obj = new Timer.TiocpCfg// L4 interface Configuration Register (TIOCP_CFG);
        obj.idlemode// 0=force-idle;1=no-idle;2=Smart-idle;3=Smart-idle = Bits8 ...
        obj.emufree// 0=counter frozen; 1=counter free-running = Bits8 ...
        obj.softreset// 0=normal mode; 1=soft reset = Bits8 ...
    var obj = new Timer.Tsicr// L4 Interface Synchronization Control Register (TSICR);
        obj.sft// Reset software functional registers = Bits8 ...
        obj.posted// Posted mode selection = Bits8 ...
    var obj = new Timer.Twer// WakepUp Enable Register (TWER);
        obj.mat_wup_ena// Enable match wake-up = Bits8 ...
        obj.ovf_wup_ena// Enable overflow wake-up = Bits8 ...
        obj.tcar_wup_ena// Enable capture wake-up = Bits8 ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY. Set in xs file = Bits32 undefined;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
     Timer.intFreq// Internal frequency for Timer = Types.FreqHz {
        lo: 0,
        hi: 0
    };
     Timer.rovViewInfo// = ViewInfo.Instance ViewInfo.create;
     Timer.timerSettings// Global Control configuration for each physical timer = Timer.TimerSetting[] [ ];
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
        params.tclr// = Timer.Tclr {
            ptv: 0,
            pre: 0,
            ce: 0,
            scpwm: 0,
            tcm: 0,
            trg: 0,
            pt: 0,
            captmode: 0,
            gpocfg: 0
        };
        params.tier// = Timer.Tier {
            mat_it_ena: 0,
            ovf_it_ena: 1,
            tcar_it_ena: 0
        };
        params.tiocpCfg// = Timer.TiocpCfg {
            idlemode: 0,
            emufree: 0,
            softreset: 1
        };
        params.tmar// = UInt32 0;
        params.tsicr// = Timer.Tsicr {
            sft: 0,
            posted: 1
        };
        params.twer// = Timer.Twer {
            mat_wup_ena: 0,
            ovf_wup_ena: 0,
            tcar_wup_ena: 0
        };
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Tclr
index URL

Control Register (TCLR)

XDCscript usage meta-domain
var obj = new Timer.Tclr;
    obj.ptv = Bits32 ...
    // Trigger output mode
    obj.pre = Bits8 ...
    // Prescalar enable
    obj.ce = Bits8 ...
    // Compare enable
    obj.scpwm = Bits8 ...
    // Pulse-width modulation
    obj.tcm = Bits16 ...
    // Transition capture mode
    obj.trg = Bits16 ...
    // Trigger output mode
    obj.pt = Bits8 ...
    // Pulse or toggle select bit
    obj.captmode = Bits8 ...
    // Capture mode select bit
    obj.gpocfg = Bits8 ...
    // PWM output/event detection input pin
C SYNOPSIS
Timer_Tclr
struct Timer.Tier
index URL

Interrupt Enable Register (TIER)

XDCscript usage meta-domain
var obj = new Timer.Tier;
    obj.mat_it_ena = Bits8 ...
    // Enable match interrupt
    obj.ovf_it_ena = Bits8 ...
    // Enable overflow interrupt
    obj.tcar_it_ena = Bits8 ...
    // Enable capture interrupt
C SYNOPSIS
Timer_Tier
metaonly struct Timer.TimerSetting
index URL

Timer Settings

XDCscript usage meta-domain
var obj = new Timer.TimerSetting;
    obj.master = Bool ...
    // specifies whether this is the master
    obj.baseAddr = Ptr ...
    // specify the base address
    obj.intNum = Int ...
    // specify which interrupt vector
    obj.name = String ...
    // specify the timer name
struct Timer.TiocpCfg
index URL

L4 interface Configuration Register (TIOCP_CFG)

XDCscript usage meta-domain
var obj = new Timer.TiocpCfg;
    obj.idlemode = Bits8 ...
    // 0=force-idle;1=no-idle;2=Smart-idle;3=Smart-idle
    obj.emufree = Bits8 ...
    // 0=counter frozen; 1=counter free-running
    obj.softreset = Bits8 ...
    // 0=normal mode; 1=soft reset
C SYNOPSIS
Timer_TiocpCfg
struct Timer.Tsicr
index URL

L4 Interface Synchronization Control Register (TSICR)

XDCscript usage meta-domain
var obj = new Timer.Tsicr;
    obj.sft = Bits8 ...
    // Reset software functional registers
    obj.posted = Bits8 ...
    // Posted mode selection
C SYNOPSIS
Timer_Tsicr
struct Timer.Twer
index URL

WakepUp Enable Register (TWER)

XDCscript usage meta-domain
var obj = new Timer.Twer;
    obj.mat_wup_ena = Bits8 ...
    // Enable match wake-up
    obj.ovf_wup_ena = Bits8 ...
    // Enable overflow wake-up
    obj.tcar_wup_ena = Bits8 ...
    // Enable capture wake-up
C SYNOPSIS
Timer_Twer
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

XDCscript usage meta-domain
Timer.anyMask = Bits32 undefined;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Timer.intFreq // module-wide
index URL

Internal frequency for Timer

XDCscript usage meta-domain
Timer.intFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
metaonly config Timer.rovViewInfo // module-wide
index URL
XDCscript usage meta-domain
Timer.rovViewInfo = ViewInfo.Instance ViewInfo.create;
metaonly config Timer.timerSettings // module-wide
index URL

Global Control configuration for each physical timer

XDCscript usage meta-domain
Timer.timerSettings = Timer.TimerSetting[] [ ];
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
    params.tclr = Timer.Tclr {
    //
        ptv: 0,
        pre: 0,
        ce: 0,
        scpwm: 0,
        tcm: 0,
        trg: 0,
        pt: 0,
        captmode: 0,
        gpocfg: 0
    };
    params.tier = Timer.Tier {
    //
        mat_it_ena: 0,
        ovf_it_ena: 1,
        tcar_it_ena: 0
    };
    params.tiocpCfg = Timer.TiocpCfg {
    //
        idlemode: 0,
        emufree: 0,
        softreset: 1
    };
    params.tmar = UInt32 0;
    //
    params.tsicr = Timer.Tsicr {
    //
        sft: 0,
        posted: 1
    };
    params.twer = Timer.Twer {
    //
        mat_wup_ena: 0,
        ovf_wup_ena: 0,
        tcar_wup_ena: 0
    };
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
config Timer.tclr // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tclr = Timer.Tclr {
    ptv: 0,
    pre: 0,
    ce: 0,
    scpwm: 0,
    tcm: 0,
    trg: 0,
    pt: 0,
    captmode: 0,
    gpocfg: 0
};
C SYNOPSIS
null
config Timer.tier // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tier = Timer.Tier {
    mat_it_ena: 0,
    ovf_it_ena: 1,
    tcar_it_ena: 0
};
C SYNOPSIS
null
config Timer.tiocpCfg // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tiocpCfg = Timer.TiocpCfg {
    idlemode: 0,
    emufree: 0,
    softreset: 1
};
C SYNOPSIS
null
config Timer.tmar // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tmar = UInt32 0;
C SYNOPSIS
null
config Timer.tsicr // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tsicr = Timer.Tsicr {
    sft: 0,
    posted: 1
};
C SYNOPSIS
null
config Timer.twer // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.twer = Timer.Twer {
    mat_wup_ena: 0,
    ovf_wup_ena: 0,
    tcar_wup_ena: 0
};
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:41 GMT


module ti.sysbios.timers.dmtimer.TimestampProvider
index URL
  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main** | Startup***
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
C synopsis target-domain sourced in ti/sysbios/timers/dmtimer/TimestampProvider.xdc
#include <ti/sysbios/timers/dmtimer/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id;
extern const Bool | TimestampProvider_useClockTimer// Use the same timer as Clock;
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
DETAILS
A value of Timer.ANY (-1) indicates any timer is ok.
config TimestampProvider_useClockTimer // module-wide
index URL

Use the same timer as Clock

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
Set this parameter when you want TimestampProvider is use the same timer as the BIOS Clock module.
This parameter overrides the timeId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/timers/dmtimer/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.timers.dmtimer.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Use the same timer as Clock = Bool undefined;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
DETAILS
A value of Timer.ANY (-1) indicates any timer is ok.
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Use the same timer as Clock

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool undefined;
DETAILS
Set this parameter when you want TimestampProvider is use the same timer as the BIOS Clock module.
This parameter overrides the timeId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:41 GMT


package ti.sysbios.timers.gptimer
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/timers/gptimer/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.timers.gptimer [2, 0, 0, 0] {
    module Timer;
    // Timer Peripheral Manager
}
generated on Fri, 17 Jun 2011 00:22:39 GMT


module ti.sysbios.timers.gptimer.Timer
index URL

Timer Peripheral Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Timer module manages the general purpose timer (gptimer) peripherals available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information). [ more ... ]
C synopsis target-domain sourced in ti/sysbios/timers/gptimer/Timer.xdc
#include <ti/sysbios/timers/gptimer/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
Typedefs
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
typedef struct | Timer_Tclr// Control Register (TCLR) ...
typedef struct | Timer_Tier// Interrupt Enable Register (TIER) ...
typedef struct | Timer_TiocpCfg// L4 interface Configuration Register (TIOCP_CFG) ...
typedef struct | Timer_Tsicr// L4 Interface Synchronization Control Register (TSICR) ...
typedef struct | Timer_Twer// WakepUp Enable Register (TWER) ...
Constants
extern const Bits32 | Timer_anyMask// Available mask to be used when select = Timer_ANY. Set in xs file;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
DETAILS
This Timer module manages the general purpose timer (gptimer) peripherals available on the ARM and C6000 devices (see Timer Mapping Tables for supported device information).
The gptimer Timer module supports the timer in 'one shot' and 'continuous' modes.
In 'one shot' mode, a timer function will "fire" (run) when the timer period expires (counts down to zero). In 'one shot' mode this will only happen once. In 'continuous' mode, the specified timer function will "fire" every time the period expires, throughout the lifetime of the program. When the period expires in 'continuous mode', the period is then reset to its original value and then begins counting down to zero again. At this point the timer function will fire again and the cycle repeats itself.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getFunc | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).

Timer Mapping Tables

The Timer module allows the user to use and configure the various timers that exist on a particular device. This is achieved by specifying a timer ID when calling ti.sysbios.hal.Timer.Timer_create. However, the timer ID specified may not always map to that timer; for example, specifying an ID value of 1 does not necessarily mean that this will map to "GPTimer1". These tables are provided to show which timers map to which timer IDs.

Timer Mapping Tables
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Tclr
index URL

Control Register (TCLR)

C synopsis target-domain
typedef struct Timer_Tclr {
    Bits32 ptv;
    // Trigger output mode
    Bits8 pre;
    // Prescalar enable
    Bits8 ce;
    // Compare enable
    Bits8 scpwm;
    // Pulse-width modulation
    Bits16 tcm;
    // Transition capture mode
    Bits16 trg;
    // Trigger output mode
    Bits8 pt;
    // Pulse or toggle select bit
    Bits8 captmode;
    // Capture mode select bit
    Bits8 gpocfg;
    // PWM output/event detection input pin
} Timer_Tclr;
struct Timer_Tier
index URL

Interrupt Enable Register (TIER)

C synopsis target-domain
typedef struct Timer_Tier {
    Bits8 mat_it_ena;
    // Enable match interrupt
    Bits8 ovf_it_ena;
    // Enable overflow interrupt
    Bits8 tcar_it_ena;
    // Enable capture interrupt
} Timer_Tier;
struct Timer_TiocpCfg
index URL

L4 interface Configuration Register (TIOCP_CFG)

C synopsis target-domain
typedef struct Timer_TiocpCfg {
    Bits8 autoidle;
    // 0=L4 interface is free running; 1=Automatic
    Bits8 softreset;
    // 0=normal mode; 1=soft reset
    Bits8 enawakeup;
    // 0=no wakeup; 1=wake-up line assertion enabled
    Bits16 idlemode;
    // 0=force-idle; 1=no-idle; 2=Smart-idle
    Bits8 emufree;
    // 0=counter frozen; 1=counter free-running
    Bits16 clockactivity;
    // Clock activity during wakeup mode period
} Timer_TiocpCfg;
struct Timer_Tsicr
index URL

L4 Interface Synchronization Control Register (TSICR)

C synopsis target-domain
typedef struct Timer_Tsicr {
    Bits8 sft;
    // Reset software functional registers
    Bits8 posted;
    // Posted mode selection
} Timer_Tsicr;
struct Timer_Twer
index URL

WakepUp Enable Register (TWER)

C synopsis target-domain
typedef struct Timer_Twer {
    Bits8 mat_wup_ena;
    // Enable match wake-up
    Bits8 ovf_wup_ena;
    // Enable overflow wake-up
    Bits8 tcar_wup_ena;
    // Enable capture wake-up
} Timer_Twer;
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

C synopsis target-domain
extern const Bits32 Timer_anyMask;
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Types_FreqHz extFreq;
    // Timer frequency
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
     Timer_Tclr tclr;
    //
     Timer_Tier tier;
    //
     Timer_TiocpCfg tiocpCfg;
    //
    UInt32 tmar;
    //
     Timer_Tsicr tsicr;
    //
     Timer_Twer twer;
    //
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
config Timer_tclr // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tclr tclr;
config Timer_tier // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tier tier;
config Timer_tiocpCfg // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_TiocpCfg tiocpCfg;
config Timer_tmar // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 tmar;
config Timer_tsicr // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Tsicr tsicr;
config Timer_twer // instance
index URL
C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Twer twer;
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/timers/gptimer/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.timers.gptimer.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Tclr// Control Register (TCLR);
        obj.ptv// Trigger output mode = Bits32 ...
        obj.pre// Prescalar enable = Bits8 ...
        obj.ce// Compare enable = Bits8 ...
        obj.scpwm// Pulse-width modulation = Bits8 ...
        obj.tcm// Transition capture mode = Bits16 ...
        obj.trg// Trigger output mode = Bits16 ...
        obj.pt// Pulse or toggle select bit = Bits8 ...
        obj.captmode// Capture mode select bit = Bits8 ...
        obj.gpocfg// PWM output/event detection input pin = Bits8 ...
    var obj = new Timer.Tier// Interrupt Enable Register (TIER);
        obj.mat_it_ena// Enable match interrupt = Bits8 ...
        obj.ovf_it_ena// Enable overflow interrupt = Bits8 ...
        obj.tcar_it_ena// Enable capture interrupt = Bits8 ...
    var obj = new Timer.TimerSetting// Timer Settings;
        obj.master// specifies whether this is the master = Bool ...
        obj.baseAddr// specify the base address = Ptr ...
        obj.intNum// specify which interrupt vector = Int ...
    var obj = new Timer.TiocpCfg// L4 interface Configuration Register (TIOCP_CFG);
        obj.autoidle// 0=L4 interface is free running; 1=Automatic = Bits8 ...
        obj.softreset// 0=normal mode; 1=soft reset = Bits8 ...
        obj.enawakeup// 0=no wakeup; 1=wake-up line assertion enabled = Bits8 ...
        obj.idlemode// 0=force-idle; 1=no-idle; 2=Smart-idle = Bits16 ...
        obj.emufree// 0=counter frozen; 1=counter free-running = Bits8 ...
        obj.clockactivity// Clock activity during wakeup mode period = Bits16 ...
    var obj = new Timer.Tsicr// L4 Interface Synchronization Control Register (TSICR);
        obj.sft// Reset software functional registers = Bits8 ...
        obj.posted// Posted mode selection = Bits8 ...
    var obj = new Timer.Twer// WakepUp Enable Register (TWER);
        obj.mat_wup_ena// Enable match wake-up = Bits8 ...
        obj.ovf_wup_ena// Enable overflow wake-up = Bits8 ...
        obj.tcar_wup_ena// Enable capture wake-up = Bits8 ...
module-wide config parameters
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY. Set in xs file = Bits32 undefined;
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
     Timer.intFreq// Internal frequency for Timer = Types.FreqHz {
        lo: 0,
        hi: 0
    };
     Timer.timerSettings// Global Control configuration for each physical timer = Timer.TimerSetting[] [ ];
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
        params.tclr// = Timer.Tclr {
            ptv: 0,
            pre: 0,
            ce: 0,
            scpwm: 0,
            tcm: 0,
            trg: 0,
            pt: 0,
            captmode: 0,
            gpocfg: 0
        };
        params.tier// = Timer.Tier {
            mat_it_ena: 0,
            ovf_it_ena: 1,
            tcar_it_ena: 0
        };
        params.tiocpCfg// = Timer.TiocpCfg {
            autoidle: 0,
            softreset: 1,
            enawakeup: 0,
            idlemode: 0,
            emufree: 0,
            clockactivity: 0
        };
        params.tmar// = UInt32 0;
        params.tsicr// = Timer.Tsicr {
            sft: 0,
            posted: 1
        };
        params.twer// = Timer.Twer {
            mat_wup_ena: 0,
            ovf_wup_ena: 0,
            tcar_wup_ena: 0
        };
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Tclr
index URL

Control Register (TCLR)

XDCscript usage meta-domain
var obj = new Timer.Tclr;
    obj.ptv = Bits32 ...
    // Trigger output mode
    obj.pre = Bits8 ...
    // Prescalar enable
    obj.ce = Bits8 ...
    // Compare enable
    obj.scpwm = Bits8 ...
    // Pulse-width modulation
    obj.tcm = Bits16 ...
    // Transition capture mode
    obj.trg = Bits16 ...
    // Trigger output mode
    obj.pt = Bits8 ...
    // Pulse or toggle select bit
    obj.captmode = Bits8 ...
    // Capture mode select bit
    obj.gpocfg = Bits8 ...
    // PWM output/event detection input pin
C SYNOPSIS
Timer_Tclr
struct Timer.Tier
index URL

Interrupt Enable Register (TIER)

XDCscript usage meta-domain
var obj = new Timer.Tier;
    obj.mat_it_ena = Bits8 ...
    // Enable match interrupt
    obj.ovf_it_ena = Bits8 ...
    // Enable overflow interrupt
    obj.tcar_it_ena = Bits8 ...
    // Enable capture interrupt
C SYNOPSIS
Timer_Tier
metaonly struct Timer.TimerSetting
index URL

Timer Settings

XDCscript usage meta-domain
var obj = new Timer.TimerSetting;
    obj.master = Bool ...
    // specifies whether this is the master
    obj.baseAddr = Ptr ...
    // specify the base address
    obj.intNum = Int ...
    // specify which interrupt vector
struct Timer.TiocpCfg
index URL

L4 interface Configuration Register (TIOCP_CFG)

XDCscript usage meta-domain
var obj = new Timer.TiocpCfg;
    obj.autoidle = Bits8 ...
    // 0=L4 interface is free running; 1=Automatic
    obj.softreset = Bits8 ...
    // 0=normal mode; 1=soft reset
    obj.enawakeup = Bits8 ...
    // 0=no wakeup; 1=wake-up line assertion enabled
    obj.idlemode = Bits16 ...
    // 0=force-idle; 1=no-idle; 2=Smart-idle
    obj.emufree = Bits8 ...
    // 0=counter frozen; 1=counter free-running
    obj.clockactivity = Bits16 ...
    // Clock activity during wakeup mode period
C SYNOPSIS
Timer_TiocpCfg
struct Timer.Tsicr
index URL

L4 Interface Synchronization Control Register (TSICR)

XDCscript usage meta-domain
var obj = new Timer.Tsicr;
    obj.sft = Bits8 ...
    // Reset software functional registers
    obj.posted = Bits8 ...
    // Posted mode selection
C SYNOPSIS
Timer_Tsicr
struct Timer.Twer
index URL

WakepUp Enable Register (TWER)

XDCscript usage meta-domain
var obj = new Timer.Twer;
    obj.mat_wup_ena = Bits8 ...
    // Enable match wake-up
    obj.ovf_wup_ena = Bits8 ...
    // Enable overflow wake-up
    obj.tcar_wup_ena = Bits8 ...
    // Enable capture wake-up
C SYNOPSIS
Timer_Twer
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

XDCscript usage meta-domain
Timer.anyMask = Bits32 undefined;
C SYNOPSIS
Timer_anyMask
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Timer.intFreq // module-wide
index URL

Internal frequency for Timer

XDCscript usage meta-domain
Timer.intFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
metaonly config Timer.timerSettings // module-wide
index URL

Global Control configuration for each physical timer

XDCscript usage meta-domain
Timer.timerSettings = Timer.TimerSetting[] [ ];
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
    params.tclr = Timer.Tclr {
    //
        ptv: 0,
        pre: 0,
        ce: 0,
        scpwm: 0,
        tcm: 0,
        trg: 0,
        pt: 0,
        captmode: 0,
        gpocfg: 0
    };
    params.tier = Timer.Tier {
    //
        mat_it_ena: 0,
        ovf_it_ena: 1,
        tcar_it_ena: 0
    };
    params.tiocpCfg = Timer.TiocpCfg {
    //
        autoidle: 0,
        softreset: 1,
        enawakeup: 0,
        idlemode: 0,
        emufree: 0,
        clockactivity: 0
    };
    params.tmar = UInt32 0;
    //
    params.tsicr = Timer.Tsicr {
    //
        sft: 0,
        posted: 1
    };
    params.twer = Timer.Twer {
    //
        mat_wup_ena: 0,
        ovf_wup_ena: 0,
        tcar_wup_ena: 0
    };
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
config Timer.tclr // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tclr = Timer.Tclr {
    ptv: 0,
    pre: 0,
    ce: 0,
    scpwm: 0,
    tcm: 0,
    trg: 0,
    pt: 0,
    captmode: 0,
    gpocfg: 0
};
C SYNOPSIS
null
config Timer.tier // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tier = Timer.Tier {
    mat_it_ena: 0,
    ovf_it_ena: 1,
    tcar_it_ena: 0
};
C SYNOPSIS
null
config Timer.tiocpCfg // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tiocpCfg = Timer.TiocpCfg {
    autoidle: 0,
    softreset: 1,
    enawakeup: 0,
    idlemode: 0,
    emufree: 0,
    clockactivity: 0
};
C SYNOPSIS
null
config Timer.tmar // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tmar = UInt32 0;
C SYNOPSIS
null
config Timer.tsicr // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.tsicr = Timer.Tsicr {
    sft: 0,
    posted: 1
};
C SYNOPSIS
null
config Timer.twer // instance
index URL
XDCscript usage meta-domain
var params = new Timer.Params;
...
params.twer = Timer.Twer {
    mat_wup_ena: 0,
    ovf_wup_ena: 0,
    tcar_wup_ena: 0
};
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:39 GMT


package ti.sysbios.timers.timer64
index URL

Contains specifications for the C64P specific SYS/BIOS functions

XDCspec declarations sourced in ti/sysbios/timers/timer64/package.xdc
requires ti.sysbios.interfaces;
package ti.sysbios.timers.timer64 [2, 0, 0, 0] {
    module Timer;
    // Timer Peripheral Manager
    module TimestampProvider;
    // Provides dm6446 specific timestamp APIs to xdc.runtime.Timestamp
}
generated on Fri, 17 Jun 2011 00:22:37 GMT


module ti.sysbios.timers.timer64.Timer
index URL

Timer Peripheral Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This Timer module manages the timer64 peripheral available on many devices. It is supported on the ARM and c64x+ DSP targets. This module supports the timer in '32-bit chained' and '32-bit unchained' mode. In the '32-bit unchained' mode, specify the lower or upper half to be use. The physical timer being used will be taken out of reset, only when its specified to be the master. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/timers/timer64/Timer.xdc
#include <ti/sysbios/timers/timer64/Timer.h>
Functions
Void | Timer_construct// Initialize a new instance object inside the provided structure(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Timer_Handle | Timer_create// Allocate and initialize a new instance object and return its handle(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
Void | Timer_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Timer_Handle *handleP);
Void | Timer_destruct// Finalize the instance object inside the provided structure(Timer_Struct *structP);
Void | Timer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Timer_Params *params);
Void | Timer_reconfig// Used to modify static timer instances at runtime(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
Functions common to all ITimer modules
UInt32 | Timer_getCount// Read timer counter register(Timer_Handle handle);
Void | Timer_getFreq// Return timer frequency in Hz(Timer_Handle handle, Types_FreqHz *freq);
ITimer_FuncPtr | Timer_getFunc// Get Timer function and arg(Timer_Handle handle, UArg *arg);
UInt | Timer_getNumTimers// Returns number of timer peripherals on the platform();
UInt32 | Timer_getPeriod// Get timer period in timer counts(Timer_Handle handle);
ITimer_Status | Timer_getStatus// Returns timer status (free or in use)(UInt id);
Void | Timer_setFunc// Overwrite Timer function and arg(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
Void | Timer_setPeriod// Set timer period specified in timer counts(Timer_Handle handle, UInt32 period);
Bool | Timer_setPeriodMicroSecs// Set timer period specified in microseconds(Timer_Handle handle, UInt32 microsecs);
Void | Timer_start// Reload and start the timer(Timer_Handle handle);
Void | Timer_stop// Stop the timer(Timer_Handle handle);
Functions common to all target instances
 | Timer_handle// Convert this instance structure pointer into an instance handle, Timer_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, Timer_Handle_label// The label associated with this instance object, Timer_Handle_name// The name of this instance object, Timer_Handle_upCast// unconditionally move one level up the inheritance hierarchy, Timer_Object_count// The number of statically-created instance objects, Timer_Object_first// The handle of the first dynamically-created instance object, or NULL, Timer_Object_get// The handle of the i-th statically-created instance object (array == NULL), Timer_Object_heap// The heap used to allocate dynamically-created instance objects, Timer_Object_next// The handle of the next dynamically-created instance object, or NULL, Timer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Timer_Module_getMask// Returns the diagnostics mask for this module, Timer_Module_hasMask// Test whether this module has a diagnostics mask, Timer_Module_heap// The heap from which this module allocates memory, Timer_Module_id// Get this module's unique id, Timer_Module_setMask// Set the diagnostics mask for this module, Timer_Module_startupDone// Test if this module has completed startup
Defines
#define | Timer_ANY// Const used to specify any timer (UInt)~0
#define | Timer_MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS (UInt)0xffffffff
Typedefs
typedef struct | Timer_Control// Timer Control Register struct ...
typedef struct | Timer_EmuMgt// Timer Emulation Management Register struct ...
typedef Void | (*Timer_FuncPtr// Timer tick function prototype)(UArg);
typedef struct | Timer_GpioDatDir// Timer GPIO Data and Direction Management Register struct ...
typedef struct | Timer_GpioIntEn// Timer GPIO interrupt control and enable Management Register struct ...
typedef enum | Timer_Half// In 32-bit modes, used to specify which half of Timer to use ...
typedef Timer_Object * | Timer_Handle// Client reference to an instance object;
typedef enum | Timer_Mode// The different modes of the Timer. These values match the TIMMODE bit fields of the Timer Global Control Register ...
typedef struct | Timer_Object// Opaque internal representation of an instance object Timer_Object;
typedef struct | Timer_Params// Instance config-params structure ...
typedef enum | Timer_PeriodType// Timer period units ...
typedef enum | Timer_RunMode// Timer Run Modes ...
typedef enum | Timer_StartMode// Timer Start Modes ...
typedef enum | Timer_Status// Timer Status ...
typedef struct | Timer_Struct// Opaque client structure large enough to hold an instance object Timer_Struct;
typedef struct | Timer_TimerSetting// Timer Settings ...
Constants
extern const Bits32 | Timer_anyMask// Available mask to be used when select = Timer_ANY. Set in xs file;
extern const Assert_Id | Timer_A_notAvailable// Assert raised when static created timer is not available;
extern const Timer_Half | Timer_defaultHalf// The default 32-bit half of the timer to be used;
extern const Error_Id | Timer_E_cannotSupport// Error raised when period requested is not supported;
extern const Error_Id | Timer_E_invalidTimer// Error raised when timer id specified is not supported;
extern const Error_Id | Timer_E_notAvailable// Error raised when timer requested is in use;
extern const Timer_TimerSetting | Timer_timerSettings// Global Control configuration for each physical timer[];
DETAILS
This Timer module manages the timer64 peripheral available on many devices. It is supported on the ARM and c64x+ DSP targets. This module supports the timer in '32-bit chained' and '32-bit unchained' mode. In the '32-bit unchained' mode, specify the lower or upper half to be use. The physical timer being used will be taken out of reset, only when its specified to be the master.
For shared timers on a homogeneous multicore device (ie. c6472), each core can create the timer, but only one core will initialize the timer and take it out of reset. The core that does the initialization can be specified by the module configuration parameter timerSettings[].ownerCoreId in the *.cfg file. By default, Core 0 is the owner for all shared timers.
Note: Creating a timer with 'Timer.ANY' specified as the id will not return a shared timer on a homogeneous multicore device. To use a shared timer, specify the timer id explicitly when creating it. On these devices Timer.ANY specifies the local timer id. This allows a single image to run on multiple cores since each core will program a different local timer.
The following sample .cfg code sets core 1 to initialize a shared timer with id 4.
  var Timer = xdc.useModule('ti.sysbios.timers.timer64.Timer');

  // sets core 1 to init and release Timer 4.
  Timer.timerSettings[4].ownerCoreId = 1;
The following sample .cfg code sets core 0 to initialize a shared timer with id 4. It also configures the Clock module to use this timer. This allows multiple cores to share timer 4 for the Clock module's interrupt source.
  // sets core 0 to init and release Timer 4.
  var Timer = xdc.useModule('ti.sysbios.timers.timer64.Timer');
  Timer.timerSettings[4].ownerCoreId = 0;

  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
  Clock.timerId = 4;

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getNumTimers | Y | Y | Y | Y | N
getStatus | Y | Y | Y | Y | N
Params_init | Y | Y | Y | Y | N
construct | Y | Y | Y | Y | N
create | N | N | Y | Y | N
delete | N | N | Y | Y | N
destruct | Y | Y | Y | Y | N
getCount | Y | Y | Y | N | N
getFreq | Y | Y | Y | Y | N
getFunc | Y | Y | Y | Y | N
getPeriod | Y | Y | Y | Y | N
reconfig | Y | Y | Y | Y | N
setFunc | Y | Y | Y | Y | N
setPeriod | Y | Y | Y | Y | N
setPeriodMicroSecs | Y | Y | Y | Y | N
start | Y | Y | Y | N | N
stop | Y | Y | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).

Timer Mapping Tables

The Timer module allows the user to use and configure the various timers that exist on a particular device. This is achieved by specifying a timer ID when calling ti.sysbios.hal.Timer.Timer_create. However, the timer ID specified may not always map to that timer; for example, specifying an ID value of 1 does not necessarily mean that this will map to "GPTimer1". These tables are provided to show which timers map to which timer IDs.

Timer Mapping Tables
const Timer_ANY
index URL

Const used to specify any timer

C synopsis target-domain
#define Timer_ANY (UInt)~0
const Timer_MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

C synopsis target-domain
#define Timer_MAX_PERIOD (UInt)0xffffffff
enum Timer_Half
index URL

In 32-bit modes, used to specify which half of Timer to use

C synopsis target-domain
typedef enum Timer_Half {
    Timer_Half_LOWER,
    Timer_Half_UPPER,
    Timer_Half_DEFAULT
} Timer_Half;
enum Timer_Mode
index URL

The different modes of the Timer. These values match the TIMMODE bit fields of the Timer Global Control Register

C synopsis target-domain
typedef enum Timer_Mode {
    Timer_Mode_64BITGPTIMER,
    Timer_Mode_UNCHAINED,
    Timer_Mode_WATCHDOG,
    Timer_Mode_CHAINED
} Timer_Mode;
enum Timer_PeriodType
index URL

Timer period units

C synopsis target-domain
typedef enum Timer_PeriodType {
    Timer_PeriodType_MICROSECS,
    // period in microsecs
    Timer_PeriodType_COUNTS
    // period in counts
} Timer_PeriodType;
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
enum Timer_RunMode
index URL

Timer Run Modes

C synopsis target-domain
typedef enum Timer_RunMode {
    Timer_RunMode_CONTINUOUS,
    // periodic and continuous
    Timer_RunMode_ONESHOT,
    // one-shot
    Timer_RunMode_DYNAMIC
    // dynamically reprogrammed
} Timer_RunMode;
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
enum Timer_StartMode
index URL

Timer Start Modes

C synopsis target-domain
typedef enum Timer_StartMode {
    Timer_StartMode_AUTO,
    // timer starts automatically
    Timer_StartMode_USER
    // timer will be started by user
} Timer_StartMode;
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
enum Timer_Status
index URL

Timer Status

C synopsis target-domain
typedef enum Timer_Status {
    Timer_Status_INUSE,
    // timer in use
    Timer_Status_FREE
    // timer is free
} Timer_Status;
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
typedef Timer_FuncPtr
index URL

Timer tick function prototype

C synopsis target-domain
typedef Void (*Timer_FuncPtr)(UArg);
struct Timer_Control
index URL

Timer Control Register struct

C synopsis target-domain
typedef struct Timer_Control {
    Bits8 tien;
    // 0=Clock not gated by TINP; 1=Clock gated
    Bits8 invout;
    // 0=Uninverted TSTAT drives TOUT; 1=Inverted TSTAT
    Bits8 invin;
    // 0=Uninverted TINP drives Timer; 1=Inverted TINP
    UInt8 pwid;
    // TSTATx goes inactive after pwid cycles (CP=0)
    Bits8 cp;
    // 0=pulse mode; 1=clock mode
} Timer_Control;
struct Timer_EmuMgt
index URL

Timer Emulation Management Register struct

C synopsis target-domain
typedef struct Timer_EmuMgt {
    Bool free;
    // 0=suspend for emu halt; 1=don't suspend
    Bool soft;
    // 0=stop immediately; 1=stop when count==period
} Timer_EmuMgt;
struct Timer_GpioDatDir
index URL

Timer GPIO Data and Direction Management Register struct

C synopsis target-domain
typedef struct Timer_GpioDatDir {
    Bits8 gpio_dati12;
    // 0=TINP12 is input; 1=TINP12 is output
    Bits8 gpio_dato12;
    // 0=TOUTP12 is input; 1=TOUTP12 is output
    Bits8 gpio_dati34;
    // 0=TINP34 is input; 1=TINP34 is output
    Bits8 gpio_dato34;
    // 0=TOUTP34 is input; 1=TOUTP34 is output
    Bits8 gpio_diri12;
    // 0=input as GPIO input; 1=input as GPIO output
    Bits8 gpio_diro12;
    // 0=output as GPIO input;1=output as GPIO output
    Bits8 gpio_diri34;
    // 0=input as GPIO input; 1=input as GPIO output
    Bits8 gpio_diro34;
    // 0=output as GPIO input;1=output as GPIO output
} Timer_GpioDatDir;
struct Timer_GpioIntEn
index URL

Timer GPIO interrupt control and enable Management Register struct

C synopsis target-domain
typedef struct Timer_GpioIntEn {
    Bits8 gpint12_eni;
    // 0=source by timer; 1=input to source event
    Bits8 gpint12_eno;
    // 0=source by timer; 1=output to source event
    Bits8 gpint12_invi;
    // 0=don't invert invput; 1=invert input
    Bits8 gpint12_invo;
    // 0=don't invert output; 1=invert output
    Bits8 gpint34_eni;
    // 0=source by timer; 1=input to source event
    Bits8 gpint34_eno;
    // 0=source by timer; 1=output to source event
    Bits8 gpint34_invi;
    // 0=don't invert invput; 1=invert input
    Bits8 gpint34_invo;
    // 0=don't invert output; 1=invert output
    Bits8 gpio_eni12;
    // 0=TINP12 as timer input; 1=TINP12 as GPIO
    Bits8 gpio_eno12;
    // 0=TOUTP12 as timer output; 1=TOUTP12 as GPIO
    Bits8 gpio_eni34;
    // 0=TINP34 as timer input; 1=TINP34 as GPIO
    Bits8 gpio_eno34;
    // 0=TOUTP34 as timer output; 1=TOUTP12 as GPIO
} Timer_GpioIntEn;
struct Timer_TimerSetting
index URL

Timer Settings

C synopsis target-domain
typedef struct Timer_TimerSetting {
     Timer_Mode mode;
    // mode to put each Timer into
    Bool master;
    // for 'unchained' mode; 1=set mode and reset
    UInt16 ownerCoreId;
    // used only for homogeneous multicore DSPs
} Timer_TimerSetting;
config Timer_A_notAvailable // module-wide
index URL

Assert raised when static created timer is not available

C synopsis target-domain
extern const Assert_Id Timer_A_notAvailable;
config Timer_E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

C synopsis target-domain
extern const Error_Id Timer_E_cannotSupport;
config Timer_E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

C synopsis target-domain
extern const Error_Id Timer_E_invalidTimer;
config Timer_E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

C synopsis target-domain
extern const Error_Id Timer_E_notAvailable;
config Timer_anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

C synopsis target-domain
extern const Bits32 Timer_anyMask;
config Timer_defaultHalf // module-wide
index URL

The default 32-bit half of the timer to be used

C synopsis target-domain
extern const Timer_Half Timer_defaultHalf;
config Timer_timerSettings // module-wide
index URL

Global Control configuration for each physical timer

C synopsis target-domain
extern const Timer_TimerSetting Timer_timerSettings[];
DETAILS
mode: Mode_UNCHAINED 32-bit unchained mode. master: TRUE If TRUE, release Timer from reset.
Timer_getNumTimers() // module-wide
index URL

Returns number of timer peripherals on the platform

C synopsis target-domain
UInt Timer_getNumTimers();
RETURNS
Number of timer peripherals.
Timer_getStatus() // module-wide
index URL

Returns timer status (free or in use)

C synopsis target-domain
ITimer_Status Timer_getStatus(UInt id);
RETURNS
timer status
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timer_Module_id();
// Get this module's unique id
Bool Timer_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timer_Module_heap();
// The heap from which this module allocates memory
Bool Timer_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timer_Module_getMask();
// Returns the diagnostics mask for this module
Void Timer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Timer_Object Timer_Object;
// Opaque internal representation of an instance object
typedef Timer_Object *Timer_Handle;
// Client reference to an instance object
typedef struct Timer_Struct Timer_Struct;
// Opaque client structure large enough to hold an instance object
Timer_Handle Timer_handle(Timer_Struct *structP);
// Convert this instance structure pointer into an instance handle
Timer_Struct *Timer_struct(Timer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Timer_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg arg;
    // Argument for tick function
     Timer_Control controlInit;
    // Control configuration. Default is all fields 0 or false except:
     Timer_EmuMgt emuMgtInit;
    // Emulation Management configuration. Default is:
     Types_FreqHz extFreq;
    // Timer frequency
     Timer_GpioDatDir gpioDatDir;
    // General Purpose IO data and direction Management configuration The default is all fields is 0
     Timer_GpioIntEn gpioIntEn;
    // General Purpose IO interrupt control and enable Management configuration. The default for all fields is 0
     Timer_Half half;
    // In 32-bit unchained mode, this field is used to specify which half of the timer to use
     Hwi_Params *hwiParams;
    // Hwi Params for Hwi Object. Default is null
    Int intNum;
    // Hwi interrupt number to be used by Timer
    UInt32 period;
    // Period of a tick
     ITimer_PeriodType periodType;
    // Period type
    UInt prescalar;
    // 32-bit pre-scalar to TIM12 in '32-bit chained' mode. The default is 0
     ITimer_RunMode runMode;
    // Timer run mode
     ITimer_StartMode startMode;
    // Timer start mode
} Timer_Params;
Void Timer_Params_init(Timer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Timer_arg // instance
index URL

Argument for tick function

C synopsis target-domain
struct Timer_Params {
     ...
    UArg arg;
DETAILS
Default is null.
config Timer_controlInit // instance
index URL

Control configuration. Default is all fields 0 or false except:

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Control controlInit;
DETAILS
pwid: 1
config Timer_emuMgtInit // instance
index URL

Emulation Management configuration. Default is:

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_EmuMgt emuMgtInit;
DETAILS
free: 0 soft: 0
config Timer_extFreq // instance
index URL

Timer frequency

C synopsis target-domain
struct Timer_Params {
     ...
     Types_FreqHz extFreq;
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
config Timer_gpioDatDir // instance
index URL

General Purpose IO data and direction Management configuration The default is all fields is 0

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_GpioDatDir gpioDatDir;
config Timer_gpioIntEn // instance
index URL

General Purpose IO interrupt control and enable Management configuration. The default for all fields is 0

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_GpioIntEn gpioIntEn;
config Timer_half // instance
index URL

In 32-bit unchained mode, this field is used to specify which half of the timer to use

C synopsis target-domain
struct Timer_Params {
     ...
     Timer_Half half;
config Timer_hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

C synopsis target-domain
struct Timer_Params {
     ...
     Hwi_Params *hwiParams;
config Timer_intNum // instance
index URL

Hwi interrupt number to be used by Timer

C synopsis target-domain
struct Timer_Params {
     ...
    Int intNum;
config Timer_period // instance
index URL

Period of a tick

C synopsis target-domain
struct Timer_Params {
     ...
    UInt32 period;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
config Timer_periodType // instance
index URL

Period type

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_PeriodType periodType;
DETAILS
Default is PeriodType_MICROSECS
config Timer_prescalar // instance
index URL

32-bit pre-scalar to TIM12 in '32-bit chained' mode. The default is 0

C synopsis target-domain
struct Timer_Params {
     ...
    UInt prescalar;
config Timer_runMode // instance
index URL

Timer run mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_RunMode runMode;
DETAILS
Default is RunMode_CONTINUOUS.
config Timer_startMode // instance
index URL

Timer start mode

C synopsis target-domain
struct Timer_Params {
     ...
     ITimer_StartMode startMode;
DETAILS
Default is StartMode_AUTO.
Instance Creation
index URL

C synopsis target-domain
Timer_Handle Timer_create(Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Timer_construct(Timer_Struct *structP, Int id, ITimer_FuncPtr tickFxn, const Timer_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
Instance Deletion
index URL

C synopsis target-domain
Void Timer_delete(Timer_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Timer_destruct(Timer_Struct *structP);
// Finalize the instance object inside the provided structure
Timer_getCount() // instance
index URL

Read timer counter register

C synopsis target-domain
UInt32 Timer_getCount(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
timer counter value
Timer_getFreq() // instance
index URL

Return timer frequency in Hz

C synopsis target-domain
Void Timer_getFreq(Timer_Handle handle, Types_FreqHz *freq);
ARGUMENTS
handle — handle of a previously-created Timer instance object
freq — frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer counter register after all scaling factors are taken into account. (including pre-scalars).
Timer_getFunc() // instance
index URL

Get Timer function and arg

C synopsis target-domain
ITimer_FuncPtr Timer_getFunc(Timer_Handle handle, UArg *arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
arg — pointer for returning Timer's function argument
RETURNS
Timer's function
Timer_getPeriod() // instance
index URL

Get timer period in timer counts

C synopsis target-domain
UInt32 Timer_getPeriod(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
RETURNS
period in timer counts
Timer_reconfig() // instance
index URL

Used to modify static timer instances at runtime

C synopsis target-domain
Void Timer_reconfig(Timer_Handle handle, Timer_FuncPtr tickFxn, Timer_Params *timerParams, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Timer instance object
timerParams — timer Params
tickFxn — functions that runs when timer expires
Timer_setFunc() // instance
index URL

Overwrite Timer function and arg

C synopsis target-domain
Void Timer_setFunc(Timer_Handle handle, ITimer_FuncPtr fxn, UArg arg);
ARGUMENTS
handle — handle of a previously-created Timer instance object
fxn — pointer to function
arg — argument to function
DETAILS
Replaces a Timer object's tickFxn function originally provided in create.
Timer_setPeriod() // instance
index URL

Set timer period specified in timer counts

C synopsis target-domain
Void Timer_setPeriod(Timer_Handle handle, UInt32 period);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriod(period);
  Timer_start();
  Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
Timer_setPeriodMicroSecs() // instance
index URL

Set timer period specified in microseconds

C synopsis target-domain
Bool Timer_setPeriodMicroSecs(Timer_Handle handle, UInt32 microsecs);
ARGUMENTS
handle — handle of a previously-created Timer instance object
period — period in microseconds
DETAILS
A best-effort method will be used to set the period register. There might be a slight rounding error based on resolution of timer period register. If the timer frequency cannot support the requested period, i.e. the timer period register cannot support the requested period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must protect against re-entrancy by disabling interrupts. Use the following call sequence to guarantee proper results:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_setPeriodMicroSecs(period);
  Timer_start();
  Hwi_restore(key);
Timer_start() // instance
index URL

Reload and start the timer

C synopsis target-domain
Void Timer_start(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Enables the timer's interrupt.
Timer_stop() // instance
index URL

Stop the timer

C synopsis target-domain
Void Timer_stop(Timer_Handle handle);
ARGUMENTS
handle — handle of a previously-created Timer instance object
DETAILS
Thread safety must be observed when using the start and stop APIs to avoid possible miss- configuration of the timers and unintended behaviors. To protect against re-entrancy, surround the start/stop invocations with Hwi_disable() and Hwi_restore() calls:
  // disable interrupts if an interrupt could lead to
  // another call to Timer_start().
  key = Hwi_disable();
  Timer_stop();
  ...
  Timer_start();
  Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.
Instance Convertors
index URL

C synopsis target-domain
ITimer_Handle Timer_Handle_upCast(Timer_Handle handle);
// unconditionally move one level up the inheritance hierarchy
Timer_Handle Timer_Handle_downCast(ITimer_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Timer_Object_count();
// The number of statically-created instance objects
Timer_Handle Timer_Object_get(Timer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Timer_Handle Timer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Timer_Handle Timer_Object_next(Timer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Timer_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Timer_Handle_label(Timer_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Timer_Handle_name(Timer_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in ti/sysbios/timers/timer64/Timer.xdc
var Timer = xdc.useModule('ti.sysbios.timers.timer64.Timer');
module-wide constants & types
    const Timer.ANY// Const used to specify any timer = ~0;
    const Timer.MAX_PERIOD// Max value of Timer period for PeriodType_COUNTS = 0xffffffff;
    values of type Timer.Half// In 32-bit modes, used to specify which half of Timer to use
        const Timer.Half_LOWER;
        const Timer.Half_UPPER;
        const Timer.Half_DEFAULT;
    values of type Timer.Mode// The different modes of the Timer. These values match the TIMMODE bit fields of the Timer Global Control Register
        const Timer.Mode_64BITGPTIMER;
        const Timer.Mode_UNCHAINED;
        const Timer.Mode_WATCHDOG;
        const Timer.Mode_CHAINED;
    values of type Timer.PeriodType// Timer period units
        const Timer.PeriodType_MICROSECS// period in microsecs;
        const Timer.PeriodType_COUNTS// period in counts;
    values of type Timer.RunMode// Timer Run Modes
        const Timer.RunMode_CONTINUOUS// periodic and continuous;
        const Timer.RunMode_ONESHOT// one-shot;
        const Timer.RunMode_DYNAMIC// dynamically reprogrammed;
    values of type Timer.StartMode// Timer Start Modes
        const Timer.StartMode_AUTO// timer starts automatically;
        const Timer.StartMode_USER// timer will be started by user;
    values of type Timer.Status// Timer Status
        const Timer.Status_INUSE// timer in use;
        const Timer.Status_FREE// timer is free;
    var obj = new Timer.Control// Timer Control Register struct;
        obj.tien// 0=Clock not gated by TINP; 1=Clock gated = Bits8 ...
        obj.invout// 0=Uninverted TSTAT drives TOUT; 1=Inverted TSTAT = Bits8 ...
        obj.invin// 0=Uninverted TINP drives Timer; 1=Inverted TINP = Bits8 ...
        obj.pwid// TSTATx goes inactive after pwid cycles (CP=0) = UInt8 ...
        obj.cp// 0=pulse mode; 1=clock mode = Bits8 ...
    var obj = new Timer.EmuMgt// Timer Emulation Management Register struct;
        obj.free// 0=suspend for emu halt; 1=don't suspend = Bool ...
        obj.soft// 0=stop immediately; 1=stop when count==period = Bool ...
    var obj = new Timer.GpioDatDir// Timer GPIO Data and Direction Management Register struct;
        obj.gpio_dati12// 0=TINP12 is input; 1=TINP12 is output = Bits8 ...
        obj.gpio_dato12// 0=TOUTP12 is input; 1=TOUTP12 is output = Bits8 ...
        obj.gpio_dati34// 0=TINP34 is input; 1=TINP34 is output = Bits8 ...
        obj.gpio_dato34// 0=TOUTP34 is input; 1=TOUTP34 is output = Bits8 ...
        obj.gpio_diri12// 0=input as GPIO input; 1=input as GPIO output = Bits8 ...
        obj.gpio_diro12// 0=output as GPIO input;1=output as GPIO output = Bits8 ...
        obj.gpio_diri34// 0=input as GPIO input; 1=input as GPIO output = Bits8 ...
        obj.gpio_diro34// 0=output as GPIO input;1=output as GPIO output = Bits8 ...
    var obj = new Timer.GpioIntEn// Timer GPIO interrupt control and enable Management Register struct;
        obj.gpint12_eni// 0=source by timer; 1=input to source event = Bits8 ...
        obj.gpint12_eno// 0=source by timer; 1=output to source event = Bits8 ...
        obj.gpint12_invi// 0=don't invert invput; 1=invert input = Bits8 ...
        obj.gpint12_invo// 0=don't invert output; 1=invert output = Bits8 ...
        obj.gpint34_eni// 0=source by timer; 1=input to source event = Bits8 ...
        obj.gpint34_eno// 0=source by timer; 1=output to source event = Bits8 ...
        obj.gpint34_invi// 0=don't invert invput; 1=invert input = Bits8 ...
        obj.gpint34_invo// 0=don't invert output; 1=invert output = Bits8 ...
        obj.gpio_eni12// 0=TINP12 as timer input; 1=TINP12 as GPIO = Bits8 ...
        obj.gpio_eno12// 0=TOUTP12 as timer output; 1=TOUTP12 as GPIO = Bits8 ...
        obj.gpio_eni34// 0=TINP34 as timer input; 1=TINP34 as GPIO = Bits8 ...
        obj.gpio_eno34// 0=TOUTP34 as timer output; 1=TOUTP12 as GPIO = Bits8 ...
    var obj = new Timer.TimerSetting// Timer Settings;
        obj.mode// mode to put each Timer into = Timer.Mode ...
        obj.master// for 'unchained' mode; 1=set mode and reset = Bool ...
        obj.ownerCoreId// used only for homogeneous multicore DSPs = UInt16 ...
module-wide config parameters
     Timer.A_notAvailable// Assert raised when static created timer is not available = Assert.Desc {
        msg: "A_notAvailable: static created timer not available"
    };
     Timer.E_cannotSupport// Error raised when period requested is not supported = Error.Desc {
        msg: "E_cannotSupport: Timer cannot support requested period %d"
    };
     Timer.E_invalidTimer// Error raised when timer id specified is not supported = Error.Desc {
        msg: "E_invalidTimer: Invalid Timer Id %d"
    };
     Timer.E_notAvailable// Error raised when timer requested is in use = Error.Desc {
        msg: "E_notAvailable: Timer not available %d"
    };
     Timer.anyMask// Available mask to be used when select = Timer_ANY. Set in xs file = Bits32 undefined;
     Timer.defaultHalf// The default 32-bit half of the timer to be used = Timer.Half Timer.Half_LOWER;
     Timer.timerSettings// Global Control configuration for each physical timer = Timer.TimerSetting[] [ ];
     Timer.common$// Common module configuration parameters = Types.Common$ undefined;
     Timer.intFreqs// Internal frequency for Timers = Types.FreqHz[] undefined;
per-instance config parameters
    var params = new Timer.Params// Instance config-params object;
        params.arg// Argument for tick function = UArg null;
        params.controlInit// Control configuration. Default is all fields 0 or false except: = Timer.Control {
            tien: 0,
            invout: 0,
            invin: 0,
            pwid: 1,
            cp: 0
        };
        params.emuMgtInit// Emulation Management configuration. Default is: = Timer.EmuMgt {
            free: 0,
            soft: 0
        };
        params.extFreq// Timer frequency = Types.FreqHz {
            lo: 0,
            hi: 0
        };
        params.gpioDatDir// General Purpose IO data and direction Management configuration The default is all fields is 0 = Timer.GpioDatDir {
            gpio_dati12: 0,
            gpio_dato12: 0,
            gpio_dati34: 0,
            gpio_dato34: 0,
            gpio_diri12: 0,
            gpio_diro12: 0,
            gpio_diri34: 0,
            gpio_diro34: 0
        };
        params.gpioIntEn// General Purpose IO interrupt control and enable Management configuration. The default for all fields is 0 = Timer.GpioIntEn {
            gpint12_eni: 0,
            gpint12_eno: 0,
            gpint12_invi: 0,
            gpint12_invo: 0,
            gpint34_eni: 0,
            gpint34_eno: 0,
            gpint34_invi: 0,
            gpint34_invo: 0,
            gpio_eni12: 0,
            gpio_eno12: 0,
            gpio_eni34: 0,
            gpio_eno34: 0
        };
        params.half// In 32-bit unchained mode, this field is used to specify which half of the timer to use = Timer.Half Timer.Half_DEFAULT;
        params.hwiParams// Hwi Params for Hwi Object. Default is null = Hwi.Params* null;
        params.intNum// Hwi interrupt number to be used by Timer = Int -1;
        params.period// Period of a tick = UInt32 0;
        params.periodType// Period type = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
        params.prescalar// 32-bit pre-scalar to TIM12 in '32-bit chained' mode. The default is 0 = UInt 0;
        params.runMode// Timer run mode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
        params.startMode// Timer start mode = ITimer.StartMode ITimer.StartMode_AUTO;
per-instance creation
    var inst = Timer.create// Create an instance-object(Int id, Void(*)(UArg) tickFxn, params);
const Timer.ANY
index URL

Const used to specify any timer

XDCscript usage meta-domain
const Timer.ANY = ~0;
C SYNOPSIS
Timer_ANY
const Timer.MAX_PERIOD
index URL

Max value of Timer period for PeriodType_COUNTS

XDCscript usage meta-domain
const Timer.MAX_PERIOD = 0xffffffff;
C SYNOPSIS
Timer_MAX_PERIOD
enum Timer.Half
index URL

In 32-bit modes, used to specify which half of Timer to use

XDCscript usage meta-domain
values of type Timer.Half
    const Timer.Half_LOWER;
    const Timer.Half_UPPER;
    const Timer.Half_DEFAULT;
C SYNOPSIS
Timer_Half
enum Timer.Mode
index URL

The different modes of the Timer. These values match the TIMMODE bit fields of the Timer Global Control Register

XDCscript usage meta-domain
values of type Timer.Mode
    const Timer.Mode_64BITGPTIMER;
    const Timer.Mode_UNCHAINED;
    const Timer.Mode_WATCHDOG;
    const Timer.Mode_CHAINED;
C SYNOPSIS
Timer_Mode
enum Timer.PeriodType
index URL

Timer period units

XDCscript usage meta-domain
values of type Timer.PeriodType
    const Timer.PeriodType_MICROSECS;
    // period in microsecs
    const Timer.PeriodType_COUNTS;
    // period in counts
VALUES
PeriodType_MICROSECS — Period value is in microseconds.
PeriodType_COUNTS — Period value is in counts.
C SYNOPSIS
Timer_PeriodType
enum Timer.RunMode
index URL

Timer Run Modes

XDCscript usage meta-domain
values of type Timer.RunMode
    const Timer.RunMode_CONTINUOUS;
    // periodic and continuous
    const Timer.RunMode_ONESHOT;
    // one-shot
    const Timer.RunMode_DYNAMIC;
    // dynamically reprogrammed
VALUES
RunMode_CONTINUOUS — Timer is periodic and runs continuously.
RunMode_ONESHOT — Timer runs for a single period value and stops.
RunMode_DYNAMIC — Timer is dynamically reprogrammed for the next required tick.
C SYNOPSIS
Timer_RunMode
enum Timer.StartMode
index URL

Timer Start Modes

XDCscript usage meta-domain
values of type Timer.StartMode
    const Timer.StartMode_AUTO;
    // timer starts automatically
    const Timer.StartMode_USER;
    // timer will be started by user
VALUES
StartMode_AUTO — Statically created/constructed Timers will be started in BIOS_start(). Dynamically created Timers will start at create() time. This includes timers created before BIOS_start().
StartMode_USER — Timer will be started by the user using start().
C SYNOPSIS
Timer_StartMode
enum Timer.Status
index URL

Timer Status

XDCscript usage meta-domain
values of type Timer.Status
    const Timer.Status_INUSE;
    // timer in use
    const Timer.Status_FREE;
    // timer is free
VALUES
Status_INUSE — Timer is in use. A timer is marked in use from the time it gets created to the time it gets deleted.
Status_FREE — Timer is free and can be acquired using create.
C SYNOPSIS
Timer_Status
struct Timer.Control
index URL

Timer Control Register struct

XDCscript usage meta-domain
var obj = new Timer.Control;
    obj.tien = Bits8 ...
    // 0=Clock not gated by TINP; 1=Clock gated
    obj.invout = Bits8 ...
    // 0=Uninverted TSTAT drives TOUT; 1=Inverted TSTAT
    obj.invin = Bits8 ...
    // 0=Uninverted TINP drives Timer; 1=Inverted TINP
    obj.pwid = UInt8 ...
    // TSTATx goes inactive after pwid cycles (CP=0)
    obj.cp = Bits8 ...
    // 0=pulse mode; 1=clock mode
C SYNOPSIS
Timer_Control
struct Timer.EmuMgt
index URL

Timer Emulation Management Register struct

XDCscript usage meta-domain
var obj = new Timer.EmuMgt;
    obj.free = Bool ...
    // 0=suspend for emu halt; 1=don't suspend
    obj.soft = Bool ...
    // 0=stop immediately; 1=stop when count==period
C SYNOPSIS
Timer_EmuMgt
struct Timer.GpioDatDir
index URL

Timer GPIO Data and Direction Management Register struct

XDCscript usage meta-domain
var obj = new Timer.GpioDatDir;
    obj.gpio_dati12 = Bits8 ...
    // 0=TINP12 is input; 1=TINP12 is output
    obj.gpio_dato12 = Bits8 ...
    // 0=TOUTP12 is input; 1=TOUTP12 is output
    obj.gpio_dati34 = Bits8 ...
    // 0=TINP34 is input; 1=TINP34 is output
    obj.gpio_dato34 = Bits8 ...
    // 0=TOUTP34 is input; 1=TOUTP34 is output
    obj.gpio_diri12 = Bits8 ...
    // 0=input as GPIO input; 1=input as GPIO output
    obj.gpio_diro12 = Bits8 ...
    // 0=output as GPIO input;1=output as GPIO output
    obj.gpio_diri34 = Bits8 ...
    // 0=input as GPIO input; 1=input as GPIO output
    obj.gpio_diro34 = Bits8 ...
    // 0=output as GPIO input;1=output as GPIO output
C SYNOPSIS
Timer_GpioDatDir
struct Timer.GpioIntEn
index URL

Timer GPIO interrupt control and enable Management Register struct

XDCscript usage meta-domain
var obj = new Timer.GpioIntEn;
    obj.gpint12_eni = Bits8 ...
    // 0=source by timer; 1=input to source event
    obj.gpint12_eno = Bits8 ...
    // 0=source by timer; 1=output to source event
    obj.gpint12_invi = Bits8 ...
    // 0=don't invert invput; 1=invert input
    obj.gpint12_invo = Bits8 ...
    // 0=don't invert output; 1=invert output
    obj.gpint34_eni = Bits8 ...
    // 0=source by timer; 1=input to source event
    obj.gpint34_eno = Bits8 ...
    // 0=source by timer; 1=output to source event
    obj.gpint34_invi = Bits8 ...
    // 0=don't invert invput; 1=invert input
    obj.gpint34_invo = Bits8 ...
    // 0=don't invert output; 1=invert output
    obj.gpio_eni12 = Bits8 ...
    // 0=TINP12 as timer input; 1=TINP12 as GPIO
    obj.gpio_eno12 = Bits8 ...
    // 0=TOUTP12 as timer output; 1=TOUTP12 as GPIO
    obj.gpio_eni34 = Bits8 ...
    // 0=TINP34 as timer input; 1=TINP34 as GPIO
    obj.gpio_eno34 = Bits8 ...
    // 0=TOUTP34 as timer output; 1=TOUTP12 as GPIO
C SYNOPSIS
Timer_GpioIntEn
struct Timer.TimerSetting
index URL

Timer Settings

XDCscript usage meta-domain
var obj = new Timer.TimerSetting;
    obj.mode = Timer.Mode ...
    // mode to put each Timer into
    obj.master = Bool ...
    // for 'unchained' mode; 1=set mode and reset
    obj.ownerCoreId = UInt16 ...
    // used only for homogeneous multicore DSPs
C SYNOPSIS
Timer_TimerSetting
config Timer.A_notAvailable // module-wide
index URL

Assert raised when static created timer is not available

XDCscript usage meta-domain
Timer.A_notAvailable = Assert.Desc {
    msg: "A_notAvailable: static created timer not available"
};
C SYNOPSIS
Timer_A_notAvailable
config Timer.E_cannotSupport // module-wide
index URL

Error raised when period requested is not supported

XDCscript usage meta-domain
Timer.E_cannotSupport = Error.Desc {
    msg: "E_cannotSupport: Timer cannot support requested period %d"
};
C SYNOPSIS
Timer_E_cannotSupport
config Timer.E_invalidTimer // module-wide
index URL

Error raised when timer id specified is not supported

XDCscript usage meta-domain
Timer.E_invalidTimer = Error.Desc {
    msg: "E_invalidTimer: Invalid Timer Id %d"
};
C SYNOPSIS
Timer_E_invalidTimer
config Timer.E_notAvailable // module-wide
index URL

Error raised when timer requested is in use

XDCscript usage meta-domain
Timer.E_notAvailable = Error.Desc {
    msg: "E_notAvailable: Timer not available %d"
};
C SYNOPSIS
Timer_E_notAvailable
config Timer.anyMask // module-wide
index URL

Available mask to be used when select = Timer_ANY. Set in xs file

XDCscript usage meta-domain
Timer.anyMask = Bits32 undefined;
C SYNOPSIS
Timer_anyMask
config Timer.defaultHalf // module-wide
index URL

The default 32-bit half of the timer to be used

XDCscript usage meta-domain
Timer.defaultHalf = Timer.Half Timer.Half_LOWER;
C SYNOPSIS
Timer_defaultHalf
config Timer.timerSettings // module-wide
index URL

Global Control configuration for each physical timer

XDCscript usage meta-domain
Timer.timerSettings = Timer.TimerSetting[] [ ];
DETAILS
mode: Mode_UNCHAINED 32-bit unchained mode. master: TRUE If TRUE, release Timer from reset.
C SYNOPSIS
Timer_timerSettings
metaonly config Timer.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timer.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Timer.intFreqs // module-wide
index URL

Internal frequency for Timers

XDCscript usage meta-domain
Timer.intFreqs = Types.FreqHz[] undefined;
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Instance config-params object
    params.arg = UArg null;
    // Argument for tick function
    params.controlInit = Timer.Control {
    // Control configuration. Default is all fields 0 or false except:
        tien: 0,
        invout: 0,
        invin: 0,
        pwid: 1,
        cp: 0
    };
    params.emuMgtInit = Timer.EmuMgt {
    // Emulation Management configuration. Default is:
        free: 0,
        soft: 0
    };
    params.extFreq = Types.FreqHz {
    // Timer frequency
        lo: 0,
        hi: 0
    };
    params.gpioDatDir = Timer.GpioDatDir {
    // General Purpose IO data and direction Management configuration The default is all fields is 0
        gpio_dati12: 0,
        gpio_dato12: 0,
        gpio_dati34: 0,
        gpio_dato34: 0,
        gpio_diri12: 0,
        gpio_diro12: 0,
        gpio_diri34: 0,
        gpio_diro34: 0
    };
    params.gpioIntEn = Timer.GpioIntEn {
    // General Purpose IO interrupt control and enable Management configuration. The default for all fields is 0
        gpint12_eni: 0,
        gpint12_eno: 0,
        gpint12_invi: 0,
        gpint12_invo: 0,
        gpint34_eni: 0,
        gpint34_eno: 0,
        gpint34_invi: 0,
        gpint34_invo: 0,
        gpio_eni12: 0,
        gpio_eno12: 0,
        gpio_eni34: 0,
        gpio_eno34: 0
    };
    params.half = Timer.Half Timer.Half_DEFAULT;
    // In 32-bit unchained mode, this field is used to specify which half of the timer to use
    params.hwiParams = Hwi.Params* null;
    // Hwi Params for Hwi Object. Default is null
    params.intNum = Int -1;
    // Hwi interrupt number to be used by Timer
    params.period = UInt32 0;
    // Period of a tick
    params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
    // Period type
    params.prescalar = UInt 0;
    // 32-bit pre-scalar to TIM12 in '32-bit chained' mode. The default is 0
    params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
    // Timer run mode
    params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
    // Timer start mode
config Timer.arg // instance
index URL

Argument for tick function

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.arg = UArg null;
DETAILS
Default is null.
C SYNOPSIS
null
config Timer.controlInit // instance
index URL

Control configuration. Default is all fields 0 or false except:

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.controlInit = Timer.Control {
    tien: 0,
    invout: 0,
    invin: 0,
    pwid: 1,
    cp: 0
};
DETAILS
pwid: 1
C SYNOPSIS
null
config Timer.emuMgtInit // instance
index URL

Emulation Management configuration. Default is:

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.emuMgtInit = Timer.EmuMgt {
    free: 0,
    soft: 0
};
DETAILS
free: 0 soft: 0
C SYNOPSIS
null
config Timer.extFreq // instance
index URL

Timer frequency

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.extFreq = Types.FreqHz {
    lo: 0,
    hi: 0
};
DETAILS
This parameter is meaningfull only on platforms where the timer's input clock can be changed. If value is left at zero, then input clock to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds, milliseconds, etc.
C SYNOPSIS
null
config Timer.gpioDatDir // instance
index URL

General Purpose IO data and direction Management configuration The default is all fields is 0

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.gpioDatDir = Timer.GpioDatDir {
    gpio_dati12: 0,
    gpio_dato12: 0,
    gpio_dati34: 0,
    gpio_dato34: 0,
    gpio_diri12: 0,
    gpio_diro12: 0,
    gpio_diri34: 0,
    gpio_diro34: 0
};
C SYNOPSIS
null
config Timer.gpioIntEn // instance
index URL

General Purpose IO interrupt control and enable Management configuration. The default for all fields is 0

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.gpioIntEn = Timer.GpioIntEn {
    gpint12_eni: 0,
    gpint12_eno: 0,
    gpint12_invi: 0,
    gpint12_invo: 0,
    gpint34_eni: 0,
    gpint34_eno: 0,
    gpint34_invi: 0,
    gpint34_invo: 0,
    gpio_eni12: 0,
    gpio_eno12: 0,
    gpio_eni34: 0,
    gpio_eno34: 0
};
C SYNOPSIS
null
config Timer.half // instance
index URL

In 32-bit unchained mode, this field is used to specify which half of the timer to use

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.half = Timer.Half Timer.Half_DEFAULT;
C SYNOPSIS
null
config Timer.hwiParams // instance
index URL

Hwi Params for Hwi Object. Default is null

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.hwiParams = Hwi.Params* null;
C SYNOPSIS
null
config Timer.intNum // instance
index URL

Hwi interrupt number to be used by Timer

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.intNum = Int -1;
C SYNOPSIS
null
config Timer.period // instance
index URL

Period of a tick

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.period = UInt32 0;
DETAILS
The period can be specified in timer counts or microseconds and its default value is 0.
The implementation of ITimer will support a period of UInt32 timer counts and use pre-scalars if necessary.
C SYNOPSIS
null
config Timer.periodType // instance
index URL

Period type

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.periodType = ITimer.PeriodType ITimer.PeriodType_MICROSECS;
DETAILS
Default is PeriodType_MICROSECS
C SYNOPSIS
null
config Timer.prescalar // instance
index URL

32-bit pre-scalar to TIM12 in '32-bit chained' mode. The default is 0

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.prescalar = UInt 0;
C SYNOPSIS
null
config Timer.runMode // instance
index URL

Timer run mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.runMode = ITimer.RunMode ITimer.RunMode_CONTINUOUS;
DETAILS
Default is RunMode_CONTINUOUS.
C SYNOPSIS
null
config Timer.startMode // instance
index URL

Timer start mode

XDCscript usage meta-domain
var params = new Timer.Params;
...
params.startMode = ITimer.StartMode ITimer.StartMode_AUTO;
DETAILS
Default is StartMode_AUTO.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Timer.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Timer.create(Int id, Void(*)(UArg) tickFxn, params);
// Create an instance-object
ARGUMENTS
id — Timer id ranging from 0 to a platform specific value, or ANY
tickFxn — function that runs upon timer expiry.
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
Create could fail if timer peripheral is unavailable. To request any available timer use ANY as the id. TimerId's are logical ids. The family-specific implementations map the ids to physical peripherals.
generated on Fri, 17 Jun 2011 00:22:37 GMT


module ti.sysbios.timers.timer64.TimestampProvider
index URL

Provides dm6446 specific timestamp APIs to xdc.runtime.Timestamp

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements

Calling Context

Function | Hwi | Swi | Task | Main | Startup
get32 | Y | Y | Y | Y | N
get64 | Y | Y | Y | Y | N
getFreq | Y | Y | Y | Y | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).
C synopsis target-domain sourced in ti/sysbios/timers/timer64/TimestampProvider.xdc
#include <ti/sysbios/timers/timer64/TimestampProvider.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampProvider_get32// Return a 32-bit timestamp();
Void | TimestampProvider_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampProvider_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampProvider_Module_getMask// Returns the diagnostics mask for this module, TimestampProvider_Module_hasMask// Test whether this module has a diagnostics mask, TimestampProvider_Module_heap// The heap from which this module allocates memory, TimestampProvider_Module_id// Get this module's unique id, TimestampProvider_Module_setMask// Set the diagnostics mask for this module, TimestampProvider_Module_startupDone// Test if this module has completed startup
Constants
extern const UInt | TimestampProvider_timerId// TimestampProvider timer id. Max id value is 2;
extern const Bool | TimestampProvider_useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module;
config TimestampProvider_timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

C synopsis target-domain
extern const UInt TimestampProvider_timerId;
config TimestampProvider_useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

C synopsis target-domain
extern const Bool TimestampProvider_useClockTimer;
DETAILS
This parameter overrides the timeId setting.
TimestampProvider_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampProvider_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampProvider_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampProvider_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampProvider_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampProvider_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampProvider_Module_id();
// Get this module's unique id
Bool TimestampProvider_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampProvider_Module_heap();
// The heap from which this module allocates memory
Bool TimestampProvider_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampProvider_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampProvider_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/timers/timer64/TimestampProvider.xdc
var TimestampProvider = xdc.useModule('ti.sysbios.timers.timer64.TimestampProvider');
module-wide config parameters
     TimestampProvider.timerId// TimestampProvider timer id. Max id value is 2 = UInt ITimer.ANY;
     TimestampProvider.useClockTimer// Set this parameter when you want TimestampProvider is use the same timer as the Clock module = Bool false;
     TimestampProvider.common$// Common module configuration parameters = Types.Common$ undefined;
config TimestampProvider.timerId // module-wide
index URL

TimestampProvider timer id. Max id value is 2

XDCscript usage meta-domain
TimestampProvider.timerId = UInt ITimer.ANY;
C SYNOPSIS
TimestampProvider_timerId
config TimestampProvider.useClockTimer // module-wide
index URL

Set this parameter when you want TimestampProvider is use the same timer as the Clock module

XDCscript usage meta-domain
TimestampProvider.useClockTimer = Bool false;
DETAILS
This parameter overrides the timeId setting.
C SYNOPSIS
TimestampProvider_useClockTimer
metaonly config TimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampProvider.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:22:37 GMT


package ti.sysbios.utils
index URL

Miscellaneous utility modules

This package contains the Load module, which reports the global CPU load and may be configured to also report thread-specific load.
XDCspec declarations sourced in ti/sysbios/utils/package.xdc
package ti.sysbios.utils [2, 0, 0, 0] {
    module Load;
    // The Load module reports execution times and load information for threads in a system
}
generated on Fri, 17 Jun 2011 00:24:00 GMT


module ti.sysbios.utils.Load
index URL

The Load module reports execution times and load information for threads in a system

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • CAVEATS
  • XDCscript usage
  • Individual elements
SYS/BIOS manages four distinct levels of execution threads: hardware interrupt service routines, software interrupt routines, tasks, and background idle functions. This module reports execution time and load on a per-task basis, and also provides information globally for hardware interrupt service routines, software interrupt routines and idle functions (in the form of the idle task). It can also report an estimate of the global CPU load, which is computed as the percentage of time in the benchmark window which was NOT spent in the idle loop. More specifically, the load is computed as follows: [ more ... ]
C synopsis target-domain sourced in ti/sysbios/utils/Load.xdc
#include <ti/sysbios/utils/Load.h>
Functions
UInt32 | Load_calculateLoad// Compute total CPU load from a Load_Stat structure(Load_Stat *stat);
UInt32 | Load_getCPULoad// Return an estimate of the global CPU load();
Bool | Load_getGlobalHwiLoad// Return the load and time spent in hwi's(Load_Stat *stat);
Bool | Load_getGlobalSwiLoad// Return the load and time spent in Swi's(Load_Stat *stat);
Bool | Load_getTaskLoad// Return the load and time spent in a specific task(Task_Handle task, Load_Stat *stat);
Void | Load_reset// Reset all internal load counters();
UInt32 | Load_setMinIdle// Set lower bound on idle loop time used to compute CPU load(UInt32 newMinIdleTime);
Void | Load_update// Record thread statistics and reset all counters();
Functions common to all target modules
 | Load_Module_getMask// Returns the diagnostics mask for this module, Load_Module_hasMask// Test whether this module has a diagnostics mask, Load_Module_heap// The heap from which this module allocates memory, Load_Module_id// Get this module's unique id, Load_Module_setMask// Set the diagnostics mask for this module, Load_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*Load_FuncPtr// Callback function type)();
typedef struct | Load_Stat// Load statistics info ...
Constants
extern const Bool | Load_hwiEnabled// Enables Hwi time monitoring;
extern const Log_Event | Load_LS_cpuLoad// This event logs the global CPU load as a percentage;
extern const Log_Event | Load_LS_hwiLoad// This event logs the Hwi load;
extern const Log_Event | Load_LS_swiLoad// This event logs the Swi load;
extern const Log_Event | Load_LS_taskLoad// This event logs Task thread loads;
extern const Load_FuncPtr | Load_postUpdate// User function called after each load update;
extern const Bool | Load_swiEnabled// Enables Swi time monitoring;
extern const Bool | Load_taskEnabled// Enables Task time monitoring;
extern const Bool | Load_updateInIdle// Automatically call update in Idle loop;
extern const UInt | Load_windowInMs// Load averaging period;
DETAILS
SYS/BIOS manages four distinct levels of execution threads: hardware interrupt service routines, software interrupt routines, tasks, and background idle functions. This module reports execution time and load on a per-task basis, and also provides information globally for hardware interrupt service routines, software interrupt routines and idle functions (in the form of the idle task). It can also report an estimate of the global CPU load, which is computed as the percentage of time in the benchmark window which was NOT spent in the idle loop. More specifically, the load is computed as follows:
global CPU load = 100 * (1 - (min. time for a trip around idle loop * # times in idle loop)/(benchmark time window))
Any work done in the idle loop is included in the CPU load - in other words, any time spent in the loop beyond the shortest trip around the idle loop is counted as non-idle time.
Execution time is reported in units of Timestamp counts, and load is reported in percentages.
By default, load data is gathered in all threads. hwiEnabled, swiEnabled and taskEnabled can be used to select which type(s) of threads are monitored. These statistics are automatically recorded to the load module's logger instance. Users can also choose to call getTaskLoad, getGlobalSwiLoad, getGlobalHwiLoad and getCPULoad at any time to obtain the statistics at runtime.
The module relies on update to be called to compute load and execution times from the time when update was last called. This is automatically done for every period specified by windowInMs in an Idle function when updateInIdle is set to true. The time between 2 calls to update is called the benchmark time window.
By passing in a function pointer of type Void(*postUpdate)(Void) through the postUpdate config parameter, one can specify a postUpdate function that is automatically called by update immediately after the statistics have been computed at the end of a benchmark time window. Setting this function allows the user to optionally post-process the thread statistics once and only once per benchmark window.
Advanced users could optionally omit calling update in the idle loop by setting updateInIdle to false. They can then call update somewhere else (e.g. in a periodic higher priority Task) instead to ensure statistics are computed even when the system is never idle.
EXAMPLES
Configuration example: The following statements configure the Load module to obtain output in the CCS output window. This is useful for early development without RTA tools support in SYS/BIOS:
  var System = xdc.useModule('xdc.runtime.System');
  var SysStd = xdc.useModule('xdc.runtime.SysStd');
  System.SupportProxy = SysStd;

  var Load = xdc.useModule('ti.sysbios.utils.Load');
  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  var Diags = xdc.useModule('xdc.runtime.Diags');

  // Turn on statistics log messages for Load module
  Load.common$.diags_USER4 = Diags.ALWAYS_ON;
  // Define a program-wide logger to be the System Logger
  Defaults.common$.logger = LoggerSys.create();
Notes on above example:
  • When using the System Logger, System_printf calls are made to produce the output in the output window. These calls are highly intrusive and are only suited for early development.
  • Also make sure your task stack sizes are large enough when using the System Logger - particularly the idle task stack size since logging is done in the idle task by default.
CAVEATS
  1. For the module to return accurate load values, the update function must be run at least once before the Timestamp count gets to wrap around. This means on a platform with a 32-bit Timestamp frequency that runs at 200 MHz, the function must be called at least once every 21 sec. With faster Timestamp frequencies it would have to be called even more frequently.
  2. If the updateInIdle option is enabled, the module will call update periodically according to windowInMs. The latter must be set to a time interval that is below (2^32) * 1000 / (Timestamp Frequency) milliseconds
  3. If the updateInIdle option is disabled, the user is then responsible for calling update more often than the above time interval.
  4. Load values might not add up to 100%. Because the module minimizes its interrupt latency and avoids locking up the system to compute all thread loads at once, each thread's execution time is evaluated separately over its own time window, which could be slightly different to that of another thread.
  5. When disabling monitoring of a thread type of higher priority, the time spent in that thread type will be counted towards time spent in threads of lower priority. E.g. if hwiEnabled and swiEnabled are both false, then time spent in Hwi's and Swi's will be counted towards the Tasks in which the interrupts happened. Thus, for better accuracy, it is best to leave monitoring on for threads of a higher priority relative to the thread type of interest.
  6. The implementation of getCPULoad() self-calibrates the shortest path through the idle loop. It does this by keeping track of the shortest time between invocations of an idle function automatically inserted by the Load module, and assumes that to be the time it takes for one iteration through the idle loop. Because of this, the CPU load value is only an estimate since the idle loop might occasionally take longer to run (e.g. due to caching effects, stalls). The reported CPU load tends to be slightly higher than reality, especially when the load is low.
  7. If taskEnabled is set to true, task name support will be automatically turned on so that the Load module can print out the task names in its log output.
  8. Currently does not support Timestamp frequencies over 4 GHz.

Calling Context

Function | Hwi | Swi | Task | Main | Startup
getCPULoad | Y | Y | Y | N | N
getGlobalHwiLoad | Y | Y | Y | N | N
getGlobalSwiLoad | Y | Y | Y | N | N
getTaskLoad | Y | Y | Y | N | N
reset | Y* | Y* | Y | Y | N
update | Y* | Y* | Y | N | N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. Load_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. Load_Module_startupDone() returns FALSE).
  • *: Indicates only when taskEnabled is set to false.
typedef Load_FuncPtr
index URL

Callback function type

C synopsis target-domain
typedef Void (*Load_FuncPtr)();
struct Load_Stat
index URL

Load statistics info

C synopsis target-domain
typedef struct Load_Stat {
    UInt32 threadTime;
    UInt32 totalTime;
} Load_Stat;
config Load_LS_cpuLoad // module-wide
index URL

This event logs the global CPU load as a percentage

C synopsis target-domain
extern const Log_Event Load_LS_cpuLoad;
DETAILS
This event is logged whenever the Diags.USER4 level is enabled and the load is measured.
config Load_LS_hwiLoad // module-wide
index URL

This event logs the Hwi load

C synopsis target-domain
extern const Log_Event Load_LS_hwiLoad;
DETAILS
This event is logged whenever the Diags.USER4 level is enabled hwiEnabled is true, and the load is measured.
This event logs the Hwi load, with the form: <load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
config Load_LS_swiLoad // module-wide
index URL

This event logs the Swi load

C synopsis target-domain
extern const Log_Event Load_LS_swiLoad;
DETAILS
This event is logged whenever the Diags.USER4 level is enabled swiEnabled is true, and the load is measured.
This event logs the Swi load, with the form: <load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
config Load_LS_taskLoad // module-wide
index URL

This event logs Task thread loads

C synopsis target-domain
extern const Log_Event Load_LS_taskLoad;
DETAILS
This event is logged whenever the Diags.USER4 level is enabled, taskEnabled is true, and the load is measured.
This event logs Task thread loads, with the form: <Task handle>,<load time>,<measurement time>,<Task function pointer>
Percentage load = <load time> / <measurement time> x 100%
config Load_hwiEnabled // module-wide
index URL

Enables Hwi time monitoring

C synopsis target-domain
extern const Bool Load_hwiEnabled;
DETAILS
When this parameter is set to true, Hwi processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged. This time, together with the total elapsed time, is used to estimate the CPU load due to any Hwi instances run between these updates.
config Load_postUpdate // module-wide
index URL

User function called after each load update

C synopsis target-domain
extern const Load_FuncPtr Load_postUpdate;
DETAILS
If non-NULL, postUpdate is run immediately after each update.
config Load_swiEnabled // module-wide
index URL

Enables Swi time monitoring

C synopsis target-domain
extern const Bool Load_swiEnabled;
DETAILS
When this parameter is set to true, Swi processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged. This time together with the total elapsed time is used to estimate the CPU load due to any Swi instances run between these updates.
config Load_taskEnabled // module-wide
index URL

Enables Task time monitoring

C synopsis target-domain
extern const Bool Load_taskEnabled;
DETAILS
When this parameter is set to true, each Task's processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged for each task. This time together with the total elapsed time is used to estimate the CPU load due to each Task run between these updates.
config Load_updateInIdle // module-wide
index URL

Automatically call update in Idle loop

C synopsis target-domain
extern const Bool Load_updateInIdle;
DETAILS
If this parameter is set to true, an Idle function, which computes and updates the CPU load, is added to the Idle loop.
config Load_windowInMs // module-wide
index URL

Load averaging period

C synopsis target-domain
extern const UInt Load_windowInMs;
DETAILS
When updateInIdle is enabled, this period determines the minimum elapsed time between updates of the load statistics in the idle loop.
Load_calculateLoad() // module-wide
index URL

Compute total CPU load from a Load_Stat structure

C synopsis target-domain
UInt32 Load_calculateLoad(Load_Stat *stat);
DETAILS
This function computes percent load from the values in a Load_Stat structure.
RETURNS
Load value of a Load_Stat structure in %.
Load_getCPULoad() // module-wide
index URL

Return an estimate of the global CPU load

C synopsis target-domain
UInt32 Load_getCPULoad();
RETURNS
CPU load in %
DETAILS
This function returns an estimate of CPU load (% utilization of the CPU), with the idle time determined based on number of trips through the idle loop multiplied by the shortest amount of time through the loop.
This function requires the idle loop to be run during a benchmark time window.
Note: Time spent in kernel while switching to a Hwi/Swi/Task is considered non-idle time.
Load_getGlobalHwiLoad() // module-wide
index URL

Return the load and time spent in hwi's

C synopsis target-domain
Bool Load_getGlobalHwiLoad(Load_Stat *stat);
ARGUMENTS
stat — Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function computes the load and time spent in Hwi's along with the time duration over which the measurement was done. Numbers are reported in Timestamp counts.
Load_getGlobalSwiLoad() // module-wide
index URL

Return the load and time spent in Swi's

C synopsis target-domain
Bool Load_getGlobalSwiLoad(Load_Stat *stat);
ARGUMENTS
stat — Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function returns the load and time spent in Swi's along with the time duration over which the measurement was done. Numbers are reported in Timestamp counts.
Load_getTaskLoad() // module-wide
index URL

Return the load and time spent in a specific task

C synopsis target-domain
Bool Load_getTaskLoad(Task_Handle task, Load_Stat *stat);
ARGUMENTS
task — Handle of the Task which time we are interested in.
stat — Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function returns the load and time spent in a specific task along with the duration over which the measurement was done. Numbers are reported in Timestamp counts.
Task handle must be valid and have been registered with Load.
Load_reset() // module-wide
index URL

Reset all internal load counters

C synopsis target-domain
Void Load_reset();
DETAILS
If taskEnabled is set to true, this function can only be called in task context.
Load_setMinIdle() // module-wide
index URL

Set lower bound on idle loop time used to compute CPU load

C synopsis target-domain
UInt32 Load_setMinIdle(UInt32 newMinIdleTime);
SEE
minIdle
Load_update() // module-wide
index URL

Record thread statistics and reset all counters

C synopsis target-domain
Void Load_update();
DETAILS
If taskEnabled is set to true, this function can only be called in task context.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Load_Module_id();
// Get this module's unique id
Bool Load_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Load_Module_heap();
// The heap from which this module allocates memory
Bool Load_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Load_Module_getMask();
// Returns the diagnostics mask for this module
Void Load_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in ti/sysbios/utils/Load.xdc
var Load = xdc.useModule('ti.sysbios.utils.Load');
module-wide constants & types
    var obj = new Load.Stat// Load statistics info;
        obj.threadTime = UInt32 ...
        obj.totalTime = UInt32 ...
module-wide config parameters
     Load.LS_cpuLoad// This event logs the global CPU load as a percentage = Log.EventDesc {
        mask: Diags.USER4,
        msg: "LS_cpuLoad: %d%%"
    };
     Load.LS_hwiLoad// This event logs the Hwi load = Log.EventDesc {
        mask: Diags.USER4,
        msg: "LS_hwiLoad: %d,%d"
    };
     Load.LS_swiLoad// This event logs the Swi load = Log.EventDesc {
        mask: Diags.USER4,
        msg: "LS_swiLoad: %d,%d"
    };
     Load.LS_taskLoad// This event logs Task thread loads = Log.EventDesc {
        mask: Diags.USER4,
        msg: "LS_taskLoad: 0x%x,%d,%d,0x%x"
    };
     Load.hwiEnabled// Enables Hwi time monitoring = Bool false;
     Load.postUpdate// User function called after each load update = Void(*)() null;
     Load.swiEnabled// Enables Swi time monitoring = Bool false;
     Load.taskEnabled// Enables Task time monitoring = Bool true;
     Load.updateInIdle// Automatically call update in Idle loop = Bool true;
     Load.windowInMs// Load averaging period = UInt 500;
     Load.common$// Common module configuration parameters = Types.Common$ undefined;
     Load.minIdle// Specifies the minimum time used to compute idle time = UInt32 0;
struct Load.Stat
index URL

Load statistics info

XDCscript usage meta-domain
var obj = new Load.Stat;
    obj.threadTime = UInt32 ...
    obj.totalTime = UInt32 ...
C SYNOPSIS
Load_Stat
config Load.LS_cpuLoad // module-wide
index URL

This event logs the global CPU load as a percentage

XDCscript usage meta-domain
Load.LS_cpuLoad = Log.EventDesc {
    mask: Diags.USER4,
    msg: "LS_cpuLoad: %d%%"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled and the load is measured.
C SYNOPSIS
Load_LS_cpuLoad
config Load.LS_hwiLoad // module-wide
index URL

This event logs the Hwi load

XDCscript usage meta-domain
Load.LS_hwiLoad = Log.EventDesc {
    mask: Diags.USER4,
    msg: "LS_hwiLoad: %d,%d"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled hwiEnabled is true, and the load is measured.
This event logs the Hwi load, with the form: <load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
Load_LS_hwiLoad
config Load.LS_swiLoad // module-wide
index URL

This event logs the Swi load

XDCscript usage meta-domain
Load.LS_swiLoad = Log.EventDesc {
    mask: Diags.USER4,
    msg: "LS_swiLoad: %d,%d"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled swiEnabled is true, and the load is measured.
This event logs the Swi load, with the form: <load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
Load_LS_swiLoad
config Load.LS_taskLoad // module-wide
index URL

This event logs Task thread loads

XDCscript usage meta-domain
Load.LS_taskLoad = Log.EventDesc {
    mask: Diags.USER4,
    msg: "LS_taskLoad: 0x%x,%d,%d,0x%x"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled, taskEnabled is true, and the load is measured.
This event logs Task thread loads, with the form: <Task handle>,<load time>,<measurement time>,<Task function pointer>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
Load_LS_taskLoad
config Load.hwiEnabled // module-wide
index URL

Enables Hwi time monitoring

XDCscript usage meta-domain
Load.hwiEnabled = Bool false;
DETAILS
When this parameter is set to true, Hwi processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged. This time, together with the total elapsed time, is used to estimate the CPU load due to any Hwi instances run between these updates.
C SYNOPSIS
Load_hwiEnabled
config Load.postUpdate // module-wide
index URL

User function called after each load update

XDCscript usage meta-domain
Load.postUpdate = Void(*)() null;
DETAILS
If non-NULL, postUpdate is run immediately after each update.
C SYNOPSIS
Load_postUpdate
config Load.swiEnabled // module-wide
index URL

Enables Swi time monitoring

XDCscript usage meta-domain
Load.swiEnabled = Bool false;
DETAILS
When this parameter is set to true, Swi processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged. This time together with the total elapsed time is used to estimate the CPU load due to any Swi instances run between these updates.
C SYNOPSIS
Load_swiEnabled
config Load.taskEnabled // module-wide
index URL

Enables Task time monitoring

XDCscript usage meta-domain
Load.taskEnabled = Bool true;
DETAILS
When this parameter is set to true, each Task's processing time is accumulated between successive calls of update and, as part of Load_update, an event with this cumulative time is logged for each task. This time together with the total elapsed time is used to estimate the CPU load due to each Task run between these updates.
C SYNOPSIS
Load_taskEnabled
config Load.updateInIdle // module-wide
index URL

Automatically call update in Idle loop

XDCscript usage meta-domain
Load.updateInIdle = Bool true;
DETAILS
If this parameter is set to true, an Idle function, which computes and updates the CPU load, is added to the Idle loop.
C SYNOPSIS
Load_updateInIdle
config Load.windowInMs // module-wide
index URL

Load averaging period

XDCscript usage meta-domain
Load.windowInMs = UInt 500;
DETAILS
When updateInIdle is enabled, this period determines the minimum elapsed time between updates of the load statistics in the idle loop.
C SYNOPSIS
Load_windowInMs
metaonly config Load.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Load.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Load.minIdle // module-wide
index URL

Specifies the minimum time used to compute idle time

XDCscript usage meta-domain
Load.minIdle = UInt32 0;
DETAILS
During CPU load measurement, the minimum time observed executing the idle loop together with the count of the number of times the idle loop runs id used to compute the total idle time. However, since the _actual_ time spent in the idle loop will almost always be greater then the observed minimum, the idle time is almost always under estimated.
This configuration parameter can be used to compensate for this underestimate by placing a lower bound on the minimum time used in the CPU measurements. The minimum idle time used to compute CPU load is guarenteed to be greater than or equal to minIdle.
generated on Fri, 17 Jun 2011 00:24:00 GMT


package xdc.runtime
index URL

Basic runtime support for RTSC programs

  • DETAILS
  • DIAGNOSTICS AND LOGS
  • MEMORY MANAGEMENT
  • CONCURRENCY SUPPORT
  • STARTUP AND SHUTDOWN
The modules and interfaces in the xdc.runtime package form the "core" RTSC target runtime support library which provides basic system services required by virtually all applications. [ more ... ]
XDCspec declarations sourced in xdc/runtime/package.xdc
package xdc.runtime [2, 1, 0] {
    interface IFilterLogger;
    // Interface for supporting filtering of Log events by detail level
    interface IGateProvider;
    // Interface implemented by all gate providers
    interface IHeap;
    // Interface to heap functions
    interface IInstance;
    // Common instance params
    interface ILogger;
    // Interface to service Log events
    interface IModule;
    // Base interface for all modules
    interface ISystemSupport;
    // Interface to core system functions
    interface ITimestampClient;
    // Timestamp Client Interface
    interface ITimestampProvider;
    // Timestamp provider interface
    module Assert;
    // Runtime assertion manager
    module Defaults;
    // Default attributes inherited by all target modules
    module Diags;
    // Diagnostics manager
    module Error;
    // Runtime error manager
    module Gate;
    // Critical section support
    module GateNull;
    // Empty implementation of IGateProvider
    module HeapMin;
    // Growth-only based heap implementation
    module HeapStd;
    // Malloc/free based heap implementation
    module Log;
    // Event logging manager
    module LoggerBuf;
    // A logger which stores Log events in a buffer
    module LoggerSys;
    // A logger which routes events to the System_printf function
    module Main;
    // Configuration "stand-in" for application code
    module Memory;
    // Static and run-time memory manager
    module Registry;
    // Register modules that are not statically configured
    module Reset;
    // Startup reset function manager
    module Rta;
    // The Rta module contains target and configuration code for providing RTA support
    module Startup;
    // The xdc.runtime startup bootstrap
    module SysMin;
    // Minimal implementation of ISystemSupport
    module SysStd;
    // Implementation of ISystemSupport using ANSI C Standard Library
    module System;
    // Basic system services
    module Text;
    // Runtime text handling services
    module Timestamp;
    // Timestamp services
    module TimestampNull;
    // Empty implementation of ITimestampProvider
    module TimestampStd;
    // Implementation of ITimestampProvider using ANSI C clock()
    module Types;
    // Basic constants and types
}
DETAILS
The modules and interfaces in the xdc.runtime package form the "core" RTSC target runtime support library which provides basic system services required by virtually all applications.
Since this package's services are intended to be available to any C/C++ client, this package does not contain any pre-compiled libraries. Instead, this package provides complete sources which are built and supplied by a target-specific package named by the rts parameter of the target used to build the client sources. This "indirection" make it possible for new targets to be added by interested parties whithout ever having to update this package.
The functionality provided by this package can be roughly partitioned into four categories:
  1. Diagnostics and Logs
  2. Memory Management
  3. Concurrency Support
  4. Startup and Shutdown
DIAGNOSTICS AND LOGS
This package provides for diagnostics with a set of modules that operate together to configure and implement diagnostics.
The modules can be partitioned into three groups: modules that generate events, a module that allows precise control over when (or if) various events are generated, and modules that manage the output or display of the events.
Assert, Error, and Log provide methods that are added to source code and generate events. The Diags module provides both configuration and runtime methods to selectively enable or disable different types of events on a per module basis. Finally, LoggerBuf and LoggerSys are simple alternative implementations of the ILogger event "handler" interface. You can provide more sophisticated or platform-specific implementations of ILogger without making any changes to code that uses Assert, Log, Error, or Diags.
The diagnostics and logger modules include the following:
  • Assert - Add integrity checks to the code.
  • Diags - Manage a module's diagnostics mask.
  • Error - Raise error events.
  • Log - Generate log events in realtime.
  • LoggerBuf - A logger using a buffer for log events.
  • LoggerSys - A logger using printf for log events.
  • Types - Define diagnostics configuration parameters.
  • Timestamp - Simple timestamp service
MEMORY MANAGEMENT
The memory management modules include the following:
  • Memory - module used by clients to allocate and free memory
  • HeapMin - Deterministic implementation that minimizes code size footprint by not supporting reuse of allocated memory.
  • HeapStd - Implementation that builds atop ANSI C malloc() and free()
CONCURRENCY SUPPORT
The concurency support modules include the following:
  • Gate - module used by clients to serialize access to shared data structures
  • GateNull - "null" implementation for applications that don't need serialization; e.g., single threaded applications
STARTUP AND SHUTDOWN
The system startup and shutdown support modules include:
  • Reset - Manages platform-specific startup initialization before main() is called
  • Startup - Manages "portable" startup initialization before main() is called
  • System - In addition to other basic services (such as printf), this module provides an atexit capability that allows modules to cleanly exit during normal application terminiation.
  • SysMin - Minimal implementation of ISystemSupport, required by the System module, suitable for deeply embedded applications.
  • SysStd - Implementation of ISystemSupport that relies on ANSI C Standard I/O Library functions.
generated on Fri, 17 Jun 2011 00:24:34 GMT


module xdc.runtime.Assert
index URL

Runtime assertion manager

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
The Assert module provides configurable diagnostics to the program. Similar to the standard C assert() macro, Assert methods are interspersed with other code to add diagnostics to a program. Unlike the standard C assert support, the Assert module provides greater flexibility in managing the messages displayed, the message string space overhead, and the runtime handling of failures. In addition, because the Assert methods build atop the Diags module, you can precisely control which asserts remain in the final application, if any. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Assert.xdc
#include <xdc/runtime/Assert.h>
Functions
macro Void | Assert_isTrue// Test an assertion(Bool expr, Assert_Id id);
Functions common to all target modules
 | Assert_Module_getMask// Returns the diagnostics mask for this module, Assert_Module_hasMask// Test whether this module has a diagnostics mask, Assert_Module_heap// The heap from which this module allocates memory, Assert_Module_id// Get this module's unique id, Assert_Module_setMask// Set the diagnostics mask for this module, Assert_Module_startupDone// Test if this module has completed startup
Typedefs
typedef opaque | Assert_Id// Assert identifier;
Constants
extern const Error_Id | Assert_E_assertFailed// The Error.Id raised when an assertion violation is detected;
DETAILS
The Assert module provides configurable diagnostics to the program. Similar to the standard C assert() macro, Assert methods are interspersed with other code to add diagnostics to a program. Unlike the standard C assert support, the Assert module provides greater flexibility in managing the messages displayed, the message string space overhead, and the runtime handling of failures. In addition, because the Assert methods build atop the Diags module, you can precisely control which asserts remain in the final application, if any.
The Assert module works in conjunction with the Diags module. Assert statements are added to the code using the Assert_isTrue() function. Execution of assert statements is controlled by the Diags.ASSERT and Diags.INTERNAL bits in a module's diagnostics mask. By default, all module's Diags_ASSERT bit is enabled and the Diags_INTERNAL bit is disabled. See Types.Common$ for the declaration of the bits in the diagnostics mask and Default.common$ for the default module settings.
Two types of asserts are supported: public asserts and internal asserts.
  • Public asserts have an assert ID and are, by default, controlled by the Diags.ASSERT bit.
  • Internal asserts don't have an assert ID (other than NULL) and are active only when both the Diags.ASSERT and Diags.INTERNAL bits of the module's diagnostics mask are set.
Assert IDs are small integer values that index into a table of assertion descriptors. These descriptors hold an error message and a diagnostics mask that is used to enable and disable the assertion at runtime.
You can remap individual public asserts to different bits in the diagnostics mask, or can disable the assert altogether. This is done by setting the mask property of the assert ID. Setting the mask to 0 disables the assert. In all other cases, the Diags.ASSERT bit is OR'd together with the mask to define the controlling bits. For example, the module's diagnostics mask must have the Diags.ASSERT bit set and any other bit specified in the mask property of the assert ID in order to activate the assert.
EXAMPLES
Example 1: The following C code adds an assert to application code which is not in a module. This assert does not have an assert identifier (the second argument is NULL); this makes it an internal assert.
  // file.c
  #include <xdc/runtime/Assert.h>

  Assert_isTrue(count > 0, NULL);
The following XDC configuration statements set both the ASSERT and INTERNAL bits in the diagnostics mask to enable the internal assert created in the previous C code. Since the C code is not in a module, you must set the bits in the diagnostics mask of the xdc.runtime.Main module. The Main module is used to control all Log and Assert statements that are not part of the implementation of a module; for example, top-level application code or any existing sources that simply call the Log or Assert methods.
  // program.cfg
  var Assert = xdc.useModule('xdc.runtime.Assert');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Main = xdc.useModule('xdc.runtime.Main');

  Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
  Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;
Example 2: The following example shows how to use and configure an assert ID that is declared by a module. It adds that assert to the application's C source code, and configures the application to execute the assert.
This is part of the XDC file for the module that declares an Assert Id:
  // Mod.xdc
  import xdc.runtime.Assert;
  import xdc.runtime.Diags;

  config Assert.Id A_nonZero = {
      msg: "A_nonZero: value must be non-zero"
  };
This is part of the C code for the application:
  // Mod.c
  #include <xdc/runtime/Assert.h>

  Assert_isTrue(x != 0, Mod_A_nonZero);
This is part of the XDC configuration file for the application:
  // program.cfg
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');
  Mod.common$.diags_ASSERT = Diags.ALWAYS_ON;
typedef Assert_Id
index URL

Assert identifier

C synopsis target-domain
typedef opaque Assert_Id;
DETAILS
Each metaonly assert descriptor is encoded into a target accessable assert Id type which can be passed to the isTrue function.
config Assert_E_assertFailed // module-wide
index URL

The Error.Id raised when an assertion violation is detected

C synopsis target-domain
extern const Error_Id Assert_E_assertFailed;
DETAILS
When an assertion violation is triggered, an error is raised via Error_raise(). E_assert_Failed is the Error.Id passed to Error_raise().
The first string argument (%s) will be either "", if the assertion Id is NULL (for internal asserts), or ": " (for public asserts). The second string argument (%s) is the Assert.Desc.msg string associated with the assertion Id; if the Id is NULL (an internal assert) or if text is not loaded (!Text.isLoaded()), this string is "".
SEE
isTrue, Error.Id
Assert_isTrue() // module-wide
index URL

Test an assertion

C synopsis target-domain
macro Void Assert_isTrue(Bool expr, Assert_Id id);
ARGUMENTS
expr — the expression which should evaluate to true
id — identifies the assert being raised
DETAILS
Assert_isTrue() statements may be conditionally enabled (disabled) on a per module basis by setting the calling module's $common.diags_ASSERT configuration parameter. If the Assert_isTrue() statement is not in a module, the calling module is the Main module. You must enable the Diags.ASSERT bit in the module's diagnostics mask for this call to be enabled. If a NULL assert id is specified, then you must enable the Diags.INTERNAL in addition to the ASSERT bit.
If the Assert_isTrue() statement is enabled and expr evaluates to false, the assert specified by id is raised; i.e., the E_assertFailed error is raised with a NULL error block. In other words, the standard Error.raise handling hooks will be run, System.abort() will be called, and control does not return to the caller. The id may be null, in which case you will get a generic assert message.
EXAMPLES
C Code
  #include <xdc/runtime/Assert.h>

  Assert_isTrue(count > 0, NULL);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Assert_Module_id();
// Get this module's unique id
Bool Assert_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Assert_Module_heap();
// The heap from which this module allocates memory
Bool Assert_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Assert_Module_getMask();
// Returns the diagnostics mask for this module
Void Assert_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Assert.xdc
var Assert = xdc.useModule('xdc.runtime.Assert');
module-wide constants & types
    var obj = new Assert.Desc// Assert descriptor;
        obj.mask = Bits16 ...
        obj.msg = String ...
module-wide config parameters
    const Assert.E_assertFailed// The Error.Id raised when an assertion violation is detected = Error.Desc {
        msg: "assertion failure%s%s"
    };
     Assert.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly struct Assert.Desc
index URL

Assert descriptor

XDCscript usage meta-domain
var obj = new Assert.Desc;
    obj.mask = Bits16 ...
    obj.msg = String ...
FIELDS
mask — Specifies which bits enable the assert.
msg — The message printed when the assert fails.
DETAILS
Each public assert is defined with an assert descriptor. This structure defines which bits in the module's diagnostics mask control this assert, and the message raised when the assert fails. The mask property is optional, it defaults to the Diags.ASSERT bit.
config Assert.E_assertFailed // module-wide
index URL

The Error.Id raised when an assertion violation is detected

XDCscript usage meta-domain
const Assert.E_assertFailed = Error.Desc {
    msg: "assertion failure%s%s"
};
DETAILS
When an assertion violation is triggered, an error is raised via Error_raise(). E_assert_Failed is the Error.Id passed to Error_raise().
The first string argument (%s) will be either "", if the assertion Id is NULL (for internal asserts), or ": " (for public asserts). The second string argument (%s) is the Assert.Desc.msg string associated with the assertion Id; if the Id is NULL (an internal assert) or if text is not loaded (!Text.isLoaded()), this string is "".
SEE
isTrue, Error.Id
C SYNOPSIS
Assert_E_assertFailed
metaonly config Assert.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Assert.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:31 GMT


module xdc.runtime.Defaults
index URL

Default attributes inherited by all target modules

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module defines default values for common$ structure. If other modules do not set common$ properties explicitly, these values will be used.
C synopsis target-domain sourced in xdc/runtime/Defaults.xdc
#include <xdc/runtime/Defaults.h>
Functions common to all target modules
Defaults_Module_getMask// Returns the diagnostics mask for this module, Defaults_Module_hasMask// Test whether this module has a diagnostics mask, Defaults_Module_heap// The heap from which this module allocates memory, Defaults_Module_id// Get this module's unique id, Defaults_Module_setMask// Set the diagnostics mask for this module, Defaults_Module_startupDone// Test if this module has completed startup
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Defaults_Module_id();
// Get this module's unique id
Bool Defaults_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Defaults_Module_heap();
// The heap from which this module allocates memory
Bool Defaults_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Defaults_Module_getMask();
// Returns the diagnostics mask for this module
Void Defaults_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Defaults.xdc
var Defaults = xdc.useModule('xdc.runtime.Defaults');
module-wide config parameters
    const Defaults.noRuntimeCommon$// Defaults inherited by the target modules that do not need the runtime support = Types.Common$ {
        diags_ASSERT: Diags.ALWAYS_OFF,
        diags_ENTRY: Diags.ALWAYS_OFF,
        diags_EXIT: Diags.ALWAYS_OFF,
        diags_INTERNAL: Diags.ALWAYS_OFF,
        diags_LIFECYCLE: Diags.ALWAYS_OFF,
        diags_STATUS: Diags.ALWAYS_OFF,
        diags_USER1: Diags.ALWAYS_OFF,
        diags_USER2: Diags.ALWAYS_OFF,
        diags_USER3: Diags.ALWAYS_OFF,
        diags_USER4: Diags.ALWAYS_OFF,
        diags_USER5: Diags.ALWAYS_OFF,
        diags_USER6: Diags.ALWAYS_OFF,
        diags_USER7: Diags.ALWAYS_OFF,
        diags_INFO: Diags.ALWAYS_OFF,
        diags_USER8: Diags.ALWAYS_OFF,
        diags_ANALYSIS: Diags.ALWAYS_OFF,
        fxntab: false,
        gate: null,
        gateParams: null,
        instanceHeap: null,
        instanceSection: null,
        logger: null,
        memoryPolicy: Types.STATIC_POLICY,
        namedInstance: false,
        namedModule: false,
        romPatchTable: false
    };
     Defaults.common$// Defaults inherited by all target modules = Types.Common$ {
        diags_ASSERT: Diags.ALWAYS_ON,
        diags_ENTRY: Diags.ALWAYS_OFF,
        diags_EXIT: Diags.ALWAYS_OFF,
        diags_INTERNAL: Diags.ALWAYS_OFF,
        diags_LIFECYCLE: Diags.ALWAYS_OFF,
        diags_STATUS: Diags.ALWAYS_ON,
        diags_USER1: Diags.ALWAYS_OFF,
        diags_USER2: Diags.ALWAYS_OFF,
        diags_USER3: Diags.ALWAYS_OFF,
        diags_USER4: Diags.ALWAYS_OFF,
        diags_USER5: Diags.ALWAYS_OFF,
        diags_USER6: Diags.ALWAYS_OFF,
        diags_USER7: Diags.ALWAYS_OFF,
        diags_INFO: Diags.ALWAYS_OFF,
        diags_USER8: Diags.ALWAYS_OFF,
        diags_ANALYSIS: Diags.ALWAYS_OFF,
        fxntab: true,
        gate: null,
        gateParams: null,
        instanceHeap: null,
        instanceSection: null,
        logger: null,
        memoryPolicy: Types.DELETE_POLICY,
        namedInstance: false,
        namedModule: true,
        romPatchTable: false
    };
module-wide functions
     Defaults.getCommon// Get a specified common parameter from a module(IModule.Module mod, String param) returns Any
metaonly config Defaults.noRuntimeCommon$ // module-wide
index URL

Defaults inherited by the target modules that do not need the runtime support

XDCscript usage meta-domain
const Defaults.noRuntimeCommon$ = Types.Common$ {
    diags_ASSERT: Diags.ALWAYS_OFF,
    diags_ENTRY: Diags.ALWAYS_OFF,
    diags_EXIT: Diags.ALWAYS_OFF,
    diags_INTERNAL: Diags.ALWAYS_OFF,
    diags_LIFECYCLE: Diags.ALWAYS_OFF,
    diags_STATUS: Diags.ALWAYS_OFF,
    diags_USER1: Diags.ALWAYS_OFF,
    diags_USER2: Diags.ALWAYS_OFF,
    diags_USER3: Diags.ALWAYS_OFF,
    diags_USER4: Diags.ALWAYS_OFF,
    diags_USER5: Diags.ALWAYS_OFF,
    diags_USER6: Diags.ALWAYS_OFF,
    diags_USER7: Diags.ALWAYS_OFF,
    diags_INFO: Diags.ALWAYS_OFF,
    diags_USER8: Diags.ALWAYS_OFF,
    diags_ANALYSIS: Diags.ALWAYS_OFF,
    fxntab: false,
    gate: null,
    gateParams: null,
    instanceHeap: null,
    instanceSection: null,
    logger: null,
    memoryPolicy: Types.STATIC_POLICY,
    namedInstance: false,
    namedModule: false,
    romPatchTable: false
};
DETAILS
Modules for which the attribute NoRuntime is set do not use any functionality controlled by the parameters in their common$ structures. For such modules, these parameters are set to the following values, and cannot be changed, to guarantee that NoRuntime modules do not accidentally request functionality they don not use.
metaonly config Defaults.common$ // module-wide
index URL

Defaults inherited by all target modules

XDCscript usage meta-domain
Defaults.common$ = Types.Common$ {
    diags_ASSERT: Diags.ALWAYS_ON,
    diags_ENTRY: Diags.ALWAYS_OFF,
    diags_EXIT: Diags.ALWAYS_OFF,
    diags_INTERNAL: Diags.ALWAYS_OFF,
    diags_LIFECYCLE: Diags.ALWAYS_OFF,
    diags_STATUS: Diags.ALWAYS_ON,
    diags_USER1: Diags.ALWAYS_OFF,
    diags_USER2: Diags.ALWAYS_OFF,
    diags_USER3: Diags.ALWAYS_OFF,
    diags_USER4: Diags.ALWAYS_OFF,
    diags_USER5: Diags.ALWAYS_OFF,
    diags_USER6: Diags.ALWAYS_OFF,
    diags_USER7: Diags.ALWAYS_OFF,
    diags_INFO: Diags.ALWAYS_OFF,
    diags_USER8: Diags.ALWAYS_OFF,
    diags_ANALYSIS: Diags.ALWAYS_OFF,
    fxntab: true,
    gate: null,
    gateParams: null,
    instanceHeap: null,
    instanceSection: null,
    logger: null,
    memoryPolicy: Types.DELETE_POLICY,
    namedInstance: false,
    namedModule: true,
    romPatchTable: false
};
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
This structure defines the default values for the configuration parameters shared by all modules in a system. Unless otherwise noted, setting one of the fields defined below will set the corresponding value for all modules in the system which have not been explicitly set; i.e., it will establish a default value for the parameter.
However, the modules from this package (xdc.runtime) are an exception. The values from Default.common$ are not copied to logger and diags_ properties of common$ in xdc.runtime modules. The property diags_ASSERT is an exception to that exception. Its value from 'Default.common$ is copied to all modules for which diags_ASSERT` has not been explicitly set.
DIAGS_ASSERT
Enables asserts at runtime. Default is ALWAYS_ON
DIAGS_ENTRY
Enables entry trace for all functions. Default is ALWAYS_OFF
DIAGS_EXIT
Enables exit trace for all functions. Default is ALWAYS_OFF
DIAGS_INTERNAL
Enables internal asserts. Default is ALWAYS_OFF. When set to ALWAYS_ON, requires diags_ASSERT to be ALWAYS_ON.
DIAGS_LIFECYCLE
Enables logging of lifecycle events. These events are logged during creates and deletes. Default is ALWAYS_OFF.
DIAGS_STATUS
Enables logging of status events, such as error and warning events. Default is ALWAYS_ON. Note that this does not mean that logging will occur by default--a logger instance must also be configured for the module in order for events to be logged.
DIAGS_INFO
Enables logging of generic informational events. Default is ALWAYS_OFF.
DIAGS_ANALYSIS
Enables logging of analysis events, such as benchmarking events. Default is ALWAYS_OFF.
DIAGS_USER
Each diags_USER field controls a separate user-defined logging level. Default is ALWAYS_OFF for all diags_USER fileds.
GATE
Default gate used by all modules which are declared as being @Gated. By default, this parameter points to an instance of GateNull, which means there is no protection.
GATEPARAMS
The default parameters used to create gates at runtime. See Types.Common$.gateParams. Default is null.
INSTANCEHEAP
Specify heap to be used for module instances. Default is null. If instanceHeap is null, instances will be allocated from the heap specified by Memory.defaultHeapInstance.
INSTANCESECTION
Specify section to be used to place module instances. Default is null.
LOGGER
Default logger used by modules to write logs. By default there is no logger.
MEMORYPOLICY
Used to specify type of application. Types.STATIC_POLICY is used when all objects are created statically. Types.CREATE_POLICY is used when the application creates objects at runtime. Types.DELETE_POLICY is used when the application creates and deletes objects at runtime. This helps eliminate unwanted create and delete code.
NAMEDINSTANCE
This parameter should be set to true if space needs to be allocated in instance objects for instance names. Allocating space for a name allows object view tools to display the names. The runtime functions Mod_Handle_name() and Mod_Handle_label() defined for each module Mod can be used to retrieve the name at runtime.
NAMEDMODULE
This field allows the name of the module to be retained on the target. Setting this to false will save space but will also prevent the target from being able to display the module names appearing in Log events and Errors.
Setting namedModule to false causes all modules, except for Memory and Main to be unnamed by default. To eliminate the string names for these modules you must explicitly set their common$.namedModule parameters to false; without these two names, target-side display of error messages is somewhat cryptic.
ROMPATCHTABLE
Specify whether modules that are allocated to ROM are patchable.
metaonly Defaults.getCommon() // module-wide
index URL

Get a specified common parameter from a module

XDCscript usage meta-domain
Defaults.getCommon(IModule.Module mod, String param) returns Any
ARGUMENTS
eb — module whose parameter is queried
param — string naming the queried parameter
DETAILS
Get the value of a member of the structure common$ based on defaults and the current value of the parameter. If the current value of param is undefined, the function returns the default value for that parameter from Default.common$.
RETURNS
Returns the value of the parameter named param from the module mod.
generated on Fri, 17 Jun 2011 00:24:31 GMT


module xdc.runtime.Diags
index URL

Diagnostics manager

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
Every XDC module has a "diagnostics mask" that allows clients to enable or disable diagnostics on a per module basis both at configuration time and at runtime. The Diags module manages a module's diagnostics mask. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Diags.xdc
#include <xdc/runtime/Diags.h>
Functions
macro Bool | Diags_compareLevels// Returns false if levelA is lower than levelB(Diags_EventLevel levelA, Diags_EventLevel levelB);
macro Diags_EventLevel | Diags_getLevel// Get the event level set in the given mask(Diags_Mask mask);
macro Bool | Diags_query// Query the module's diagnostics mask against the given mask(Diags_Mask mask);
Void | Diags_setMask// Set a module's diagnostics mask at runtime(String control);
Functions common to all target modules
 | Diags_Module_getMask// Returns the diagnostics mask for this module, Diags_Module_hasMask// Test whether this module has a diagnostics mask, Diags_Module_heap// The heap from which this module allocates memory, Diags_Module_id// Get this module's unique id, Diags_Module_setMask// Set the diagnostics mask for this module, Diags_Module_startupDone// Test if this module has completed startup
Defines
#define | Diags_ALL// Mask of all diagnostics categories, including both logging and asserts (Diags_Mask)0xFF9F
#define | Diags_ALL_LOGGING// Mask of all logging diagnostic categories (does not include asserts) (Diags_Mask)Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL)
#define | Diags_ANALYSIS// Analysis (e.g., benchmark) event (Diags_Mask)Diags.USER8
#define | Diags_ASSERT// Assert checking (Diags_Mask)0x0010
#define | Diags_CRITICAL// A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL' (Diags_EventLevel)Diags.LEVEL2
#define | Diags_EMERGENCY// A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY' (Diags_EventLevel)Diags.LEVEL1
#define | Diags_ENTRY// Function entry (Diags_Mask)0x0001
#define | Diags_ERROR// A 'LEVEL3' 'STATUS' event is defined as 'ERROR' (Diags_EventLevel)Diags.LEVEL3
#define | Diags_EXIT// Function exit (Diags_Mask)0x0002
#define | Diags_INFO// Informational event (Diags_Mask)Diags.USER7
#define | Diags_INTERNAL// Internal diagnostics (Diags_Mask)0x0008
#define | Diags_LIFECYCLE// Object life-cycle (Diags_Mask)0x0004
#define | Diags_STATUS// Warning or error event (Diags_Mask)0x0080
#define | Diags_USER1// User defined diagnostics (Diags_Mask)0x0100
#define | Diags_USER2// User defined diagnostics (Diags_Mask)0x0200
#define | Diags_USER3// User defined diagnostics (Diags_Mask)0x0400
#define | Diags_USER4// User defined diagnostics (Diags_Mask)0x0800
#define | Diags_USER5// User defined diagnostics (Diags_Mask)0x1000
#define | Diags_USER6// User defined diagnostics (Diags_Mask)0x2000
#define | Diags_USER7// Alias for informational event (Diags_Mask)0x4000
#define | Diags_USER8// Alias for analysis event (Diags_Mask)0x8000
#define | Diags_WARNING// A 'LEVEL4' 'STATUS' event is defined as 'WARNING' (Diags_EventLevel)Diags.LEVEL4
Typedefs
typedef enum | Diags_EventLevel// The level of an event ...
typedef Types_DiagsMask | Diags_Mask// Type used to specify bits in the diags mask;
DETAILS
Every XDC module has a "diagnostics mask" that allows clients to enable or disable diagnostics on a per module basis both at configuration time and at runtime. The Diags module manages a module's diagnostics mask.
You use the Diags module to set and clear bits in a module's diagnostics mask for the purpose of controlling diagnostics within that module. Each bit corresponds to a "category" of diagnostic that can be individually enabled or disabled.
A module's diagnostics mask controls both Assert and Log statements within that module. A module's diagnostics mask may also be used to conditionally execute blocks of code using the Diags_query() runtime function.
A module's diagnostics mask can be set at configuration time and at runtime. The implementation of diagnostics is such that when they are permanently turned off at configuration time (Mode.ALWAYS_OFF), an optimizer can completely eliminate the diagnostics code from the program. Similarly, if diagnostics are permanently turned on at configuration time (Mode.ALWAYS_ON), the optimizer can eliminate all runtime conditional checking and simply invoke the diagnostics code directly. Runtime checking of the diagnostics mask is performed only when the diagnostics are configured to be runtime modifiable (Mode.RUNTIME_OFF or Mode.RUNTIME_ON).
Each bit of the diagnostics mask is controlled by one of the following constants.
  Constant    Meaning
  --------------------------
  ENTRY       Function entry
  EXIT        Function exit
  LIFECYCLE   Object life-cycle
  INTERNAL    Internal diagnostics
  ASSERT      Assert checking
  STATUS      Warning or Error events
  USER1       User defined diagnostics
  USER2       User defined diagnostics
  USER3       User defined diagnostics
  USER4       User defined diagnostics
  USER5       User defined diagnostics
  USER6       User defined diagnostics
  USER7       User defined diagnostics
  INFO        Informational event
  USER8       User defined diagnostics
  ANALYSIS    Analysis event
These constants can be used from either JavaScript configuration scripts or C code and, therefore, have two "names". For example, to reference the ENTRY constant from JavaScript you must use Diags.ENTRY whereas from C you would use Diags_ENTRY.
The ENTRY and EXIT categories are for log statements at the entry and exit points, respectively, to each function within a module. This is useful for tracking the execution flow of your program.
The LIFECYCLE category is for log events at the create/construct and delete/destruct points of each instance object for the module. This is useful for tracking the life-cycle of a module instance object.
ASSERT and INTERNAL are unique in that they are not related to logging, but instead control the Assert statements in a module. These categories control the two classes of asserts:
  • Public asserts, which have an Assert_Id and are documented in the module's reference pages. These asserts are on by default and are meant to help developers validate code that invokes a module's functions.
  • Internal asserts, which have no Assert_Id. These asserts are off by default and are typically used only when developing code. That is, like the standard C assert() mechanism, these asserts are not part of a deployed application.
When a module has enabled the ASSERT category (which is enabled by default) in its diagnostics mask, the module executes all of its public assert statements. To enable internal asserts, you must enable both the ASSERT and INTERNAL categories.
The ASSERT and INTERNAL categories are not intended for use as log event categories. If an event is defined with either of these categories, you will receive a validation error during configuration.
The STATUS category is used for error and warning type events. The four event levels within the STATUS category have defined meanings, see EMERGENCY
The INFO category is used for generic informational events. Any event which does not belong to a more specific category of events may simply be an INFO event.
The ANALYSIS category is used for events related to benchmarks and performance analysis.
The USER1-6 categories are available to each module writer to use as he or she wishes.
The USER7 and USER8 categories are still defined, but their bits have been repurposed for the INFO and ANALYSIS categories, respectively, so the use of USER7 and USER8 has been deprecated.
EXAMPLES
Configuration example: The following XDC configuration statements set a module's diagnostics mask in a configuration script. (In this case, the Task module of the ti.sysbios.knl package is used.) In this example, the ENTRY bit is turned on and the EXIT bit is turned off. Both bits are configured to be runtime modifiable.
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Task = xdc.useModule('ti.sysbios.knl.Task');

  Task.common$.diags_ENTRY = Diags.RUNTIME_ON;
  Task.common$.diags_EXIT = Diags.RUNTIME_OFF;
Runtime example: The following C code shows how to disable and reenable ENTER diagnostics at runtime for the ti.sysbios.knl.Task module configured in the previous example. The first call to Diag_setMask() enables entry diagnostics ("+E") for just the ti.sysbios.knl.Task module; any call to any Task method in the application causes an "entry" Log event to be generated. The second call disables ("-E") the generation of these events. See Diags_setMask() for a complete description of the strings accepted by this function.
  #include <xdc/runtime/Diags.h>
  :
  Diags_setMask("ti.sysbios.knl.Task+E");
  :
  Diags_setMask("ti.sysbios.knl.Task-E");
Configuration example: The following XDC configuration statements turn on asserts in the entire program.
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Defaults = xdc.useModule('xdc.runtime.Defaults');

  Defaults.diags_ASSERT = Diags.ALWAYS_ON;
Configuration example: Using the Diags.setMaskMeta() function, the following XDC configuration statements turn on asserts in all of the modules whose name begins with "ti.sysbios." In this case, no change to the application code is necessary to enable these events. It is important to note that, while the configuration step must be re-run and the application must be re-linked, no application sources need to be recompiled.
  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.%", Diags.ASSERT, Diags.ALWAYS_ON);
const Diags_ALL
index URL

Mask of all diagnostics categories, including both logging and asserts

C synopsis target-domain
#define Diags_ALL (Diags_Mask)0xFF9F
const Diags_ALL_LOGGING
index URL

Mask of all logging diagnostic categories (does not include asserts)

C synopsis target-domain
#define Diags_ALL_LOGGING (Diags_Mask)Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL)
const Diags_ANALYSIS
index URL

Analysis (e.g., benchmark) event

C synopsis target-domain
#define Diags_ANALYSIS (Diags_Mask)Diags.USER8
const Diags_ASSERT
index URL

Assert checking

C synopsis target-domain
#define Diags_ASSERT (Diags_Mask)0x0010
const Diags_CRITICAL
index URL

A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'

C synopsis target-domain
#define Diags_CRITICAL (Diags_EventLevel)Diags.LEVEL2
DETAILS
See 'EMERGENCY' for details.
const Diags_EMERGENCY
index URL

A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'

C synopsis target-domain
#define Diags_EMERGENCY (Diags_EventLevel)Diags.LEVEL1
DETAILS
For STATUS events only, the meaning of the four EventLevels has been defined. These constants are simply aliases for the four event levels.
The highest three levels are different severities of an error event. For example, an EMERGENCY event may represent an unrecoverable system failure, a CRITICAL event may require notification of an operator, and an ERROR may be a recoverable error.
The lowest level is reserved for warnings, such as when a resource becomes dangerously low.
const Diags_ENTRY
index URL

Function entry

C synopsis target-domain
#define Diags_ENTRY (Diags_Mask)0x0001
const Diags_ERROR
index URL

A 'LEVEL3' 'STATUS' event is defined as 'ERROR'

C synopsis target-domain
#define Diags_ERROR (Diags_EventLevel)Diags.LEVEL3
DETAILS
See 'EMERGENCY' for details.
const Diags_EXIT
index URL

Function exit

C synopsis target-domain
#define Diags_EXIT (Diags_Mask)0x0002
const Diags_INFO
index URL

Informational event

C synopsis target-domain
#define Diags_INFO (Diags_Mask)Diags.USER7
const Diags_INTERNAL
index URL

Internal diagnostics

C synopsis target-domain
#define Diags_INTERNAL (Diags_Mask)0x0008
const Diags_LIFECYCLE
index URL

Object life-cycle

C synopsis target-domain
#define Diags_LIFECYCLE (Diags_Mask)0x0004
const Diags_STATUS
index URL

Warning or error event

C synopsis target-domain
#define Diags_STATUS (Diags_Mask)0x0080
const Diags_USER1
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER1 (Diags_Mask)0x0100
const Diags_USER2
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER2 (Diags_Mask)0x0200
const Diags_USER3
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER3 (Diags_Mask)0x0400
const Diags_USER4
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER4 (Diags_Mask)0x0800
const Diags_USER5
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER5 (Diags_Mask)0x1000
const Diags_USER6
index URL

User defined diagnostics

C synopsis target-domain
#define Diags_USER6 (Diags_Mask)0x2000
const Diags_USER7
index URL

Alias for informational event

C synopsis target-domain
#define Diags_USER7 (Diags_Mask)0x4000
const Diags_USER8
index URL

Alias for analysis event

C synopsis target-domain
#define Diags_USER8 (Diags_Mask)0x8000
const Diags_WARNING
index URL

A 'LEVEL4' 'STATUS' event is defined as 'WARNING'

C synopsis target-domain
#define Diags_WARNING (Diags_EventLevel)Diags.LEVEL4
DETAILS
See 'EMERGENCY' for details.
enum Diags_EventLevel
index URL

The level of an event

C synopsis target-domain
typedef enum Diags_EventLevel {
    Diags_LEVEL1,
    Diags_LEVEL2,
    Diags_LEVEL3,
    Diags_LEVEL4
} Diags_EventLevel;
DETAILS
The diagnostics bits each represent a different category of event, for example: an analysis event, a lifecycle event, or an informational event. Within each of these categories, events may have one of four levels to enable filtering based on the level of information desired.
The meaning of these levels and the distinction between them is left open to the user. Depending on the meaning given, different terminology may be used to describe them--they may be levels of detail, priority, severity, etc. The heirarchy of the events is set such that LEVEL1 is the highest priority and LEVEL4 is the lowest. That is, enabling LEVEL4 events implies that events of all four levels will be logged.
LEVEL1
Least detail, highest priority, most severe, etc.
LEVEL2
LEVEL3
LEVEL4
Most detail, lowest priority, least severe, etc.
The STATUS bit is the only category where the levels are given explicit meaning to ensure consistency. Within the STATUS category, the meaning of the levels is defined by the constants EMERGENCY, CRITICAL, ERROR, and WARNING.
Events which don't define a level will receive LEVEL1 by default.
typedef Diags_Mask
index URL

Type used to specify bits in the diags mask

C synopsis target-domain
typedef Types_DiagsMask Diags_Mask;
Diags_compareLevels() // module-wide
index URL

Returns false if levelA is lower than levelB

C synopsis target-domain
macro Bool Diags_compareLevels(Diags_EventLevel levelA, Diags_EventLevel levelB);
DETAILS
This API is intended to be used to determine if a given event passes a filtering threshold and should be logged. Conceptually (though not necessarily in implementation), this API is equivalent to the expression (levelA < levelB). The values of the EventLevels have internal meaning, so a direct comparison of two levels should not done; this API must be used to correctly compare them.
LEVEL1 is the highest level and LEVEL4 is the lowest. So LEVEL4 is less than LEVEL3, which is less than LEVEL2, which is less than LEVEL1.
Diags_getLevel() // module-wide
index URL

Get the event level set in the given mask

C synopsis target-domain
macro Diags_EventLevel Diags_getLevel(Diags_Mask mask);
ARGUMENTS
mask — mask of diagnostics bits to read filter level from.
DETAILS
See 'EventLevel' for a description of event levels.
Diags_query() // module-wide
index URL

Query the module's diagnostics mask against the given mask

C synopsis target-domain
macro Bool Diags_query(Diags_Mask mask);
ARGUMENTS
mask — mask of diagnostics bits to test
This given mask is constructed by OR'ing together the desired bits of the diagnostics mask using the constants listed in the Mask Summary above. The module's diagnostics mask will be logically AND'ed with the given mask, and return true if the result is non-zero and false otherwise.
      if (Diags_query(Diags_USER1 | Diags_USER4)) {
          :
      }
DETAILS
Use this query function to test the state of a module's diagnostics mask at runtime. This function will perform a logical AND operation on the module's diagnostics mask and the given mask. If any bits survive the operation, the function returns true.
  result = moduleMask & givenMask ? true : false;
This query function has a compile-time binding to the module's diagnostics mask. If the query function is part of the C code implementation of a module, then it will use that module's diagnostics mask. Otherwise, it will use the diagnostics mask of the xdc.runtime.Main module.
The implementation of the diagnostics mask and the query function is such that an optimizer can take advantage of dead code elimination and/or constant folding to eliminate or reduce code size. For example, if the query function is used in a conditional test, and the given mask contains only bits which have been configured to be permanently off, then the code for the entire conditional statement can be removed at link time. If the bits in the given mask have been configured to be permanently on, then the conditional code can be removed leaving the body of the conditional as direct in-line code.
EXAMPLES
In the following example, the USER1 bit of the module's diagnostics mask has been configured to be permanently off, thus the entire conditional code block can be removed at link time. Note, the C code below is part of the module itself.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var ModA = xdc.useModule('my.package.ModuleA');
  ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
C Code, ModA.c
  if (Diags_query(Diags_USER1)) {         // this code removed
      ...additional code here...          // this code removed
  }                                       // this code removed
In the following example, the USER1 bit of the module's diagnostics mask has been configured to be permanently on, thus the conditional code can be removed leaving the code contained within the conditional statement. Note, the C code below is part of the module itself.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var ModA = xdc.useModule('my.package.ModuleA');
  ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
C Code, ModA.c
  if (Diags_query(Diags_USER1) {          // this code removed
      ...additional code here...          // this code remains
  }                                       // this code removed
Diags_setMask() // module-wide
index URL

Set a module's diagnostics mask at runtime

C synopsis target-domain
Void Diags_setMask(String control);
ARGUMENTS
control — diagnostic mask control string
This control string defines one or more actions where each action consists of a module name, an operator character, and a list of bit specifiers. Use the % character as a wildcard to turn the module name into a prefix matching pattern for a set of modules. Multiple actions are separated with the ; character.
The control string has the following format:
  <module[%]><op><bits>[;<module[%]><op><bits>]
Specify individual module names explicitly (e.g. ti.sysbios.knl.Task), or match multiple modules using a prefix matching pattern specified with the % character (e.g. ti.sysbios.knl.%).
The operator is specified with a single character from the following table.
  Operator    Description
  --------------------------------------------------
  +           Set only the specified bits (other bits preserved)
  -           Clear only the specified bits (other bits preserved)
  =           Assign the entire mask to the given value where the
              specified bits are set and all other bits are cleared
The bits are specified with a list of characters from the following table. Refer to the Mask Summary for a list of each bit of the diagnostics mask.
  Control     Diagnostics
  Character   Constant        Description
  --------------------------------------------------
  E           ENTRY           Function entry
  X           EXIT            Function exit
  L           LIFECYCLE       Object life-cycle
  I           INTERNAL        Internal diagnostics
  A           ASSERT          Assert checking
  Z           ANALYSIS        Analysis event
  F           INFO            Informational event
  S           STATUS          Status (error, warning) event
  1           USER1           User defined diagnostics
  2           USER2           User defined diagnostics
  3           USER3           User defined diagnostics
  4           USER4           User defined diagnostics
  5           USER5           User defined diagnostics
  6           USER6           User defined diagnostics
  7           USER7           User defined diagnostics
  8           USER8           User defined diagnostics
DETAILS
Use the given control string to set or clear bits in a module's diagnostics mask. The control string defines one or more actions where each action modifies the diagnostics mask in one or more modules. Each action can either set, clear, or assign a module's diagnostics mask. To both set and clear bits in the same diagnostics mask requires two actions, or you can assign the entire mask explicitly in one action. Each action can specify a given module or a set of modules using name prefix matching.
WARNING
Each bit of a module's diagnostics mask that is to be modified at runtime, must be configured to be runtime modifiable in the program's configuration script. Use either RUNTIME_OFF or RUNTIME_ON as the configuration value for the desired bit in the diagnostics mask. In addition, the Diags.setMaskEnabled configuration parameter must be set to true in order to load this function onto the target. Finally, the following configuration parameters must have the values indicated (which are their default values):
  • <module>.common$.namedModule = true;
  • Text.isLoaded = true;
Note: any error that occurs during the parsing of the control string causes Diags_setmask() to return without processing the remainder of the control string.
EXAMPLES
The following example demonstrates how to set a module's diagnostics mask (the Task module in this case) at runtime. In this example, the USER1 bit is turned on. Note that the module's USER1 diagnostics bit must be configured to be runtime modifiable. In this instance, the bit is initialized to off.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Task = xdc.useModule('ti.sysbios.knl.Task');
  Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
C Code
  Diags_setMask("ti.sysbios.knl.Task+1");
The following example demonstrates the use of the % wildcard character to set the USER1 bit at runtime for all modules in the ti.sysbios.knl package. The meta-only Diags.setMaskMeta function is used to configure the USER1 bit to be runtime modifiable. The setMask function is used to actually set the USER1 bit at runtime in all the ti.sysbios.knl modules. Note the use of the % character in both functions to match all the module names within the given package.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
C Code
  Diags_setMask("ti.sysbios.knl.%+1");
In the following example, the ENTRY, EXIT and LIFECYCLE trace is enabled for all modules in the ti.sysbios.knl package but is initially off; i.e., no events will occur until explicitly turned on at runtime.
At runtime the call to Diags_setMask turns on ENTRY and EXIT trace and turns off LIFECYCLE trace for all modules in the application for which trace has been enabled during configuration. In this case, the only modules that can generate events are those in the ti.sysbios.knl package.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.knl.%",
      Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
C Code
  Diags_setMask("%+EX;%-L");
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Diags_Module_id();
// Get this module's unique id
Bool Diags_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Diags_Module_heap();
// The heap from which this module allocates memory
Bool Diags_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Diags_Module_getMask();
// Returns the diagnostics mask for this module
Void Diags_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Diags.xdc
var Diags = xdc.useModule('xdc.runtime.Diags');
module-wide constants & types
    const Diags.ALL// Mask of all diagnostics categories, including both logging and asserts = 0xFF9F;
    const Diags.ALL_LOGGING// Mask of all logging diagnostic categories (does not include asserts) = Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL);
    const Diags.ANALYSIS// Analysis (e.g., benchmark) event = Diags.USER8;
    const Diags.ASSERT// Assert checking = 0x0010;
    const Diags.CRITICAL// A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL' = Diags.LEVEL2;
    const Diags.EMERGENCY// A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY' = Diags.LEVEL1;
    const Diags.ENTRY// Function entry = 0x0001;
    const Diags.ERROR// A 'LEVEL3' 'STATUS' event is defined as 'ERROR' = Diags.LEVEL3;
    const Diags.EXIT// Function exit = 0x0002;
    const Diags.INFO// Informational event = Diags.USER7;
    const Diags.INTERNAL// Internal diagnostics = 0x0008;
    const Diags.LIFECYCLE// Object life-cycle = 0x0004;
    const Diags.STATUS// Warning or error event = 0x0080;
    const Diags.USER1// User defined diagnostics = 0x0100;
    const Diags.USER2// User defined diagnostics = 0x0200;
    const Diags.USER3// User defined diagnostics = 0x0400;
    const Diags.USER4// User defined diagnostics = 0x0800;
    const Diags.USER5// User defined diagnostics = 0x1000;
    const Diags.USER6// User defined diagnostics = 0x2000;
    const Diags.USER7// Alias for informational event = 0x4000;
    const Diags.USER8// Alias for analysis event = 0x8000;
    const Diags.WARNING// A 'LEVEL4' 'STATUS' event is defined as 'WARNING' = Diags.LEVEL4;
    values of type Diags.EventLevel// The level of an event
        const Diags.LEVEL1;
        const Diags.LEVEL2;
        const Diags.LEVEL3;
        const Diags.LEVEL4;
    values of type Diags.Mode// Diagnostics mask bit value used at configuration time
        const Diags.ALWAYS_OFF// permanently disabled;
        const Diags.ALWAYS_ON// permanently enabled;
        const Diags.RUNTIME_OFF// run-time settable, initially disabled;
        const Diags.RUNTIME_ON// run-time settable, initially enabled;
module-wide config parameters
     Diags.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     Diags.setMaskMeta// Set the module's diagnostics mask at config time(Any pattern, Bits16 mask, Diags.Mode mode) returns Void
const Diags.ALL
index URL

Mask of all diagnostics categories, including both logging and asserts

XDCscript usage meta-domain
const Diags.ALL = 0xFF9F;
C SYNOPSIS
Diags_ALL
const Diags.ALL_LOGGING
index URL

Mask of all logging diagnostic categories (does not include asserts)

XDCscript usage meta-domain
const Diags.ALL_LOGGING = Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL);
C SYNOPSIS
Diags_ALL_LOGGING
const Diags.ANALYSIS
index URL

Analysis (e.g., benchmark) event

XDCscript usage meta-domain
const Diags.ANALYSIS = Diags.USER8;
C SYNOPSIS
Diags_ANALYSIS
const Diags.ASSERT
index URL

Assert checking

XDCscript usage meta-domain
const Diags.ASSERT = 0x0010;
C SYNOPSIS
Diags_ASSERT
const Diags.CRITICAL
index URL

A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'

XDCscript usage meta-domain
const Diags.CRITICAL = Diags.LEVEL2;
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
Diags_CRITICAL
const Diags.EMERGENCY
index URL

A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'

XDCscript usage meta-domain
const Diags.EMERGENCY = Diags.LEVEL1;
DETAILS
For STATUS events only, the meaning of the four EventLevels has been defined. These constants are simply aliases for the four event levels.
The highest three levels are different severities of an error event. For example, an EMERGENCY event may represent an unrecoverable system failure, a CRITICAL event may require notification of an operator, and an ERROR may be a recoverable error.
The lowest level is reserved for warnings, such as when a resource becomes dangerously low.
C SYNOPSIS
Diags_EMERGENCY
const Diags.ENTRY
index URL

Function entry

XDCscript usage meta-domain
const Diags.ENTRY = 0x0001;
C SYNOPSIS
Diags_ENTRY
const Diags.ERROR
index URL

A 'LEVEL3' 'STATUS' event is defined as 'ERROR'

XDCscript usage meta-domain
const Diags.ERROR = Diags.LEVEL3;
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
Diags_ERROR
const Diags.EXIT
index URL

Function exit

XDCscript usage meta-domain
const Diags.EXIT = 0x0002;
C SYNOPSIS
Diags_EXIT
const Diags.INFO
index URL

Informational event

XDCscript usage meta-domain
const Diags.INFO = Diags.USER7;
C SYNOPSIS
Diags_INFO
const Diags.INTERNAL
index URL

Internal diagnostics

XDCscript usage meta-domain
const Diags.INTERNAL = 0x0008;
C SYNOPSIS
Diags_INTERNAL
const Diags.LIFECYCLE
index URL

Object life-cycle

XDCscript usage meta-domain
const Diags.LIFECYCLE = 0x0004;
C SYNOPSIS
Diags_LIFECYCLE
const Diags.STATUS
index URL

Warning or error event

XDCscript usage meta-domain
const Diags.STATUS = 0x0080;
C SYNOPSIS
Diags_STATUS
const Diags.USER1
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER1 = 0x0100;
C SYNOPSIS
Diags_USER1
const Diags.USER2
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER2 = 0x0200;
C SYNOPSIS
Diags_USER2
const Diags.USER3
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER3 = 0x0400;
C SYNOPSIS
Diags_USER3
const Diags.USER4
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER4 = 0x0800;
C SYNOPSIS
Diags_USER4
const Diags.USER5
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER5 = 0x1000;
C SYNOPSIS
Diags_USER5
const Diags.USER6
index URL

User defined diagnostics

XDCscript usage meta-domain
const Diags.USER6 = 0x2000;
C SYNOPSIS
Diags_USER6
const Diags.USER7
index URL

Alias for informational event

XDCscript usage meta-domain
const Diags.USER7 = 0x4000;
C SYNOPSIS
Diags_USER7
const Diags.USER8
index URL

Alias for analysis event

XDCscript usage meta-domain
const Diags.USER8 = 0x8000;
C SYNOPSIS
Diags_USER8
const Diags.WARNING
index URL

A 'LEVEL4' 'STATUS' event is defined as 'WARNING'

XDCscript usage meta-domain
const Diags.WARNING = Diags.LEVEL4;
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
Diags_WARNING
enum Diags.EventLevel
index URL

The level of an event

XDCscript usage meta-domain
values of type Diags.EventLevel
    const Diags.LEVEL1;
    const Diags.LEVEL2;
    const Diags.LEVEL3;
    const Diags.LEVEL4;
DETAILS
The diagnostics bits each represent a different category of event, for example: an analysis event, a lifecycle event, or an informational event. Within each of these categories, events may have one of four levels to enable filtering based on the level of information desired.
The meaning of these levels and the distinction between them is left open to the user. Depending on the meaning given, different terminology may be used to describe them--they may be levels of detail, priority, severity, etc. The heirarchy of the events is set such that LEVEL1 is the highest priority and LEVEL4 is the lowest. That is, enabling LEVEL4 events implies that events of all four levels will be logged.
LEVEL1
Least detail, highest priority, most severe, etc.
LEVEL2
LEVEL3
LEVEL4
Most detail, lowest priority, least severe, etc.
The STATUS bit is the only category where the levels are given explicit meaning to ensure consistency. Within the STATUS category, the meaning of the levels is defined by the constants EMERGENCY, CRITICAL, ERROR, and WARNING.
Events which don't define a level will receive LEVEL1 by default.
C SYNOPSIS
Diags_EventLevel
metaonly enum Diags.Mode
index URL

Diagnostics mask bit value used at configuration time

XDCscript usage meta-domain
values of type Diags.Mode
    const Diags.ALWAYS_OFF;
    // permanently disabled
    const Diags.ALWAYS_ON;
    // permanently enabled
    const Diags.RUNTIME_OFF;
    // run-time settable, initially disabled
    const Diags.RUNTIME_ON;
    // run-time settable, initially enabled
DETAILS
At run-time a module's diagnostics mask is an ordinary data word with each bit value being 0 or 1 indicating whether or not the corresponding diagnostic is disabled or enabled. At configuration time, however, each bit of the diagnostics mask can be placed in one of several Modes; these modes determine its initial runtime value and whether or not the bit is modifiable at runtime.
When setting a module's diagnostics mask at configuration time, use one of the enumerated values of type Mode. These values will either set or clear a bit in the mask and also define if the bit can be changed at run-time. For example, using ALWAYS_OFF as the bit value means that bit cannot be set at run-time. This fact can be used by an optimizer to perform constant-folding and dead-code elimination.
metaonly config Diags.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Diags.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly Diags.setMaskMeta() // module-wide
index URL

Set the module's diagnostics mask at config time

XDCscript usage meta-domain
Diags.setMaskMeta(Any pattern, Bits16 mask, Diags.Mode mode) returns Void
ARGUMENTS
pattern — module prefix or regular expression
The pattern is used to match a module's name. If pattern is specified as a string, then name prefix matching is used. The pattern may also be a regular expression. Only the masks of the modules matching pattern are set.
mask — diagnostic fields to modify
The mask is used to determine which fields in the diags mask are modified. Each field specified in the mask is set to the given mode value.
mode — mode to assign to the specified mask fields
generated on Fri, 17 Jun 2011 00:24:31 GMT


module xdc.runtime.Error
index URL

Runtime error manager

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Error.xdc
#include <xdc/runtime/Error.h>
Functions
Bool | Error_check// Return TRUE if an error was raised(Error_Block *eb);
UInt16 | Error_getCode// Get an error's code(Error_Block *eb);
Error_Data * | Error_getData// Get an error's argument list(Error_Block *eb);
Error_Id | Error_getId// Get an error's id(Error_Block *eb);
String | Error_getMsg// Get an error's "printf" format string(Error_Block *eb);
Types_Site * | Error_getSite// Get an error's call site info(Error_Block *eb);
Void | Error_init// Put an error block into its initial state(Error_Block *eb);
Void | Error_print// Print error using System.printf()(Error_Block *eb);
macro Void | Error_raise// Raise an error(Error_Block *eb, Error_Id id, IArg arg1, IArg arg2);
Functions common to all target modules
 | Error_Module_getMask// Returns the diagnostics mask for this module, Error_Module_hasMask// Test whether this module has a diagnostics mask, Error_Module_heap// The heap from which this module allocates memory, Error_Module_id// Get this module's unique id, Error_Module_setMask// Set the diagnostics mask for this module, Error_Module_startupDone// Test if this module has completed startup
Defines
#define | Error_NUMARGS// Maximum number of arguments supported by an error (Int)2
Typedefs
typedef struct | Error_Block// Error block Error_Block;
typedef struct | Error_Data// Error args ...
typedef Void | (*Error_HookFxn// Function called whenever an error is raised)(Error_Block*);
typedef opaque | Error_Id// Error identifier;
typedef enum | Error_Policy// Error handling policies ...
Constants
extern const Error_Id | Error_E_generic// Generic error;
extern const Error_Id | Error_E_memory// Out of memory error;
extern const Error_Id | Error_E_msgCode// Generic error that displays a string and a numeric value;
extern const UInt16 | Error_maxDepth// Maximum number of concurrent calls to raiseHook;
extern const Error_Policy | Error_policy// System-wide error handling policy;
extern const Error_HookFxn | Error_raiseHook// The function to call whenever an error is raised;
DETAILS
The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters.
Modules may define specific error types and reference these when raising an error. Each error type has a custom error message and can be parameterized with up to NUMARGS arguments. A generic error type is provided for raising errors when not in a module.
Use the Error_check() function to determine if an error has been raised. It is important to understand that it is the caller's responsibility to check the error block after calling a function that takes an error block as an argument. Otherwise, a raised error may go undetected, which could compromise the integrity of the system. For example:
  Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }
The Error.raiseHook configuration parameter allows a configured function to be invoked when any error is raised. This function is passed a pointer to the error's error block and makes it easy to manage all errors from a common point. For example, you can trap any error (fatal or not) by simply setting a breakpoint in this function. You can use the following functions to extract information from an error block.
  • Error_getData()
  • Error_getCode()
  • Error_getId()
  • Error_getMsg()
  • Error_getSite()
The Error module provides facilities for handling errors, but the Log module also provides features for logging error events. These are separate concepts; however, to ensure that users do not have to both raise and log an error, the Error module will automatically log an error event when one is raised. The Error module logs the standard Log.L_error event, passing it the error message and arguments.
The error event is logged to the Error module's logger using the Error module's diags mask. Logging of errors is enabled by default in the diags mask, but the event will not be logged unless a logger is configured for the Error module as well.
To make the error event appear as though it is coming from the module which called Error_raise, the event is logged with the caller's module id and with the caller's call site information.
EXAMPLES
Example 1: The following example shows how a module, named ModA, defines a custom error type and shows how this error is raised by the module. The module defines an Id of E_notEven in its module specification file (in this case, ModA.xdc). The error's message string takes only one argument. The module also defines a mayFail() function that takes an error block. In the module's C source file, the function checks for the error condition and raises the error if needed.
This is part of ModA's XDC specification file for the module:
  config xdc.runtime.Error.Id E_notEven = {
      msg: "expected an even number (%d)"
  };

  Void mayFail(Int x, xdc.runtime.Error.Block *eb);
This is part of the C code for the module:
  Void ModA_mayFail(Int x, Error_Block *eb)
  {
      if ((x % 2) != 0) {
          Error_raise(eb, ModA_E_notEven, x, 0);
          ...add error handling code here...
          return;
      }
      ...
  }
Example 2: The following C code supplies an error block to a function that requires one and tests the error block to see if the function raised an error. Note that an error block must be initialized before it can be used and same error block may be passed to several functions.
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>
  Error_Block eb;
  Task_Handle tsk;

  Error_init(&eb);
  tsk = Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }
Example 3: The following C code shows that you may pass NULL to a function requiring an error block. In this case, if the function raises an error, the program is aborted (via xdc_runtime_System_abort()), thus execution control will never return to the caller.
  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>

  tsk = Task_create(..., NULL);
  ...will never get here if an error was raised in Task_create...
Example 4: The following C code shows how to write a function that is not part of a module and that takes an error block and raises the generic error type provided by the Error module. Note, if the caller passes NULL for the error block or if the error policy is TERMINATE, then the call to Error_raise() will call xdc_runtime_System_abort() and never return.
  #include <xdc/runtime/Error.h>

  Void myFunc(..., Error_Block *eb)
  {
      ...

      if (...error condition detected...) {
          String  myErrorMsg = "my custom error message";
          Error_raise(eb, Error_E_generic, myErrorMsg, 0);
          ...add error handling code here...
          return;
      }
  }
const Error_NUMARGS
index URL

Maximum number of arguments supported by an error

C synopsis target-domain
#define Error_NUMARGS (Int)2
enum Error_Policy
index URL

Error handling policies

C synopsis target-domain
typedef enum Error_Policy {
    Error_TERMINATE,
    Error_UNWIND
} Error_Policy;
VALUES
TERMINATE — All raised errors are fatal. A call to Error_raise will never return to the caller.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
Regardless of the current policy in use, raising an error by calling Error_raise will always invoke the error raise hook function assigned to the Error.raiseHook configuration parameter.
typedef Error_HookFxn
index URL

Function called whenever an error is raised

C synopsis target-domain
typedef Void (*Error_HookFxn)(Error_Block*);
DETAILS
The first parameter and only parameter passed to this function is a pointer to an Error_Block. Even if the client passes a NULL error block pointer to Error_raise, this parameter passed to this "hook" function is always non-NULL.
typedef Error_Id
index URL

Error identifier

C synopsis target-domain
typedef opaque Error_Id;
DETAILS
Each type of error raised is defined with a metaonly Error.Desc. An Error_Id is a 32-bit target value that encodes the information in the Desc. Target programs use Error_Id values to "raise" and check for specific errors.
WARNING
Id values may vary among different configurations of an application. For example, the addition of a new module to a program may result in a different absolute value for E_generic. If you need error numbers that remain invariant, use the user definable Desc.code field.
struct Error_Block
index URL

Error block

C synopsis target-domain
typedef struct Error_Block Error_Block;
DETAILS
An opaque structure used to store information about errors once raised. This structure must be initialized via Error_init() before being used for the first time.
struct Error_Data
index URL

Error args

C synopsis target-domain
typedef struct Error_Data {
    IArg arg[Error_NUMARGS];
} Error_Data;
DETAILS
The two arguments (arg1, arg2) passed to raise are stored in one of these arrays within the associated Error_Block. To access these arguments use getData to obtain a pointer to the Error_Block's Data array.
SEE
getData
config Error_E_generic // module-wide
index URL

Generic error

C synopsis target-domain
extern const Error_Id Error_E_generic;
DETAILS
This error takes advantage of the $S specifier to allow for recursive formatting of the error message passed to error raise.
For example, the following is possible:
  Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
SEE
System.extendedFormats, System.printf
config Error_E_memory // module-wide
index URL

Out of memory error

C synopsis target-domain
extern const Error_Id Error_E_memory;
DETAILS
The first parameter must be the heap instance handle. The second parameter is the size of the object for which the allocation failed.
config Error_E_msgCode // module-wide
index URL

Generic error that displays a string and a numeric value

C synopsis target-domain
extern const Error_Id Error_E_msgCode;
config Error_maxDepth // module-wide
index URL

Maximum number of concurrent calls to raiseHook

C synopsis target-domain
extern const UInt16 Error_maxDepth;
DETAILS
To prevent errors that occur in the raiseHook function from causing an infinite recursion, the maximum number of concurrent calls to raiseHook is limited by Error_maxDepth. If the number of concurrent calls exceeds Error_maxDepth, the raiseHook function is not called.
In multi-threaded systems, errors raised by separate threads may be detected as recursive calls to raiseHook. So, setting Error.maxDepth to a small value may - in rare instances - result in errorHook not being called for some raised errors.
If it is important that all raised errors trigger a call to the raiseHook function, set Error.maxDepth to an impossibly large number (0xffff) and either ensure that the raise hook never calls a function that can raise an error or add checks in raiseHook to protect against "double faults".
config Error_policy // module-wide
index URL

System-wide error handling policy

C synopsis target-domain
extern const Error_Policy Error_policy;
config Error_raiseHook // module-wide
index URL

The function to call whenever an error is raised

C synopsis target-domain
extern const Error_HookFxn Error_raiseHook;
DETAILS
This function is always called when an error is raised, even if the Error policy is TERMINATE. In rare cases, it is possible that a raised error does not trigger a call to raiseHook; see maxDepth.
By default, this function is set to Error_print which causes the error to be formatted and output via System_printf.
SEE
maxDepth, HookFxn, print
Error_check() // module-wide
index URL

Return TRUE if an error was raised

C synopsis target-domain
Bool Error_check(Error_Block *eb);
ARGUMENTS
eb — pointer to an Error_Block or NULL
RETURNS
If eb is non-NULL and Error.policy == UNWIND and an error was raised on eb, this function returns TRUE. Otherwise, it returns FALSE.
Error_getCode() // module-wide
index URL

Get an error's code

C synopsis target-domain
UInt16 Error_getCode(Error_Block *eb);
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getCode returns the error code associated with this error block.
SEE
raise, Desc
Error_getData() // module-wide
index URL

Get an error's argument list

C synopsis target-domain
Error_Data *Error_getData(Error_Block *eb);
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getData returns an array of type Data with NUMARGS elements containing the arguments provided at the time the error was raised.
SEE
raise
Error_getId() // module-wide
index URL

Get an error's id

C synopsis target-domain
Error_Id Error_getId(Error_Block *eb);
ARGUMENTS
eb — non-NULL pointer to an Error_Block
WARNING
Error_Id values may vary among different configurations of an application. For example, the addition of a new module to a program may result in a different absolute value for E_generic. If you need error numbers that remain invariant, use the user definable Desc.code field.
SEE
raise, Desc
Error_getMsg() // module-wide
index URL

Get an error's "printf" format string

C synopsis target-domain
String Error_getMsg(Error_Block *eb);
ARGUMENTS
eb — non-NULL pointer to an Error_Block
SEE
raise, Desc
Error_getSite() // module-wide
index URL

Get an error's call site info

C synopsis target-domain
Types_Site *Error_getSite(Error_Block *eb);
ARGUMENTS
eb — non-NULL pointer to an Error_Block
RETURNS
getSite returns a pointer to an initialized Types.Site structure. However, in the event that the call site was compiled with xdc_FILE defined to be NULL (to minimize string space overhead) the file field may be set to NULL.
SEE
raise, Desc
Error_init() // module-wide
index URL

Put an error block into its initial state

C synopsis target-domain
Void Error_init(Error_Block *eb);
ARGUMENTS
eb — pointer to an Error_Block or NULL
If eb is NULL this function simply returns.
DETAILS
To ensure reliable error detection, clients must call init for an Error_Block prior to any use.
If the same Error Block is used multiple times, only the last error raised is retained.
Error_print() // module-wide
index URL

Print error using System.printf()

C synopsis target-domain
Void Error_print(Error_Block *eb);
ARGUMENTS
eb — pointer to an Error_Block or NULL
If eb is NULL this function simply returns with no output.
DETAILS
This function prints the error using System_printf(). The output is on a single line terminated with a new line character and has the following form:
      <site>: <file>, line <line_num>: <err_msg>
where <site> is the module that raised the error, <file> and <line_num> are the file and line number of the containing the call site of the Error_raise(), and <err_msg> is the error message rendered with the arguments associated with the error.
WARNING
This function is not protected by a gate and, as a result, if two threads call this method concurrently, the output of the two calls will be intermingled. To prevent intermingled error output, you can either wrap all calls to this method with an appropriate Gate_enter/Gate_leave pair or simply ensure that only one thread in the system ever calls this method.
Error_raise() // module-wide
index URL

Raise an error

C synopsis target-domain
macro Void Error_raise(Error_Block *eb, Error_Id id, IArg arg1, IArg arg2);
ARGUMENTS
eb — pointer to an Error_Block or NULL
If eb is NULL or Error.policy == TERMINATE, this function does not return to the caller; after calling any configured raiseHook, System_abort is called with the string "xdc.runtime.Error.raise: terminating execution\n".
id — the error to raise
This pointer identifies the class of error being raised; the error class indicates how to interpret any subsequent arguments passed to raise.
arg1 — error's first argument
The argument interpreted by the first control character in the error message format string. It is ignored if not needed.
arg2 — error's second argument
The argument interpreted by the second control character in the error message format string. It is ignored if not needed.
DETAILS
This function is used to raise an Error by writing call site, error ID, and error argument information into the Error_Block pointed to by eb.
If Error_raise is called more than once on an Error_Block object, the previous error information is overwritten; only the last error is retained in the Error_Block object.
In all cases, any configured Error.raiseHook function is called with a non-NULL pointer to a fully initialized Error_Block object.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Error_Module_id();
// Get this module's unique id
Bool Error_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Error_Module_heap();
// The heap from which this module allocates memory
Bool Error_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Error_Module_getMask();
// Returns the diagnostics mask for this module
Void Error_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Error.xdc
var Error = xdc.useModule('xdc.runtime.Error');
module-wide constants & types
    const Error.NUMARGS// Maximum number of arguments supported by an error = 2;
    values of type Error.Policy// Error handling policies
        const Error.TERMINATE;
        const Error.UNWIND;
    var obj = new Error.Data// Error args;
        obj.arg = IArg[Error.NUMARGS] ...
    var obj = new Error.Desc// Error descriptor;
        obj.msg = String ...
        obj.code = UInt16 ...
module-wide config parameters
     Error.E_generic// Generic error = Error.Desc {
        msg: "%$S"
    };
     Error.E_memory// Out of memory error = Error.Desc {
        msg: "out of memory: heap=0x%x, size=%u"
    };
     Error.E_msgCode// Generic error that displays a string and a numeric value = Error.Desc {
        msg: "%s 0x%x"
    };
     Error.maxDepth// Maximum number of concurrent calls to raiseHook = UInt16 16;
     Error.policy// System-wide error handling policy = Error.Policy Error.UNWIND;
     Error.raiseHook// The function to call whenever an error is raised = Void(*)(Error.Block*) Error.print;
     Error.common$// Common module configuration parameters = Types.Common$ undefined;
const Error.NUMARGS
index URL

Maximum number of arguments supported by an error

XDCscript usage meta-domain
const Error.NUMARGS = 2;
C SYNOPSIS
Error_NUMARGS
enum Error.Policy
index URL

Error handling policies

XDCscript usage meta-domain
values of type Error.Policy
    const Error.TERMINATE;
    const Error.UNWIND;
VALUES
TERMINATE — All raised errors are fatal. A call to Error_raise will never return to the caller.
UNWIND — Errors are returned to the caller. A call to Error_raise will return back to the caller.
DETAILS
Regardless of the current policy in use, raising an error by calling Error_raise will always invoke the error raise hook function assigned to the Error.raiseHook configuration parameter.
C SYNOPSIS
Error_Policy
struct Error.Data
index URL

Error args

XDCscript usage meta-domain
var obj = new Error.Data;
    obj.arg = IArg[Error.NUMARGS] ...
DETAILS
The two arguments (arg1, arg2) passed to raise are stored in one of these arrays within the associated Error_Block. To access these arguments use getData to obtain a pointer to the Error_Block's Data array.
SEE
getData
C SYNOPSIS
Error_Data
metaonly struct Error.Desc
index URL

Error descriptor

XDCscript usage meta-domain
var obj = new Error.Desc;
    obj.msg = String ...
    obj.code = UInt16 ...
FIELDS
msg — The error message using a printf style format string, but limited to NUMARGS arguments. This format string together with the two arguments passed to Error_raise` are used to create a human readable error message.
code — A user assignable code, 0 by default. The user may optionally set this field during config to give the error a well-known numeric code.
DETAILS
Each type of error is defined with an error descriptor. This structure groups common information about the errors of this type.
config Error.E_generic // module-wide
index URL

Generic error

XDCscript usage meta-domain
Error.E_generic = Error.Desc {
    msg: "%$S"
};
DETAILS
This error takes advantage of the $S specifier to allow for recursive formatting of the error message passed to error raise.
For example, the following is possible:
  Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
SEE
System.extendedFormats, System.printf
C SYNOPSIS
Error_E_generic
config Error.E_memory // module-wide
index URL

Out of memory error

XDCscript usage meta-domain
Error.E_memory = Error.Desc {
    msg: "out of memory: heap=0x%x, size=%u"
};
DETAILS
The first parameter must be the heap instance handle. The second parameter is the size of the object for which the allocation failed.
C SYNOPSIS
Error_E_memory
config Error.E_msgCode // module-wide
index URL

Generic error that displays a string and a numeric value

XDCscript usage meta-domain
Error.E_msgCode = Error.Desc {
    msg: "%s 0x%x"
};
C SYNOPSIS
Error_E_msgCode
config Error.maxDepth // module-wide
index URL

Maximum number of concurrent calls to raiseHook

XDCscript usage meta-domain
Error.maxDepth = UInt16 16;
DETAILS
To prevent errors that occur in the raiseHook function from causing an infinite recursion, the maximum number of concurrent calls to raiseHook is limited by Error_maxDepth. If the number of concurrent calls exceeds Error_maxDepth, the raiseHook function is not called.
In multi-threaded systems, errors raised by separate threads may be detected as recursive calls to raiseHook. So, setting Error.maxDepth to a small value may - in rare instances - result in errorHook not being called for some raised errors.
If it is important that all raised errors trigger a call to the raiseHook function, set Error.maxDepth to an impossibly large number (0xffff) and either ensure that the raise hook never calls a function that can raise an error or add checks in raiseHook to protect against "double faults".
C SYNOPSIS
Error_maxDepth
config Error.policy // module-wide
index URL

System-wide error handling policy

XDCscript usage meta-domain
Error.policy = Error.Policy Error.UNWIND;
C SYNOPSIS
Error_policy
config Error.raiseHook // module-wide
index URL

The function to call whenever an error is raised

XDCscript usage meta-domain
Error.raiseHook = Void(*)(Error.Block*) Error.print;
DETAILS
This function is always called when an error is raised, even if the Error policy is TERMINATE. In rare cases, it is possible that a raised error does not trigger a call to raiseHook; see maxDepth.
By default, this function is set to Error_print which causes the error to be formatted and output via System_printf.
SEE
maxDepth, HookFxn, print
C SYNOPSIS
Error_raiseHook
metaonly config Error.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Error.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.Gate
index URL

Critical section support

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
Gates are used by clients to protect concurrent access to critical data structures. Critical data structures are those that must be updated by at most one thread at a time. All code that needs access to a critical data structure "enters" a gate (that's associated with the data structure) prior to accessing the data, modifies the data structure, then "leaves" the gate. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Gate.xdc
#include <xdc/runtime/Gate.h>
Functions
macro Gate_Ref | Gate_allocInstance// Allocate a gate instance from the current module's gate(Error_Block *eb);
macro Bool | Gate_canBePreempted// Check if the module level gate allows thread preemption();
macro Bool | Gate_canBlock// Check if the module level gate can block threads();
macro IArg | Gate_enterInstance// Enter a critical section protected by this gate instance(Gate_Ref gate);
macro IArg | Gate_enterModule// Enter a critical section protected by the current module's gate();
IArg | Gate_enterSystem// Enter a critical section protected by the global System gate();
macro Void | Gate_freeInstance// Free a gate instance to the current module's gatekeeper(Gate_Ref gate);
macro Void | Gate_leaveInstance// Leave a critical section protected by a gate(Gate_Ref gate, IArg key);
macro Void | Gate_leaveModule// Leave a critical section protected by the current module's gate(IArg key);
Void | Gate_leaveSystem// Leave a critical section protected by the global System gate(IArg key);
Functions common to all target modules
 | Gate_Module_getMask// Returns the diagnostics mask for this module, Gate_Module_hasMask// Test whether this module has a diagnostics mask, Gate_Module_heap// The heap from which this module allocates memory, Gate_Module_id// Get this module's unique id, Gate_Module_setMask// Set the diagnostics mask for this module, Gate_Module_startupDone// Test if this module has completed startup
Typedefs
typedef opaque | Gate_Ref// Opaque reference to an allocated gate instance;
DETAILS
Gates are used by clients to protect concurrent access to critical data structures. Critical data structures are those that must be updated by at most one thread at a time. All code that needs access to a critical data structure "enters" a gate (that's associated with the data structure) prior to accessing the data, modifies the data structure, then "leaves" the gate.
A gate is responsible for ensuring that at most one thread at a time can enter and execute "inside" the gate. There are several implementations of gates, with different system executation times and latency tradoffs. In addition, some gates must not be entered by certain thread types; e.g., a gate that is implemented via a "blocking" semaphore must not be called by an interrupt service routine (ISR).
A module can be declared "gated" by adding the @Gated attribute to the module's XDC spec file. A "gated" module is assigned a module-level gate at the configuration time, and that gate is then used to protect critical sections in the module's target code. A module-level gate is an instance of a module implementing IGateProvider interface. However, gated modules do not access their module-level gates directly. They use this module to access transparently their module-level gate.
Application code that is not a part of any module also has a module-level gate, configured through the module Main.
Each gated module can optionally create gates on an adhoc basis at runtime using the same gate module that was used to create the module level gate.
Gates that work by disabling all preemption while inside a gate can be used to protect data structures accessed by ISRs and other threads. But, if the time required to update the data structure is not a small constant, this type of gate may violate a system's real-time requirements.
Gates have two orthogonal attributes: "blocking" and "preemptible". In general, gates that are "blocking" can not be use by code that is called by ISRs and gates that are not "preemptible" should only be used to to protect data manipulated by code that has small constant execution time.
typedef Gate_Ref
index URL

Opaque reference to an allocated gate instance

C synopsis target-domain
typedef opaque Gate_Ref;
Gate_allocInstance() // module-wide
index URL

Allocate a gate instance from the current module's gate

C synopsis target-domain
macro Gate_Ref Gate_allocInstance(Error_Block *eb);
ARGUMENTS
eb — Error block pointer
If NULL, any error in creating the instance will terminate the application.
DETAILS
This method is used by modules to create gates at runtime using the same IGateProvider that was used to create the module level gate. The parameters passed to the IGateProvider are specified at configuration time via the Types.Common$.gateParams configuration parameter.
RETURNS
Non-NULL instance handle is returned if no error occurs; otherwise an error is raised in eb and NULL is returned.
SEE
IGateProvider, Error
Gate_canBePreempted() // module-wide
index URL

Check if the module level gate allows thread preemption

C synopsis target-domain
macro Bool Gate_canBePreempted();
DETAILS
This type of gate should always be used by clients that protect a data structure whose updates require more than a small constant amount of time; e.g., update of a memory allocator's free list.
RETURNS
Returns TRUE if the underlying gate does not disable thread preemption.
Gate_canBlock() // module-wide
index URL

Check if the module level gate can block threads

C synopsis target-domain
macro Bool Gate_canBlock();
DETAILS
This type of gate should never be called by clients that must never call a "blocking" RTOS operation; e.g., interrupt service routines
RETURNS
Returns TRUE if the underlying gatekeeper's gate can block
Gate_enterInstance() // module-wide
index URL

Enter a critical section protected by this gate instance

C synopsis target-domain
macro IArg Gate_enterInstance(Gate_Ref gate);
ARGUMENTS
gate — non-NULL return value from a prior call to allocInstance.
RETURNS
Returns a "key" value that must be used to leave gate via leaveInstance().
Gate_enterModule() // module-wide
index URL

Enter a critical section protected by the current module's gate

C synopsis target-domain
macro IArg Gate_enterModule();
RETURNS
Returns a "key" value that must be used to leave the current module gate via leaveModule().
SEE
leaveModule
Gate_enterSystem() // module-wide
index URL

Enter a critical section protected by the global System gate

C synopsis target-domain
IArg Gate_enterSystem();
RETURNS
Returns a "key" value that must be used to leave the System gate via leaveSystem().
SEE
leaveSystem
Gate_freeInstance() // module-wide
index URL

Free a gate instance to the current module's gatekeeper

C synopsis target-domain
macro Void Gate_freeInstance(Gate_Ref gate);
ARGUMENTS
gate — non-NULL return value from a prior call to allocInstance.
SEE
allocInstance
Gate_leaveInstance() // module-wide
index URL

Leave a critical section protected by a gate

C synopsis target-domain
macro Void Gate_leaveInstance(Gate_Ref gate, IArg key);
ARGUMENTS
gate — non-NULL return value from a prior call to allocInstance.
key — the return value of a prior call to enterInstance
SEE
enterInstance, allocInstance
Gate_leaveModule() // module-wide
index URL

Leave a critical section protected by the current module's gate

C synopsis target-domain
macro Void Gate_leaveModule(IArg key);
ARGUMENTS
key — the return value of a prior call to enterModule
SEE
enterModule
Gate_leaveSystem() // module-wide
index URL

Leave a critical section protected by the global System gate

C synopsis target-domain
Void Gate_leaveSystem(IArg key);
ARGUMENTS
key — the return value of a prior call to enterSystem
SEE
enterSystem
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Gate_Module_id();
// Get this module's unique id
Bool Gate_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Gate_Module_heap();
// The heap from which this module allocates memory
Bool Gate_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Gate_Module_getMask();
// Returns the diagnostics mask for this module
Void Gate_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Gate.xdc
var Gate = xdc.useModule('xdc.runtime.Gate');
module-wide config parameters
     Gate.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     Gate.staticAlloc// Assign a statically-allocated gate instance to a state-object field(Any stateObj, String fldName) returns Void
metaonly config Gate.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Gate.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly Gate.staticAlloc() // module-wide
index URL

Assign a statically-allocated gate instance to a state-object field

XDCscript usage meta-domain
Gate.staticAlloc(Any stateObj, String fldName) returns Void
ARGUMENTS
stateObj — the state object for the instance being created
fldName — a name of a field within the state object
This parameter names a field that will point to the created gate instance to be created. It is a caller's responsibility to ensure that the type of fldName is a handle to an IGateProvider instance.
DETAILS
This method is used to create a gate for static instance objects that require a gate.
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.GateNull
index URL

Empty implementation of IGateProvider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
An instance of this IGateProvider implementation is assigned to all gated modules as a default module-wide gate. Instances of this gate implementation provide no protection for critical sections and should only be used for modules in which the data structures protected by module-level gates are never accessed by concurrent threads.
C synopsis target-domain sourced in xdc/runtime/GateNull.xdc
#include <xdc/runtime/GateNull.h>
Functions
Void | GateNull_construct// Initialize a new instance object inside the provided structure(GateNull_Struct *structP, const GateNull_Params *params);
GateNull_Handle | GateNull_create// Allocate and initialize a new instance object and return its handle(const GateNull_Params *params, Error_Block *eb);
Void | GateNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateNull_Handle *handleP);
Void | GateNull_destruct// Finalize the instance object inside the provided structure(GateNull_Struct *structP);
Void | GateNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateNull_Params *params);
Functions common to all IGateProvider modules
IArg | GateNull_enter// Enter this gate(GateNull_Handle handle);
Void | GateNull_leave// Leave this gate(GateNull_Handle handle, IArg key);
Bool | GateNull_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateNull_handle// Convert this instance structure pointer into an instance handle, GateNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateNull_Handle_label// The label associated with this instance object, GateNull_Handle_name// The name of this instance object, GateNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateNull_Object_count// The number of statically-created instance objects, GateNull_Object_first// The handle of the first dynamically-created instance object, or NULL, GateNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateNull_Object_heap// The heap used to allocate dynamically-created instance objects, GateNull_Object_next// The handle of the next dynamically-created instance object, or NULL, GateNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateNull_Module_getMask// Returns the diagnostics mask for this module, GateNull_Module_hasMask// Test whether this module has a diagnostics mask, GateNull_Module_heap// The heap from which this module allocates memory, GateNull_Module_id// Get this module's unique id, GateNull_Module_setMask// Set the diagnostics mask for this module, GateNull_Module_startupDone// Test if this module has completed startup
Defines
#define | GateNull_Q_BLOCKING// Blocking quality (Int)1
#define | GateNull_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateNull_Object * | GateNull_Handle// Client reference to an instance object;
typedef struct | GateNull_Object// Opaque internal representation of an instance object GateNull_Object;
typedef struct | GateNull_Params// Instance config-params structure ...
typedef struct | GateNull_Struct// Opaque client structure large enough to hold an instance object GateNull_Struct;
const GateNull_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateNull_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateNull_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateNull_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateNull_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateNull_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateNull_Module_id();
// Get this module's unique id
Bool GateNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateNull_Module_heap();
// The heap from which this module allocates memory
Bool GateNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateNull_Module_getMask();
// Returns the diagnostics mask for this module
Void GateNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateNull_Object GateNull_Object;
// Opaque internal representation of an instance object
typedef GateNull_Object *GateNull_Handle;
// Client reference to an instance object
typedef struct GateNull_Struct GateNull_Struct;
// Opaque client structure large enough to hold an instance object
GateNull_Handle GateNull_handle(GateNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateNull_Struct *GateNull_struct(GateNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateNull_Params;
Void GateNull_Params_init(GateNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateNull_Handle GateNull_create(const GateNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateNull_construct(GateNull_Struct *structP, const GateNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateNull_delete(GateNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateNull_destruct(GateNull_Struct *structP);
// Finalize the instance object inside the provided structure
GateNull_enter() // instance
index URL

Enter this gate

C synopsis target-domain
IArg GateNull_enter(GateNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateNull instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
GateNull_leave() // instance
index URL

Leave this gate

C synopsis target-domain
Void GateNull_leave(GateNull_Handle handle, IArg key);
ARGUMENTS
handle — handle of a previously-created GateNull instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateNull_Handle_upCast(GateNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateNull_Handle GateNull_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateNull_Object_count();
// The number of statically-created instance objects
GateNull_Handle GateNull_Object_get(GateNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateNull_Handle GateNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateNull_Handle GateNull_Object_next(GateNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateNull_Handle_label(GateNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateNull_Handle_name(GateNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/GateNull.xdc
var GateNull = xdc.useModule('xdc.runtime.GateNull');
module-wide constants & types
    const GateNull.Q_BLOCKING// Blocking quality = 1;
    const GateNull.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateNull.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateNull.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateNull.Params// Instance config-params object;
per-instance creation
    var inst = GateNull.create// Create an instance-object(params);
const GateNull.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateNull.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateNull_Q_BLOCKING
const GateNull.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateNull.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateNull_Q_PREEMPTING
metaonly config GateNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateNull.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateNull.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateNull.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateNull.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.HeapMin
index URL

Growth-only based heap implementation

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
HeapMin is a minimal footprint heap implementation. This module is is designed for applications that only create module instances and generally only allocate memory at runtime, but never delete created instances or free memory explicitly. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/HeapMin.xdc
#include <xdc/runtime/HeapMin.h>
Functions
Void | HeapMin_construct// Initialize a new instance object inside the provided structure(HeapMin_Struct *structP, const HeapMin_Params *params);
HeapMin_Handle | HeapMin_create// Allocate and initialize a new instance object and return its handle(const HeapMin_Params *params, Error_Block *eb);
Void | HeapMin_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapMin_Handle *handleP);
Void | HeapMin_destruct// Finalize the instance object inside the provided structure(HeapMin_Struct *structP);
Void | HeapMin_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapMin_Params *params);
Functions common to all IHeap modules
Ptr | HeapMin_alloc// Allocate a block of memory from the heap(HeapMin_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapMin_free// Free a block of memory back to the heap(HeapMin_Handle handle, Ptr block, SizeT size);
Void | HeapMin_getStats// Retrieve the statistics from the heap(HeapMin_Handle handle, Memory_Stats *stats);
Bool | HeapMin_isBlocking// Can this heap block the caller(HeapMin_Handle handle);
Functions common to all target instances
 | HeapMin_handle// Convert this instance structure pointer into an instance handle, HeapMin_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapMin_Handle_label// The label associated with this instance object, HeapMin_Handle_name// The name of this instance object, HeapMin_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapMin_Object_count// The number of statically-created instance objects, HeapMin_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapMin_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapMin_Object_heap// The heap used to allocate dynamically-created instance objects, HeapMin_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapMin_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapMin_Module_getMask// Returns the diagnostics mask for this module, HeapMin_Module_hasMask// Test whether this module has a diagnostics mask, HeapMin_Module_heap// The heap from which this module allocates memory, HeapMin_Module_id// Get this module's unique id, HeapMin_Module_setMask// Set the diagnostics mask for this module, HeapMin_Module_startupDone// Test if this module has completed startup
Typedefs
typedef HeapMin_Object * | HeapMin_Handle// Client reference to an instance object;
typedef struct | HeapMin_Object// Opaque internal representation of an instance object HeapMin_Object;
typedef struct | HeapMin_Params// Instance config-params structure ...
typedef struct | HeapMin_Struct// Opaque client structure large enough to hold an instance object HeapMin_Struct;
Constants
extern const Assert_Id | HeapMin_A_zeroSize// Assert that the size is non-zero on the create;
extern const Error_Id | HeapMin_E_freeError// Error raised if free() is called;
extern const Bool | HeapMin_freeError// Flag to control whether E_freeError is enabled;
DETAILS
HeapMin is a minimal footprint heap implementation. This module is is designed for applications that only create module instances and generally only allocate memory at runtime, but never delete created instances or free memory explicitly.
For configuration-time HeapMin.create, the heap is aligned to Memory.getMaxDefaultTypeAlignMeta() for those targets that support static alignment. For targets that do not support static alignment, the buffer alignment is undefined.
When calling create() at runtime, the client is responsible for aligning the buffer.
config HeapMin_A_zeroSize // module-wide
index URL

Assert that the size is non-zero on the create

C synopsis target-domain
extern const Assert_Id HeapMin_A_zeroSize;
config HeapMin_E_freeError // module-wide
index URL

Error raised if free() is called

C synopsis target-domain
extern const Error_Id HeapMin_E_freeError;
DETAILS
This error is only raised if a free() is called and freeError is true.
config HeapMin_freeError // module-wide
index URL

Flag to control whether E_freeError is enabled

C synopsis target-domain
extern const Bool HeapMin_freeError;
DETAILS
If true, a E_freeError error occurs when trying to free a buffer.
If false, no error occurs and the free() does nothing.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId HeapMin_Module_id();
// Get this module's unique id
Bool HeapMin_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle HeapMin_Module_heap();
// The heap from which this module allocates memory
Bool HeapMin_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMin_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMin_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct HeapMin_Object HeapMin_Object;
// Opaque internal representation of an instance object
typedef HeapMin_Object *HeapMin_Handle;
// Client reference to an instance object
typedef struct HeapMin_Struct HeapMin_Struct;
// Opaque client structure large enough to hold an instance object
HeapMin_Handle HeapMin_handle(HeapMin_Struct *structP);
// Convert this instance structure pointer into an instance handle
HeapMin_Struct *HeapMin_struct(HeapMin_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct HeapMin_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Ptr buf;
    // Buffer that will be managed by the heap instance
     Memory_Size size;
    // Size (in MADUs) of the heap
} HeapMin_Params;
Void HeapMin_Params_init(HeapMin_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMin_buf // instance
index URL

Buffer that will be managed by the heap instance

C synopsis target-domain
struct HeapMin_Params {
     ...
    Ptr buf;
DETAILS
When creating a heap at runtime, the user must supply the memory that the heap will manage. It is up to the caller to align the buffer as needed.
This parameter is ignored when creating heaps during configuration.
config HeapMin_size // instance
index URL

Size (in MADUs) of the heap

C synopsis target-domain
struct HeapMin_Params {
     ...
     Memory_Size size;
DETAILS
This parameter specifies the size of the heap managed by a HeapMin instance. In the static case, a buffer of length size will be created. In the dynamic case, size specifies the size of the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an A_zeroSize assert for the runtime create.
Instance Creation
index URL

C synopsis target-domain
HeapMin_Handle HeapMin_create(const HeapMin_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void HeapMin_construct(HeapMin_Struct *structP, const HeapMin_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This heap is a growth-only heap that is intended to be used by systems that never delete objects or free memory. Objects can be created at runtime based on values determined at runtime, but objects can not be deleted.
SEE
HeapMin.Params
Instance Deletion
index URL

C synopsis target-domain
Void HeapMin_delete(HeapMin_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void HeapMin_destruct(HeapMin_Struct *structP);
// Finalize the instance object inside the provided structure
HeapMin_alloc() // instance
index URL

Allocate a block of memory from the heap

C synopsis target-domain
Ptr HeapMin_alloc(HeapMin_Handle handle, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created HeapMin instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
RETURNS
Returns the address of the allocated memory.
CONSTRAINTS
The alignment must be a power of 2.
SEE
IHeap.alloc
HeapMin_free() // instance
index URL

Free a block of memory back to the heap

C synopsis target-domain
Void HeapMin_free(HeapMin_Handle handle, Ptr block, SizeT size);
ARGUMENTS
handle — handle of a previously-created HeapMin instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
This is a growth only heap. Calling the HeapMin_free function will result in a E_freeError error unless freeError is set to false.
SEE
IHeap.free
HeapMin_getStats() // instance
index URL

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapMin_getStats(HeapMin_Handle handle, Memory_Stats *stats);
ARGUMENTS
handle — handle of a previously-created HeapMin instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
HeapMin_isBlocking() // instance
index URL

Can this heap block the caller

C synopsis target-domain
Bool HeapMin_isBlocking(HeapMin_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapMin instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
HeapMin always returns FALSE since it never blocks on a resource.
Instance Convertors
index URL

C synopsis target-domain
IHeap_Handle HeapMin_Handle_upCast(HeapMin_Handle handle);
// unconditionally move one level up the inheritance hierarchy
HeapMin_Handle HeapMin_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int HeapMin_Object_count();
// The number of statically-created instance objects
HeapMin_Handle HeapMin_Object_get(HeapMin_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
HeapMin_Handle HeapMin_Object_first();
// The handle of the first dynamically-created instance object, or NULL
HeapMin_Handle HeapMin_Object_next(HeapMin_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle HeapMin_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *HeapMin_Handle_label(HeapMin_Handle handle, Types_Label *buf);
// The label associated with this instance object
String HeapMin_Handle_name(HeapMin_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/HeapMin.xdc
var HeapMin = xdc.useModule('xdc.runtime.HeapMin');
module-wide config parameters
     HeapMin.A_zeroSize// Assert that the size is non-zero on the create = Assert.Desc {
        msg: "HeapMin_create cannot have a zero size value"
    };
     HeapMin.E_freeError// Error raised if free() is called = Error.Desc {
        msg: "free() invalid in growth-only HeapMin"
    };
     HeapMin.freeError// Flag to control whether E_freeError is enabled = Bool true;
     HeapMin.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new HeapMin.Params// Instance config-params object;
        params.align// Alignment of the buffer being managed by this heap instance = SizeT undefined;
        params.buf// Buffer that will be managed by the heap instance = Ptr 0;
        params.sectionName// Section name of the heap = String null;
        params.size// Size (in MADUs) of the heap = UArg 0;
per-instance creation
    var inst = HeapMin.create// Create an instance-object(params);
config HeapMin.A_zeroSize // module-wide
index URL

Assert that the size is non-zero on the create

XDCscript usage meta-domain
HeapMin.A_zeroSize = Assert.Desc {
    msg: "HeapMin_create cannot have a zero size value"
};
C SYNOPSIS
HeapMin_A_zeroSize
config HeapMin.E_freeError // module-wide
index URL

Error raised if free() is called

XDCscript usage meta-domain
HeapMin.E_freeError = Error.Desc {
    msg: "free() invalid in growth-only HeapMin"
};
DETAILS
This error is only raised if a free() is called and freeError is true.
C SYNOPSIS
HeapMin_E_freeError
config HeapMin.freeError // module-wide
index URL

Flag to control whether E_freeError is enabled

XDCscript usage meta-domain
HeapMin.freeError = Bool true;
DETAILS
If true, a E_freeError error occurs when trying to free a buffer.
If false, no error occurs and the free() does nothing.
C SYNOPSIS
HeapMin_freeError
metaonly config HeapMin.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
HeapMin.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new HeapMin.Params;
// Instance config-params object
    params.align = SizeT undefined;
    // Alignment of the buffer being managed by this heap instance
    params.buf = Ptr 0;
    // Buffer that will be managed by the heap instance
    params.sectionName = String null;
    // Section name of the heap
    params.size = UArg 0;
    // Size (in MADUs) of the heap
config HeapMin.buf // instance
index URL

Buffer that will be managed by the heap instance

XDCscript usage meta-domain
var params = new HeapMin.Params;
...
params.buf = Ptr 0;
DETAILS
When creating a heap at runtime, the user must supply the memory that the heap will manage. It is up to the caller to align the buffer as needed.
This parameter is ignored when creating heaps during configuration.
C SYNOPSIS
null
config HeapMin.size // instance
index URL

Size (in MADUs) of the heap

XDCscript usage meta-domain
var params = new HeapMin.Params;
...
params.size = UArg 0;
DETAILS
This parameter specifies the size of the heap managed by a HeapMin instance. In the static case, a buffer of length size will be created. In the dynamic case, size specifies the size of the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an A_zeroSize assert for the runtime create.
C SYNOPSIS
null
metaonly config HeapMin.align // instance
index URL

Alignment of the buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMin.Params;
...
params.align = SizeT undefined;
DETAILS
In the static HeapMin.create() call, the buffer allocated for the HeapMin instance will have the alignment specified by this parameter on targets that support static alignment.
In the dynamic case, the client must supply the buffer, so it is the client's responsibility to manage the buffer's alignment, and there is no 'align' parameter.
The specified align parameter must be a power of 2.
The default alignment of zero causes the buffer to get aligned using Memory.getMaxDefaultTypeAlignMeta().
metaonly config HeapMin.sectionName // instance
index URL

Section name of the heap

XDCscript usage meta-domain
var params = new HeapMin.Params;
...
params.sectionName = String null;
DETAILS
When creating heaps during configuration, this parameter specifies where the heap's buffer will be placed. This parameter is passed as the section name in the Memory.staticPlace function.
SEE
Memory.staticPlace
Instance Creation
index URL

XDCscript usage meta-domain
var params = new HeapMin.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMin.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This heap is a growth-only heap that is intended to be used by systems that never delete objects or free memory. Objects can be created at runtime based on values determined at runtime, but objects can not be deleted.
SEE
HeapMin.Params
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.HeapStd
index URL

Malloc/free based heap implementation

  • C synopsis
  • Individual elements
  • DETAILS
  • CONSTRAINTS
  • XDCscript usage
  • Individual elements
This heap is based on the ANSI C Standard Library functions malloc() and free() and assumes that these functions are thread-safe. Please refer to the target specific documentation of the ANSI C Standard Library for details. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/HeapStd.xdc
#include <xdc/runtime/HeapStd.h>
Functions
Void | HeapStd_construct// Initialize a new instance object inside the provided structure(HeapStd_Struct *structP, const HeapStd_Params *params, Error_Block *eb);
HeapStd_Handle | HeapStd_create// Allocate and initialize a new instance object and return its handle(const HeapStd_Params *params, Error_Block *eb);
Void | HeapStd_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapStd_Handle *handleP);
Void | HeapStd_destruct// Finalize the instance object inside the provided structure(HeapStd_Struct *structP);
Void | HeapStd_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapStd_Params *params);
Functions common to all IHeap modules
Ptr | HeapStd_alloc// Allocates a block of memory from the heap(HeapStd_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void | HeapStd_free// Free a block of memory back to the heap(HeapStd_Handle handle, Ptr block, SizeT size);
Void | HeapStd_getStats// Retrieve the statistics from the heap(HeapStd_Handle handle, Memory_Stats *stats);
Bool | HeapStd_isBlocking// Returns whether the heap may block during an HeapStd_alloc() or HeapStd_free()(HeapStd_Handle handle);
Functions common to all target instances
 | HeapStd_handle// Convert this instance structure pointer into an instance handle, HeapStd_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapStd_Handle_label// The label associated with this instance object, HeapStd_Handle_name// The name of this instance object, HeapStd_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapStd_Object_count// The number of statically-created instance objects, HeapStd_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapStd_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapStd_Object_heap// The heap used to allocate dynamically-created instance objects, HeapStd_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapStd_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | HeapStd_Module_getMask// Returns the diagnostics mask for this module, HeapStd_Module_hasMask// Test whether this module has a diagnostics mask, HeapStd_Module_heap// The heap from which this module allocates memory, HeapStd_Module_id// Get this module's unique id, HeapStd_Module_setMask// Set the diagnostics mask for this module, HeapStd_Module_startupDone// Test if this module has completed startup
Typedefs
typedef HeapStd_Object * | HeapStd_Handle// Client reference to an instance object;
typedef struct | HeapStd_Object// Opaque internal representation of an instance object HeapStd_Object;
typedef struct | HeapStd_Params// Instance config-params structure ...
typedef struct | HeapStd_Struct// Opaque client structure large enough to hold an instance object HeapStd_Struct;
Constants
extern const Assert_Id | HeapStd_A_invalidAlignment// Assert that the alignment argument in alloc is valid;
extern const Assert_Id | HeapStd_A_invalidTotalFreeSize// Assert that remaining size is less than or equal to starting size;
extern const Assert_Id | HeapStd_A_zeroSize// Assert that the size is non-zero on the create;
extern const Error_Id | HeapStd_E_noRTSMemory// Error raised if all the RTS heap is used up;
DETAILS
This heap is based on the ANSI C Standard Library functions malloc() and free() and assumes that these functions are thread-safe. Please refer to the target specific documentation of the ANSI C Standard Library for details.
The largest free block that can be returned form malloc() cannot be determined. Therefore, the property largestFreeSize in Memory.Stats returned from getStats() always returns 0.
CONSTRAINTS
The alloc() function only supports alignment requests up to value returned from Memory.getMaxDefaultTypeAlign().
config HeapStd_A_invalidAlignment // module-wide
index URL

Assert that the alignment argument in alloc is valid

C synopsis target-domain
extern const Assert_Id HeapStd_A_invalidAlignment;
DETAILS
If this assertion is raised, it means that the requested alignment is greater than the maximum alignment allowed on the target.
config HeapStd_A_invalidTotalFreeSize // module-wide
index URL

Assert that remaining size is less than or equal to starting size

C synopsis target-domain
extern const Assert_Id HeapStd_A_invalidTotalFreeSize;
DETAILS
If this assertion is raised, it means that either incorrect sizes were passed to free or multiple calls to free were made with the same buffer.
config HeapStd_A_zeroSize // module-wide
index URL

Assert that the size is non-zero on the create

C synopsis target-domain
extern const Assert_Id HeapStd_A_zeroSize;
config HeapStd_E_noRTSMemory // module-wide
index URL

Error raised if all the RTS heap is used up

C synopsis target-domain
extern const Error_Id HeapStd_E_noRTSMemory;
DETAILS
The total size of all HeapStd instance allocations added together cannot exceed the malloc/free heap size determined by xdc.cfg.Program.heap.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId HeapStd_Module_id();
// Get this module's unique id
Bool HeapStd_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle HeapStd_Module_heap();
// The heap from which this module allocates memory
Bool HeapStd_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapStd_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapStd_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct HeapStd_Object HeapStd_Object;
// Opaque internal representation of an instance object
typedef HeapStd_Object *HeapStd_Handle;
// Client reference to an instance object
typedef struct HeapStd_Struct HeapStd_Struct;
// Opaque client structure large enough to hold an instance object
HeapStd_Handle HeapStd_handle(HeapStd_Struct *structP);
// Convert this instance structure pointer into an instance handle
HeapStd_Struct *HeapStd_struct(HeapStd_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct HeapStd_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     Memory_Size size;
    // Size (in MAUs) of the heap
} HeapStd_Params;
Void HeapStd_Params_init(HeapStd_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapStd_size // instance
index URL

Size (in MAUs) of the heap

C synopsis target-domain
struct HeapStd_Params {
     ...
     Memory_Size size;
DETAILS
This parameter specifies the size of the heap managed by a HeapStd instance. HeapStd is built upon the ANSI C Standard Library functions malloc() and free().
The total size of all HeapStd instance allocations added together cannot exceed the malloc/free heap size determined by Program.heap.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an assert for the runtime create.
Instance Creation
index URL

C synopsis target-domain
HeapStd_Handle HeapStd_create(const HeapStd_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void HeapStd_construct(HeapStd_Struct *structP, const HeapStd_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This heap uses the ANSI C Standard Library functions malloc() and free() to manage memory and assumes that these functions are thread-safe.
SEE
HeapStd.Params
Instance Deletion
index URL

C synopsis target-domain
Void HeapStd_delete(HeapStd_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void HeapStd_destruct(HeapStd_Struct *structP);
// Finalize the instance object inside the provided structure
HeapStd_alloc() // instance
index URL

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapStd_alloc(HeapStd_Handle handle, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created HeapStd instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
RETURNS
Returns the address of the allocated memory.
CONSTRAINTS
The only alignment currently supported is the default alignment returned by the underlying malloc() implementation. The align value must be less than or equal to the value returned from Memory.getMaxDefaultTypeAlign().
SEE
IHeap.alloc
HeapStd_free() // instance
index URL

Free a block of memory back to the heap

C synopsis target-domain
Void HeapStd_free(HeapStd_Handle handle, Ptr block, SizeT size);
ARGUMENTS
handle — handle of a previously-created HeapStd instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
HeapStd_getStats() // instance
index URL

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapStd_getStats(HeapStd_Handle handle, Memory_Stats *stats);
ARGUMENTS
handle — handle of a previously-created HeapStd instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
HeapStd_isBlocking() // instance
index URL

Returns whether the heap may block during an HeapStd_alloc() or HeapStd_free()

C synopsis target-domain
Bool HeapStd_isBlocking(HeapStd_Handle handle);
ARGUMENTS
handle — handle of a previously-created HeapStd instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
Since the implementation of the underlaying ANSI C Standard Library is not known, this function always returns the more restrictive case which is TRUE.
Instance Convertors
index URL

C synopsis target-domain
IHeap_Handle HeapStd_Handle_upCast(HeapStd_Handle handle);
// unconditionally move one level up the inheritance hierarchy
HeapStd_Handle HeapStd_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int HeapStd_Object_count();
// The number of statically-created instance objects
HeapStd_Handle HeapStd_Object_get(HeapStd_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
HeapStd_Handle HeapStd_Object_first();
// The handle of the first dynamically-created instance object, or NULL
HeapStd_Handle HeapStd_Object_next(HeapStd_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle HeapStd_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *HeapStd_Handle_label(HeapStd_Handle handle, Types_Label *buf);
// The label associated with this instance object
String HeapStd_Handle_name(HeapStd_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/HeapStd.xdc
var HeapStd = xdc.useModule('xdc.runtime.HeapStd');
module-wide config parameters
     HeapStd.A_invalidAlignment// Assert that the alignment argument in alloc is valid = Assert.Desc {
        msg: "HeapStd_alloc - requested alignment is greater than allowed"
    };
     HeapStd.A_invalidTotalFreeSize// Assert that remaining size is less than or equal to starting size = Assert.Desc {
        msg: "HeapStd instance totalFreeSize is greater than starting size"
    };
     HeapStd.A_zeroSize// Assert that the size is non-zero on the create = Assert.Desc {
        msg: "HeapStd_create cannot have a zero size value"
    };
     HeapStd.E_noRTSMemory// Error raised if all the RTS heap is used up = Error.Desc {
        msg: "The RTS heap is used up. Examine Program.heap."
    };
     HeapStd.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new HeapStd.Params// Instance config-params object;
        params.size// Size (in MAUs) of the heap = UArg 0;
per-instance creation
    var inst = HeapStd.create// Create an instance-object(params);
config HeapStd.A_invalidAlignment // module-wide
index URL

Assert that the alignment argument in alloc is valid

XDCscript usage meta-domain
HeapStd.A_invalidAlignment = Assert.Desc {
    msg: "HeapStd_alloc - requested alignment is greater than allowed"
};
DETAILS
If this assertion is raised, it means that the requested alignment is greater than the maximum alignment allowed on the target.
C SYNOPSIS
HeapStd_A_invalidAlignment
config HeapStd.A_invalidTotalFreeSize // module-wide
index URL

Assert that remaining size is less than or equal to starting size

XDCscript usage meta-domain
HeapStd.A_invalidTotalFreeSize = Assert.Desc {
    msg: "HeapStd instance totalFreeSize is greater than starting size"
};
DETAILS
If this assertion is raised, it means that either incorrect sizes were passed to free or multiple calls to free were made with the same buffer.
C SYNOPSIS
HeapStd_A_invalidTotalFreeSize
config HeapStd.A_zeroSize // module-wide
index URL

Assert that the size is non-zero on the create

XDCscript usage meta-domain
HeapStd.A_zeroSize = Assert.Desc {
    msg: "HeapStd_create cannot have a zero size value"
};
C SYNOPSIS
HeapStd_A_zeroSize
config HeapStd.E_noRTSMemory // module-wide
index URL

Error raised if all the RTS heap is used up

XDCscript usage meta-domain
HeapStd.E_noRTSMemory = Error.Desc {
    msg: "The RTS heap is used up. Examine Program.heap."
};
DETAILS
The total size of all HeapStd instance allocations added together cannot exceed the malloc/free heap size determined by xdc.cfg.Program.heap.
C SYNOPSIS
HeapStd_E_noRTSMemory
metaonly config HeapStd.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
HeapStd.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new HeapStd.Params;
// Instance config-params object
    params.size = UArg 0;
    // Size (in MAUs) of the heap
config HeapStd.size // instance
index URL

Size (in MAUs) of the heap

XDCscript usage meta-domain
var params = new HeapStd.Params;
...
params.size = UArg 0;
DETAILS
This parameter specifies the size of the heap managed by a HeapStd instance. HeapStd is built upon the ANSI C Standard Library functions malloc() and free().
The total size of all HeapStd instance allocations added together cannot exceed the malloc/free heap size determined by Program.heap.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an assert for the runtime create.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new HeapStd.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapStd.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This heap uses the ANSI C Standard Library functions malloc() and free() to manage memory and assumes that these functions are thread-safe.
SEE
HeapStd.Params
generated on Fri, 17 Jun 2011 00:24:32 GMT


interface xdc.runtime.IFilterLogger
index URL

Interface for supporting filtering of Log events by detail level

  • C synopsis
  • Individual elements
Filtering of events based on detail level is not inherently supported by the Log APIs as is filtering of events based on the diagnostics mask. [ more ... ]
XDCspec summary sourced in xdc/runtime/IFilterLogger.xdc
interface IFilterLogger { ...
// inherits xdc.runtime.ILogger
    // inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
package xdc.runtime;
interface IFilterLogger inherits ILogger {
module-wide config parameters
    config Bool filterByLevel// Support filtering of events by event level = false;
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    metaonly function getMetaArgs// Returns any meta data needed to support RTA(inst, instNum);
instance:
per-instance functions
    Bool disable// Disable a log();
    Bool enable// Enable a log();
     Diags.Mask getFilterLevel// Returns the mask of diags categories currently set to the specified level(Diags.EventLevel level);
    Void setFilterLevel// Set the level of detail that instances will log(Diags.Mask mask, Diags.EventLevel filterLevel);
    Void write0// Process a log event with 0 arguments(Log.Event evt, Types.ModuleId mid);
    Void write1// Process a log event with 1 arguments(Log.Event evt, Types.ModuleId mid, IArg a1);
    Void write2// Process a log event with 2 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
    Void write4// Process a log event with up to 4 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
    Void write8// Process a log event with up to 8 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
}
DETAILS
Filtering of events based on detail level is not inherently supported by the Log APIs as is filtering of events based on the diagnostics mask.
Support for this type of filtering must be done by an ILogger implementation. Not all users are interested in this filtering support, however, so it is not required of all ILogger implementations.
ILoggers that do intend to support filtering by detail level should implement this interface, which extends the ILogger interface.
The setFilterLevel and getFilterLevel functions support runtime specification of a different filtering level for each of the diagnostics categories.
config IFilterLogger.filterByLevel // module-wide
index URL

Support filtering of events by event level

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
config Bool filterByLevel = false;
DETAILS
To improve logging performance, this feature can be disabled by setting filterByLevel to false.
See 'setFilterLevel' for an explanation of level filtering.
metaonly config IFilterLogger.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly IFilterLogger.getMetaArgs() // module-wide
index URL

Returns any meta data needed to support RTA

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
metaonly function getMetaArgs(inst, instNum);
DETAILS
This meta data should be returned in the form of a structure which can be converted into XML. This data is added to the RTA XML file during the application's configuration, and can be accessed later through the xdc.rta.MetaData module.
The MetaData is returned per instance of the ILogger module. The instance object is passed to the function as the first argument.
The second argument is the index of the instance in the list of the ILogger's static instances.
IFilterLogger.disable() // instance
index URL

Disable a log

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Bool disable();
DETAILS
Events written to a disabled log are silently discarded.
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
IFilterLogger.enable() // instance
index URL

Enable a log

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Bool enable();
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
IFilterLogger.getFilterLevel() // instance
index URL

Returns the mask of diags categories currently set to the specified level

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Diags.Mask getFilterLevel(Diags.EventLevel level);
DETAILS
See 'setFilterLevel' for an explanation of level filtering.
IFilterLogger.setFilterLevel() // instance
index URL

Set the level of detail that instances will log

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void setFilterLevel(Diags.Mask mask, Diags.EventLevel filterLevel);
ARGUMENTS
mask — The diags categories to set the level for
filterLevel — The new filtering level for the specified categories
DETAILS
Events with the specified level or higher will be logged, events below the specified level will be dropped.
Events are filtered first by diags category, then by level. If an event's diags category is disabled in the module's diags mask, then it will be filtered out regardless of level. The event will not even be passed to the logger.
This API allows for setting the filtering level for more than one diags category at a time. The mask parameter can be a single category or multiple categories combined, and the level will be set for all of those categories.
IFilterLogger.write0() // instance
index URL

Process a log event with 0 arguments

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void write0(Log.Event evt, Types.ModuleId mid);
DETAILS
Same as write4 except with 0 arguments rather than 4.
SEE
ILogger.write4()
IFilterLogger.write1() // instance
index URL

Process a log event with 1 arguments

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void write1(Log.Event evt, Types.ModuleId mid, IArg a1);
DETAILS
Same as write4 except with 1 arguments rather than 4.
SEE
ILogger.write4()
IFilterLogger.write2() // instance
index URL

Process a log event with 2 arguments

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void write2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
DETAILS
Same as write4 except with 2 arguments rather than 4.
SEE
ILogger.write4()
IFilterLogger.write4() // instance
index URL

Process a log event with up to 4 arguments

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void write4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
ARGUMENTS
evt — event to be logged
mid — module ID of the module which logged the event
a1 — arbitrary argument passed by caller
DETAILS
The evt argument is of type Log.Event, which encodes the Log.EventId, the Diags.Mask, and the Diags.EventLevel of the event. The event ID can be obtained via Types.getEventId(evt), the Diags mask can be obtained via Diags.getMask(evt), and the event level can be obtained via Diags.getLevel(evt).
The modId argument is the module ID of the module that logged the event.
The event information can be used by the logger to handle different events specially. For example, the event ID can be used to compare against other known Log.Events.
      if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
          :
      }
The Diags mask and event level can be used for filtering of events based on event level (see IFilterLogger), or even routing events to separate loggers based on diags category (see, for example, LoggerBuf.statusLogger).
The Diags mask and event level are useful for handling the event, but are generally not recorded by the logger because they are not needed in decoding and displaying the event. A more suitable value to record is a Types.Event, which encodes the event ID and module ID. For example, the Log.EventRec type stores a Types.Event in its record definition. A Types.Event can be created using the Types.makeEvent API given the event ID and module ID.
The event ID value of 0 is used to indicate an event triggered by a call to one of the Log_print[0-6] methods. These methods take a format string rather than a Log_Event argument and, as a result, the event ID encoded in evt is 0 and the parameter a1 is the format string.
Non-zero event IDs can also be used to access the msg string associated with the Log.EventDesc that originally defined the Log event.
      Log_EventId id = Log_getEventId(evt));
      if (id != 0) {
          String msg = Text_ropeText(id);
          System_aprintf(msg, a1, a2, a3, a4);
      }
This works because an event's ID is simply an offset into a table of characters (maintained by the Text module) containing the event's msg string.
The arguments a1, a2, etc. are parameters that are to be interpreted according to the message format string associated with evt.
SEE
Log.Event, Log.EventDesc, Text.ropeText, Log.getEventId
IFilterLogger.write8() // instance
index URL

Process a log event with up to 8 arguments

XDCspec declarations sourced in xdc/runtime/IFilterLogger.xdc
Void write8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
DETAILS
Same as write4 except with 8 arguments rather than 4.
SEE
ILogger.write4()
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.IGateProvider
index URL

Interface implemented by all gate providers

  • C synopsis
  • Individual elements
  • DETAILS
  • NOTES
Gates are used within the xdc.runtime package to serialize access to data structures that are used by more than one thread. [ more ... ]
XDCspec summary sourced in xdc/runtime/IGateProvider.xdc
interface IGateProvider { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
package xdc.runtime;
interface IGateProvider {
module-wide constants & types
    const Int Q_BLOCKING// Blocking quality = 1;
    const Int Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bool query// Runtime test for a particular gate quality(Int qual);
    metaonly Bool queryMeta// Configuration time test for a particular gate quality(Int qual);
instance:
per-instance creation
     create// Create an instance-object();
per-instance functions
    IArg enter// Enter this gate();
    Void leave// Leave this gate(IArg key);
}
DETAILS
Gates are used within the xdc.runtime package to serialize access to data structures that are used by more than one thread.
Gates are responsible for ensuring that only one out of multiple threads can access a data structure at a time. There are important scheduling latency and performance considerations that affect the "type" of gate used to protect each data structure. For example, the best way to protect a shared counter is to simply disable all interrupts before the update and restore the interrupt state after the update; disabling all interrupts prevents all thread switching, so the update is guaranteed to be "atomic". Although highly efficient, this method of creating atomic sections causes serious system latencies when the time required to update the data structure can't be bounded.
For example, a memory manager's list of free blocks can grow indefinitely long during periods of high fragmentation. Searching such a list with interrupts disabled would cause system latencies to also become unbounded. In this case, the best solution is to provide a gate that suspends the execution of threads that try to enter a gate that has already been entered; i.e., the gate "blocks" the thread until the thread already in the gate leaves. The time required to enter and leave the gate is greater than simply enabling and restoring interrupts, but since the time spent within the gate is relatively large, the overhead caused by entering and leaving gates will not become a significant percentage of overall system time. More importantly, threads that do not need to access the shared data structure are completely unaffected by threads that do access it.
NOTES
Modules inheriting this interface should treat all names beginning with Q_ as reserved words, i.e. the names from that namespace should not be used. This will allow future version of this interface to define new constants ("qualities") similar to Q_BLOCKING and Q_PREEMPTING without breaking any existing modules.
const IGateProvider.Q_BLOCKING
index URL

Blocking quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
const Int Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const IGateProvider.Q_PREEMPTING
index URL

Preempting quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
const Int Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
metaonly config IGateProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
IGateProvider.query() // module-wide
index URL

Runtime test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
Bool query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
metaonly IGateProvider.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
metaonly Bool queryMeta(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
create();
// Create an instance-object
IGateProvider.enter() // instance
index URL

Enter this gate

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
IArg enter();
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
IGateProvider.leave() // instance
index URL

Leave this gate

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
Void leave(IArg key);
ARGUMENTS
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.IHeap
index URL

Interface to heap functions

  • C synopsis
  • Individual elements
All heap implementations inherit from this interface. The implementations can have additional configuration parmeters and functions.
XDCspec summary sourced in xdc/runtime/IHeap.xdc
interface IHeap { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/IHeap.xdc
package xdc.runtime;
interface IHeap {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
instance:
per-instance creation
     create// Create an instance-object();
per-instance functions
    Ptr alloc// Allocates a block of memory from the heap(SizeT size, SizeT align, Error.Block *eb);
    Void free// Free a block of memory back to the heap(Ptr block, SizeT size);
    Void getStats// Retrieve the statistics from the heap(Memory.Stats *stats);
    Bool isBlocking// Returns whether the heap may block during an alloc() or free()();
}
metaonly config IHeap.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
create();
// Create an instance-object
DETAILS
See specific IHeap implementation for parameters used.
IHeap.alloc() // instance
index URL

Allocates a block of memory from the heap

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
ARGUMENTS
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
RETURNS
Returns the address of the allocated memory.
IHeap.free() // instance
index URL

Free a block of memory back to the heap

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
Void free(Ptr block, SizeT size);
ARGUMENTS
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
IHeap.getStats() // instance
index URL

Retrieve the statistics from the heap

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
Void getStats(Memory.Stats *stats);
ARGUMENTS
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
IHeap.isBlocking() // instance
index URL

Returns whether the heap may block during an alloc() or free()

XDCspec declarations sourced in xdc/runtime/IHeap.xdc
Bool isBlocking();
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.IInstance
index URL

Common instance params

  • C synopsis
  • Individual elements
Every module's instance parameter structure contains a pointer to an IInstance.Params structure named instance. So, every instance parameter defined in this interface may optionally be set when creating (or constructing) any module's instances.
XDCspec summary sourced in xdc/runtime/IInstance.xdc
interface IInstance { ...
instance: ...
XDCspec declarations sourced in xdc/runtime/IInstance.xdc
package xdc.runtime;
interface IInstance {
instance:
per-instance config parameters
    config String name// Name of the instance = null;
}
config IInstance.name // instance
index URL

Name of the instance

XDCspec declarations sourced in xdc/runtime/IInstance.xdc
config String name = null;
DETAILS
It is possible to "bind" a name to each instance of any module at the time the instance is created (or constructed).
      ModA_Params params;
      ModA_Params_init(&params);
      params.instance->name = "myInstance";
      ModA_create(&params, NULL);
The name field must be assigned a pointer to a buffer that persists as long as the instance that it names exists. Only a reference to the name is retained in the instance, the name is not copied to a secondary buffer.
The configuration parameters that controls if instance names are supported is common$.namedInstance. The parameter is a member of the structure common$, available in each module. By default, this parameter is set to false, which disables support for instance names. Therefore, to enable instance names for a given module Mod, configure the module as follows in your configuration script:
      var Mod = xdc.useModule('pkg.Mod');
      ModA.common$.namedInstance = true;
Here is how the static instances are given names at the configuration time:
      var inst = Mod.create();
      inst.instance.name = "myInstance";
At runtime, assign your instance a name:
      #include <package/name/Mod.h>
      Mod_Params params;
      Mod_Params_init(&params);
      params.instance->name = "myInstance";
      Mod_create(&params, NULL);
If instances have been configured to not support names, it is still possible to assign to the instance.name field of the parameter structure (as shown above). However, the pointer is not retained and methods that normally return an instance's name will return NULL instead.
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.ILogger
index URL

Interface to service Log events

  • C synopsis
  • Individual elements
A logger is responsible for recording, transmitting, or otherwise handling Log Events generated by clients of the Log module. The Log module uses modules that implement the ILogger interface to record the log events. Most application code will use the Log module instead of directly calling the specific ILogger module implementation. [ more ... ]
XDCspec summary sourced in xdc/runtime/ILogger.xdc
interface ILogger { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/ILogger.xdc
package xdc.runtime;
interface ILogger {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    metaonly function getMetaArgs// Returns any meta data needed to support RTA(inst, instNum);
instance:
per-instance functions
    Bool disable// Disable a log();
    Bool enable// Enable a log();
    Void write0// Process a log event with 0 arguments(Log.Event evt, Types.ModuleId mid);
    Void write1// Process a log event with 1 arguments(Log.Event evt, Types.ModuleId mid, IArg a1);
    Void write2// Process a log event with 2 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
    Void write4// Process a log event with up to 4 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
    Void write8// Process a log event with up to 8 arguments(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
}
DETAILS
A logger is responsible for recording, transmitting, or otherwise handling Log Events generated by clients of the Log module. The Log module uses modules that implement the ILogger interface to record the log events. Most application code will use the Log module instead of directly calling the specific ILogger module implementation.
All logger implementations must inherit from this interface. The derived implementations must implement the functions defined in this interface but may also add additional configuration parameters and functions.
Events may be defined with a detail level, but the Log interface does not inherently provide support for filtering of events based on detail level. Instead, this is left to the ILogger implementation. ILogger implementations which wish to support filtering based on detail level should implement the IFilterLogger interface, which extends the ILogger interface to include APIs for getting and setting the current filter level.
metaonly config ILogger.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly ILogger.getMetaArgs() // module-wide
index URL

Returns any meta data needed to support RTA

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
metaonly function getMetaArgs(inst, instNum);
DETAILS
This meta data should be returned in the form of a structure which can be converted into XML. This data is added to the RTA XML file during the application's configuration, and can be accessed later through the xdc.rta.MetaData module.
The MetaData is returned per instance of the ILogger module. The instance object is passed to the function as the first argument.
The second argument is the index of the instance in the list of the ILogger's static instances.
ILogger.disable() // instance
index URL

Disable a log

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Bool disable();
DETAILS
Events written to a disabled log are silently discarded.
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
ILogger.enable() // instance
index URL

Enable a log

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Bool enable();
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
ILogger.write0() // instance
index URL

Process a log event with 0 arguments

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Void write0(Log.Event evt, Types.ModuleId mid);
DETAILS
Same as write4 except with 0 arguments rather than 4.
SEE
ILogger.write4()
ILogger.write1() // instance
index URL

Process a log event with 1 arguments

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Void write1(Log.Event evt, Types.ModuleId mid, IArg a1);
DETAILS
Same as write4 except with 1 arguments rather than 4.
SEE
ILogger.write4()
ILogger.write2() // instance
index URL

Process a log event with 2 arguments

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Void write2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
DETAILS
Same as write4 except with 2 arguments rather than 4.
SEE
ILogger.write4()
ILogger.write4() // instance
index URL

Process a log event with up to 4 arguments

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Void write4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
ARGUMENTS
evt — event to be logged
mid — module ID of the module which logged the event
a1 — arbitrary argument passed by caller
DETAILS
The evt argument is of type Log.Event, which encodes the Log.EventId, the Diags.Mask, and the Diags.EventLevel of the event. The event ID can be obtained via Types.getEventId(evt), the Diags mask can be obtained via Diags.getMask(evt), and the event level can be obtained via Diags.getLevel(evt).
The modId argument is the module ID of the module that logged the event.
The event information can be used by the logger to handle different events specially. For example, the event ID can be used to compare against other known Log.Events.
      if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
          :
      }
The Diags mask and event level can be used for filtering of events based on event level (see IFilterLogger), or even routing events to separate loggers based on diags category (see, for example, LoggerBuf.statusLogger).
The Diags mask and event level are useful for handling the event, but are generally not recorded by the logger because they are not needed in decoding and displaying the event. A more suitable value to record is a Types.Event, which encodes the event ID and module ID. For example, the Log.EventRec type stores a Types.Event in its record definition. A Types.Event can be created using the Types.makeEvent API given the event ID and module ID.
The event ID value of 0 is used to indicate an event triggered by a call to one of the Log_print[0-6] methods. These methods take a format string rather than a Log_Event argument and, as a result, the event ID encoded in evt is 0 and the parameter a1 is the format string.
Non-zero event IDs can also be used to access the msg string associated with the Log.EventDesc that originally defined the Log event.
      Log_EventId id = Log_getEventId(evt));
      if (id != 0) {
          String msg = Text_ropeText(id);
          System_aprintf(msg, a1, a2, a3, a4);
      }
This works because an event's ID is simply an offset into a table of characters (maintained by the Text module) containing the event's msg string.
The arguments a1, a2, etc. are parameters that are to be interpreted according to the message format string associated with evt.
SEE
Log.Event, Log.EventDesc, Text.ropeText, Log.getEventId
ILogger.write8() // instance
index URL

Process a log event with up to 8 arguments

XDCspec declarations sourced in xdc/runtime/ILogger.xdc
Void write8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
DETAILS
Same as write4 except with 8 arguments rather than 4.
SEE
ILogger.write4()
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.IModule
index URL

Base interface for all modules

  • DETAILS
  • INTERNAL
  • EXTERNAL
All modules share a common set of configuration parameters and methods. [ more ... ]
XDCspec summary sourced in xdc/runtime/IModule.xdc
interface IModule { ...
XDCspec declarations sourced in xdc/runtime/IModule.xdc
package xdc.runtime;
interface IModule {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
}
DETAILS
All modules share a common set of configuration parameters and methods.
INTERNAL
This section provides a terse summary of the methods provided by every module for use within the module's implementation. Each method's prototype is shown along with a brief summary of its behavior. These methods are declared in the module's internal header which should always be included in any file referencing these functions. For a module named Mod the following statement includes this header.
      #include "package/internal/Mod.xdc.h"
In the protypes below, Mod refers to the module being implemented, embeddedObj is the name of field in the module's state structure that is either an embedded object field or an array of such objects, and fld is the name of a field declared in the module's state structure.
  // enter the module's gate
  IArg Mod_Module_enter(Gate_Handle gate);

  // leave the module's gate
  Mod_Module_leave(Gate_Handle, IArg);

  // return a pointer to the embeddedObj field
  Ptr Mod_Module_State_embeddedObj();

  // the value of the fld field of the module's state structure
  Mod_module->fld;    // fld is declared in module's .xdc file
EXTERNAL
This section provides a terse summary of the methods provided by every module for use by an application or other modules. Each method's prototype is shown along with a brief summary of its behavior. These methods are declared in the module's header which should always be included in any file referencing these functions. For a module named Mod in the package named a.b.c, the following statement includes this header.
      #include <a/b/c/Mod.h>
In the protypes below, IMod referes to some interface, Mod refers to a module that (optionally) inherits from IMod, and pkgName is the name of the package containing the interface IMod.
  // methods to operate on modules

      // return heap associated with this module
      IHeap_Handle Mod_Module_heap();

      // get Mod's module ID
      Types_ModuleId Mod_Module_id();

      // return TRUE if Mod's startup is complete
      Bool Mod_Module_startupDone();

      // type-safe conversion from an interface to an inheriting module
      // Returns NULL if the conversion is not valid
      Mod_Handle Mod_Handle_downCast(IMod_Handle handle);

      // type-safe conversion from a module to an interface it inherits from
      // Returns NULL if the conversion is not valid
      IMod_Handle Mod_Handle_upCast(Mod_Module_Handle handle);

  // methods to access the instances managed by Mod

      // return heap used to create instances
      IHeap_Handle Mod_Object_heap();

      // return count of static instances
      Int Mod_Object_count();

      // get the i'th instance object of an array of instance objects
      //
      // If the array reference is NULL, get the i'th statically created
      // instance object.
      Mod_Object *Mod_Object_get(Mod_Object *array, Int i);

      // get the first "live" runtime instance
      Mod_Object *Mod_Object_first();

      // get the next "live" runtime instance
      Mod_Object *Mod_Object_next(Mod_Object *obj);

  // methods that operate on instance handles

      // fill in buf structure with instance's label info, returns buf
      Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);

      // returns name of the instance inst, if it has one (otherwise NULL)
      String Mod_Handle_name(Mod_Handle inst);

      // type-safe conversion of module handle to interface handle
      // Returns NULL if the conversion is not valid
      IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);

      // type-safe conversion of interface handle to module handle
      // Returns NULL if the conversion is not valid
      Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);

      // get the module that created the handle
      Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
metaonly config IModule.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/IModule.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.ISystemSupport
index URL

Interface to core system functions

Each embedded system requires implementations of these functions but the behavior of these functions varies depending on the context of the embedded system. For example, some systems will implement exit() as an infinite loop because the executable is designed to *never* exit.
XDCspec summary sourced in xdc/runtime/ISystemSupport.xdc
interface ISystemSupport { ...
// inherits xdc.runtime.IModule
XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
package xdc.runtime;
interface ISystemSupport {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void abort// Backend for System.abort()(String str);
    Void exit// Backend for System.exit()(Int stat);
    Void flush// Backend for System.flush()();
    Void putch// Backend for System.printf() and System.putch()(Char ch);
    Bool ready// Test if character output can proceed();
}
metaonly config ISystemSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ISystemSupport.abort() // module-wide
index URL

Backend for System.abort()

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
Void abort(String str);
ARGUMENTS
str — message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
DETAILS
This function is called by System.abort() prior to calling the ANSI C Standard library function abort(). So, to ensure the abort processing of the system's ANSI C Standard library completes, this function should return to its caller.
ISystemSupport.exit() // module-wide
index URL

Backend for System.exit()

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
Void exit(Int stat);
ARGUMENTS
stat — status value passed to all "atexit" handlers
This value is passed to all "atexit" handles bound via System.atexit(). If the application exits via the ANSI C Standard exit() function rather than via System_exit(), stat will be equal to System.STATUS_UNKNOWN.
DETAILS
This function is called as part the normal "atexit" processing performed by the ANSI C Standard Library's exit() function; System.exit() directly calls ANSI exit().
This function is called after all "atexit" handlers bound via System.atexit() are run and it is always called while "inside" the the System gate.
To ensure that all exit processing of the system's ANSI C Standard Library completes, this function should return to its caller. Exit handlers bound using the ANSI C Standard Library atexit() function may run before or after this function.
SEE
System.atexit
ISystemSupport.flush() // module-wide
index URL

Backend for System.flush()

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
Void flush();
DETAILS
This function is simply called by System_flush to output any characters buffered by the underlying SystemSupport module to an output device.
ISystemSupport.putch() // module-wide
index URL

Backend for System.printf() and System.putch()

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
Void putch(Char ch);
ARGUMENTS
ch — character to output
DETAILS
Output a single character. This function is called by System_printf() to write each character of formated output specified by its arguments.
ISystemSupport.ready() // module-wide
index URL

Test if character output can proceed

XDCspec declarations sourced in xdc/runtime/ISystemSupport.xdc
Bool ready();
DETAILS
This function is called by System prior to performing any character output. If this function returns FALSE, the System functions that would normally call putch() simply return (with an appropriate error status) without ever calling putch.
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.ITimestampClient
index URL

Timestamp Client Interface

This interface defines the methods used by client applications to get timestamp values. It is implemented by the Timestamp module.
XDCspec summary sourced in xdc/runtime/ITimestampClient.xdc
interface ITimestampClient { ...
// inherits xdc.runtime.IModule
XDCspec declarations sourced in xdc/runtime/ITimestampClient.xdc
package xdc.runtime;
interface ITimestampClient {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bits32 get32// Return a 32-bit timestamp();
    Void get64// Return a 64-bit timestamp(Types.Timestamp64 *result);
    Void getFreq// Get the timestamp timer's frequency (in Hz)(Types.FreqHz *freq);
}
metaonly config ITimestampClient.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/ITimestampClient.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ITimestampClient.get32() // module-wide
index URL

Return a 32-bit timestamp

XDCspec declarations sourced in xdc/runtime/ITimestampClient.xdc
Bits32 get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
ITimestampClient.get64() // module-wide
index URL

Return a 64-bit timestamp

XDCspec declarations sourced in xdc/runtime/ITimestampClient.xdc
Void get64(Types.Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
ITimestampClient.getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

XDCspec declarations sourced in xdc/runtime/ITimestampClient.xdc
Void getFreq(Types.FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
generated on Fri, 17 Jun 2011 00:24:31 GMT


interface xdc.runtime.ITimestampProvider
index URL

Timestamp provider interface

This interface is implemented by platform-specific modules that "provide" underlying timestamp services for the xdc.runtime.Timestamp module. [ more ... ]
XDCspec summary sourced in xdc/runtime/ITimestampProvider.xdc
interface ITimestampProvider { ...
// inherits xdc.runtime.ITimestampClient
    // inherits xdc.runtime.IModule
XDCspec declarations sourced in xdc/runtime/ITimestampProvider.xdc
package xdc.runtime;
interface ITimestampProvider inherits ITimestampClient {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bits32 get32// Return a 32-bit timestamp();
    Void get64// Return a 64-bit timestamp(Types.Timestamp64 *result);
    Void getFreq// Get the timestamp timer's frequency (in Hz)(Types.FreqHz *freq);
}
DETAILS
This interface is implemented by platform-specific modules that "provide" underlying timestamp services for the xdc.runtime.Timestamp module.
Only the xdc.runtime.Timestamp module and the xdc.runtime.ITimestampClient interface should be directly referenced by platform-independent applications.
This interface is part of a design pattern that includes the ITimestampClient interface and the Timestamp module. This pattern allows client code to:
  • use the platform-independent interfaces provided by either ITimestampClient and Timestamp and remain 100% portable
  • optionally leverage platform-specific capabilities of any module that implements ITimestampProvider and still always have access to the platform-independent methods specified by ITimestampClient (because ITimestampProvider inherits from ITimestampClient)
This pattern is in contrast to other "provider" interfaces that exist only to specify the methods necessary to enable "higher-level" modules; client code *never* accesses these provider interfaces directly, clients always only use the higher-level modules.
metaonly config ITimestampProvider.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/ITimestampProvider.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ITimestampProvider.get32() // module-wide
index URL

Return a 32-bit timestamp

XDCspec declarations sourced in xdc/runtime/ITimestampProvider.xdc
Bits32 get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
ITimestampProvider.get64() // module-wide
index URL

Return a 64-bit timestamp

XDCspec declarations sourced in xdc/runtime/ITimestampProvider.xdc
Void get64(Types.Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
ITimestampProvider.getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

XDCspec declarations sourced in xdc/runtime/ITimestampProvider.xdc
Void getFreq(Types.FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
generated on Fri, 17 Jun 2011 00:24:31 GMT


module xdc.runtime.Log
index URL

Event logging manager

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
RTSC modules and the application code generate Log_Event events by calling the Log module's functions. The Log module then passes those events to an ILogger instance assigned to the event originating module, specified by that module's configuration parameter common$.logger. ILogger instances handle events, usually converting events to Log_EventRec records prior to recording, transmitting, or displaying them. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Log.xdc
#include <xdc/runtime/Log.h>
Functions
Void | Log_doPrint// Render an event as text via System_printf(Log_EventRec *evRec);
macro Void | Log_error0// Generate a Log "error event" with 0 arguments(String fmt);
macro Void | Log_error1// Generate a Log "error event" with 1 argument(String fmt, IArg a1);
macro Void | Log_error2// Generate a Log "error event" with 2 arguments(String fmt, IArg a1, IArg a2);
macro Void | Log_error3// Generate a Log "error event" with 3 arguments(String fmt, IArg a1, IArg a2, IArg a3);
macro Void | Log_error4// Generate a Log "error event" with 4 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_error5// Generate a Log "error event" with 5 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Log_EventId | Log_getEventId// Get event ID of the specified (encoded) event(Log_Event evt);
macro Diags_Mask | Log_getMask// Get the Diags mask for the specified (encoded) event(Log_Event evt);
macro Void | Log_info0// Generate a Log "info event" with 0 arguments(String fmt);
macro Void | Log_info1// Generate a Log "info event" with 1 argument(String fmt, IArg a1);
macro Void | Log_info2// Generate a Log "info event" with 2 arguments(String fmt, IArg a1, IArg a2);
macro Void | Log_info3// Generate a Log "info event" with 3 arguments(String fmt, IArg a1, IArg a2, IArg a3);
macro Void | Log_info4// Generate a Log "info event" with 4 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_info5// Generate a Log "info event" with 5 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void | Log_print0// Generate a Log "print event" with 0 arguments(Diags_Mask mask, String fmt);
macro Void | Log_print1// Generate a Log "print event" with 1 argument(Diags_Mask mask, String fmt, IArg a1);
macro Void | Log_print2// Generate a Log "print event" with 2 arguments(Diags_Mask mask, String fmt, IArg a1, IArg a2);
macro Void | Log_print3// Generate a Log "print event" with 3 arguments(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3);
macro Void | Log_print4// Generate a Log "print event" with 4 arguments(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_print5// Generate a Log "print event" with 5 arguments(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void | Log_print6// Generate a Log "print event" with 6 arguments(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
macro Void | Log_put0// Unconditionally put the specified Log event with 0 arguments(Log_Event evt, Types_ModuleId mid);
macro Void | Log_put1// Unconditionally put the specified Log event and 1 argument(Log_Event evt, Types_ModuleId mid, IArg a1);
macro Void | Log_put2// Unconditionally put the specified Log event and 2 arguments(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
macro Void | Log_put4// Unconditionally put the specified Log event(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_put8// Unconditionally put the specified Log event and 8 arguments(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
macro Void | Log_warning0// Generate a Log "warning event" with 0 arguments(String fmt);
macro Void | Log_warning1// Generate a Log "warning event" with 1 argument(String fmt, IArg a1);
macro Void | Log_warning2// Generate a Log "warning event" with 2 arguments(String fmt, IArg a1, IArg a2);
macro Void | Log_warning3// Generate a Log "warning event" with 3 arguments(String fmt, IArg a1, IArg a2, IArg a3);
macro Void | Log_warning4// Generate a Log "warning event" with 4 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_warning5// Generate a Log "warning event" with 5 arguments(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void | Log_write0// Generate a Log event with 0 arguments(Log_Event evt);
macro Void | Log_write1// Generate a Log event with 1 argument(Log_Event evt, IArg a1);
macro Void | Log_write2// Generate a Log event with 2 arguments(Log_Event evt, IArg a1, IArg a2);
macro Void | Log_write3// Generate a Log event with 3 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3);
macro Void | Log_write4// Generate a Log event with 4 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void | Log_write5// Generate a Log event with 5 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void | Log_write6// Generate a Log event with 6 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
macro Void | Log_write7// Generate a Log event with 7 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7);
macro Void | Log_write8// Generate a Log event with 8 arguments(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Functions common to all target modules
 | Log_Module_getMask// Returns the diagnostics mask for this module, Log_Module_hasMask// Test whether this module has a diagnostics mask, Log_Module_heap// The heap from which this module allocates memory, Log_Module_id// Get this module's unique id, Log_Module_setMask// Set the diagnostics mask for this module, Log_Module_startupDone// Test if this module has completed startup
Defines
#define | Log_NUMARGS// Maximum number of arguments supported in Log events (Int)8
#define | Log_PRINTFID// The EventId for Log_print() events (Log_EventId)0
Typedefs
typedef opaque | Log_Event// Log event type;
typedef Types_RopeId | Log_EventId// Unique ID embedded in each Event;
typedef struct | Log_EventRec// The target representation of a recorded event ...
Constants
extern const Log_Event | Log_L_construct// Lifecycle event posted when an instance is constructed;
extern const Log_Event | Log_L_create// Lifecycle event posted when an instance is created;
extern const Log_Event | Log_L_delete// Lifecycle event posted when an instance is deleted;
extern const Log_Event | Log_L_destruct// Lifecycle event posted when an instance is destructed;
extern const Log_Event | Log_L_error// Error event posted by Log_errorX API;
extern const Log_Event | Log_L_info// Info event posted by Log_infoX API;
extern const Log_Event | Log_L_warning// Warning event posted by Log_warningX API;
DETAILS
RTSC modules and the application code generate Log_Event events by calling the Log module's functions. The Log module then passes those events to an ILogger instance assigned to the event originating module, specified by that module's configuration parameter common$.logger. ILogger instances handle events, usually converting events to Log_EventRec records prior to recording, transmitting, or displaying them.
All events generated by a target module are stored and displayed by an ILogger, examples of which are instances of xdc.runtime.LoggerBuf or xdc.runtime.LoggerSys. At runtime, modules generate events through this module, rather than invoking directly their ILoggers. By doing so, modules can be configured to use different ILogger implementations without any changes to their source code.
A logger instance can accept Log events from any module, but a module can put Log events to only one logger instance. There can be one or more logger instances in a system. All Log calls that are not in a module are controlled by the module xdc.runtime.Main. For example, top-level application code or any existing sources that simply call the Log or Assert methods implicitly use the logger associated with the Main module.
The generation of a Log event is controlled by a module's diagnostics mask, which is described in details in Diags. Each Log event is associated with a mask. Log events are generated only when a particular bit is set in both the Log event mask and the module's diagnostics mask. For example, a Log event mask with the USER1 bit set is generated only when the USER1 bit is also set in the module's diagnostics mask.
There are two ways to generate Log events:
  • Log_write(), which is tailored for module writers and takes full advantage of the XDC configuration model. For example, the message string associated with the Log event need not be a part of the final application, significantly reducing the "footprint overhead" of embedding diagnostics in deployed systems. The Log_write[0-8]() functions allow up to 8 values to be passed to the logger. They expect the logger to handle any formatting. A Log event type allows you to specify the type of event.
  • Log_print(), which is designed for arbitrary C code. The Log_print[0-6]() functions allow up to 6 values to be passed along with a printf-like format string to the logger. They handle printf-style formatting.
Both functions are controlled by the module's diagnostics mask. Their storage or output is defined by the logger that is assigned to the module that calls the Log methods or to the xdc.runtime.Main module if the caller is not part of a module.
The Log function call sites are implemented in such a way that an optimizer can completely eliminate Log code from the program if the Log functions have been permanently disabled at configuration time. If the Log functions are permanently turned on at configuration time, then the optimizer can eliminate all runtime conditional checking and simply invoke the Log functions directly. Runtime checking is performed only when the Log functions are configured to be runtime modifiable.
The Log calls can also be completely removed by defining the symbol xdc_runtime_Log_DISABLE_ALL. This can be done on the compile line, e.g. -Dxdc_runtime_Log_DISABLE_ALL. This will completely remove the Log statements from any code compiled with this flag, regardless of the application's logging configuration or your compiler's optimization settings.
It is also possible to remove all logging except for Log_error, Log_warning, or Log_info statements. This is done by first defining xdc_runtime_Log_DISABLE_ALL, followed by defining one or more of the symbols below to leave that type of logging enabled:
  • xdc_runtime_Log_ENABLE_ERROR
  • xdc_runtime_Log_ENABLE_WARNING
  • xdc_runtime_Log_ENABLE_INFO
For example, to disable all Log statements except for Log_error, add the following to the compile line:
      -Dxdc_runtime_Log_DISABLE_ALL -Dxdc_runtime_Log_ENABLE_ERROR
EXAMPLES
Example 1: The following example defines a Log event, uses that Log event in a module, and configures the program to generate the Log event. In this example, both USER1 and USER2 bits are set in the event mask. This means that if either bit is set in the module's diagnostics mask, then the Log event will be generated.
This is a part of the XDC specification file for the Mod module (Mod.xdc):
  import xdc.runtime.Diags;
  import xdc.runtime.Log;

  config Log.Event L_someEvent = {
      mask: Diags.USER1 | Diags.USER2,
      level: Diags.LEVEL1,
      msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
  };
This is a part of the C code implementation of the Mod module:
  #include <xdc/runtime/Log.h>
  UInt x, y;

  Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
The following configuration script demonstrates how the application might control the Log statements embedded in the Mod module at configuration time. In this case, the configuration script arranges for the Log statements within the Mod module (shown above) to always generate events. Without these configuration statements, no Log events would be generated by this module.
This is part of the XDC configuration file for the application:
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
  var Mod = xdc.useModule('my.pkg.Mod');
  Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
  Mod.common$.logger = LoggerSys.create();
Example 2: The following XDC configuration statements turn on enter and exit logging at configuration time for a module. Without any other changes in the runtime code, every time a module Mod's function is being called or exits, an event will be logged.
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
  Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
Example 3: The following example configures a module to support enter and exit logging, but defers the actual activation and deactivation of the logging until runtime. See the Diags_setMask() function for details on specifying the control string.
This is a part of the XDC configuration file for the application:
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
  Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
This is a part of the C code for the application:
  // turn on enter and exit logging in the module
  Diags_setMask("my.pkg.Mod+EX");

  // turn off enter and exit logging in the module
  Diags_setMask("my.pkg.Mod-EX");
const Log_NUMARGS
index URL

Maximum number of arguments supported in Log events

C synopsis target-domain
#define Log_NUMARGS (Int)8
const Log_PRINTFID
index URL

The EventId for Log_print() events

C synopsis target-domain
#define Log_PRINTFID (Log_EventId)0
typedef Log_Event
index URL

Log event type

C synopsis target-domain
typedef opaque Log_Event;
DETAILS
An Event is represented on the target as a 32-bit value that can be decoded offline to recover the Event information defined in a corresponding metaonly EventDesc. In addition, Events may be decoded at runtime via methods provided in this module; see getMask and getEventId.
When an event is "raised" a Types_Event is created which has the same event ID as the Log_Event but also encodes the module ID of the caller. This new event is passed to the underlying ILogger module along with any arguments associated with the event.
SEE
getMask, getEventId
typedef Log_EventId
index URL

Unique ID embedded in each Event

C synopsis target-domain
typedef Types_RopeId Log_EventId;
DETAILS
This ID must be used to compare two Events for equality. Event ids are not guaranteed to remain constant between different configurations of an application. For example, adding a module may cause the event ids of another module to change.
However, event ids declared by a module are guaranteed to be consecutive values starting from the first declared Log_Event and increasing to the last declared event. As a result, clients of a module can efficiently test ranges of events and modules can add new events, such as internal trace events, without breaking clients; simply be careful to add new events after any existing events in you module's .xdc specification.
SEE
getEventId, Event
struct Log_EventRec
index URL

The target representation of a recorded event

C synopsis target-domain
typedef struct Log_EventRec {
     Types_Timestamp64 tstamp;
    // time event was written
    Bits32 serial;
    // serial number of event
     Types_Event evt;
    // target encoding of an Event
    IArg arg[Log_NUMARGS];
    // arguments passed via Log_write/print
} Log_EventRec;
DETAILS
This structure defines how events are recorded on the target.
config Log_L_construct // module-wide
index URL

Lifecycle event posted when an instance is constructed

C synopsis target-domain
extern const Log_Event Log_L_construct;
config Log_L_create // module-wide
index URL

Lifecycle event posted when an instance is created

C synopsis target-domain
extern const Log_Event Log_L_create;
config Log_L_delete // module-wide
index URL

Lifecycle event posted when an instance is deleted

C synopsis target-domain
extern const Log_Event Log_L_delete;
config Log_L_destruct // module-wide
index URL

Lifecycle event posted when an instance is destructed

C synopsis target-domain
extern const Log_Event Log_L_destruct;
config Log_L_error // module-wide
index URL

Error event posted by Log_errorX API

C synopsis target-domain
extern const Log_Event Log_L_error;
DETAILS
This event is marked as a STATUS event and given the priority level of ERROR.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
config Log_L_info // module-wide
index URL

Info event posted by Log_infoX API

C synopsis target-domain
extern const Log_Event Log_L_info;
DETAILS
This event is marked as an INFO event. The event priority is not specified in the event definition. Rather, it is specified as an argument to the Log_infoX APIs.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
config Log_L_warning // module-wide
index URL

Warning event posted by Log_warningX API

C synopsis target-domain
extern const Log_Event Log_L_warning;
DETAILS
This event is marked as a STATUS event and given the priority level of WARNING.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
Log_doPrint() // module-wide
index URL

Render an event as text via System_printf

C synopsis target-domain
Void Log_doPrint(Log_EventRec *evRec);
ARGUMENTS
evRec — a nonNULL pointer to an initialized Log_EventRec structure to be formated via System_printf.
DETAILS
This method is not gated and may make more than one call to System_printf. This utility method is typically used within the implementation of a logger which initializes Log_EventRec structures based on Log events produced by the application.
Log_error0() // module-wide
index URL

Generate a Log "error event" with 0 arguments

C synopsis target-domain
macro Void Log_error0(String fmt);
SEE
error5
Log_error1() // module-wide
index URL

Generate a Log "error event" with 1 argument

C synopsis target-domain
macro Void Log_error1(String fmt, IArg a1);
SEE
error5
Log_error2() // module-wide
index URL

Generate a Log "error event" with 2 arguments

C synopsis target-domain
macro Void Log_error2(String fmt, IArg a1, IArg a2);
SEE
error5
Log_error3() // module-wide
index URL

Generate a Log "error event" with 3 arguments

C synopsis target-domain
macro Void Log_error3(String fmt, IArg a1, IArg a2, IArg a3);
SEE
error5
Log_error4() // module-wide
index URL

Generate a Log "error event" with 4 arguments

C synopsis target-domain
macro Void Log_error4(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
SEE
error5
Log_error5() // module-wide
index URL

Generate a Log "error event" with 5 arguments

C synopsis target-domain
macro Void Log_error5(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
ARGUMENTS
fmt — a reference to a constant error string / fmt string
a1 — value for an additional parameter (e.g. an error code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_error APIs are intended to allow users to easily log error events in their code. Similar to the Log_print APIs, Log_error does not require that you define an event. You simply pass an informative error string which can optionally be formatted with additional arguments. The error is logged with the predefined event L_error.
Log_error prepends a string to the message which identifies it as an ERROR and specifies the filename and line number of the Log_error call site. A simple example:
  Log_error0("Invalid argument");
This event will be formatted as (assuming that the above call was line 35 of "MyCode.c")
  ERROR at "MyCode.c", line 35: Invalid argument
Users may provide additional information in the error event, such as a predefined error code or details of the error. These additional values will be used to format the string passed to Log_error.
Log_error does not use a variable length argument list--you must call the appropriate Log_errorX API based on the number of arguments.
SEE
for information about format strings.
EXAMPLES
The following example demonstrates a typical usage.
  Int myArg;

  Log_error1("Invalid argument: %d", myArg);
The above event is formatted as, for example:
  ERROR: "MyCode.c", line 35: Invalid argument: -1
Log_getEventId() // module-wide
index URL

Get event ID of the specified (encoded) event

C synopsis target-domain
macro Log_EventId Log_getEventId(Log_Event evt);
ARGUMENTS
evt — the Log event encoding a mask and event ID
DETAILS
This method is used to compare "known" Log events with "raised" Types_Event.
RETURNS
event ID of the specified event
SEE
Types.getEventId
Log_getMask() // module-wide
index URL

Get the Diags mask for the specified (encoded) event

C synopsis target-domain
macro Diags_Mask Log_getMask(Log_Event evt);
ARGUMENTS
evt — the Log event encoding a mask and event ID
RETURNS
Diags mask for the specified event
Log_info0() // module-wide
index URL

Generate a Log "info event" with 0 arguments

C synopsis target-domain
macro Void Log_info0(String fmt);
SEE
info5
Log_info1() // module-wide
index URL

Generate a Log "info event" with 1 argument

C synopsis target-domain
macro Void Log_info1(String fmt, IArg a1);
SEE
info5
Log_info2() // module-wide
index URL

Generate a Log "info event" with 2 arguments

C synopsis target-domain
macro Void Log_info2(String fmt, IArg a1, IArg a2);
SEE
info5
Log_info3() // module-wide
index URL

Generate a Log "info event" with 3 arguments

C synopsis target-domain
macro Void Log_info3(String fmt, IArg a1, IArg a2, IArg a3);
SEE
info5
Log_info4() // module-wide
index URL

Generate a Log "info event" with 4 arguments

C synopsis target-domain
macro Void Log_info4(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
SEE
info5
Log_info5() // module-wide
index URL

Generate a Log "info event" with 5 arguments

C synopsis target-domain
macro Void Log_info5(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
ARGUMENTS
fmt — reference to a constant event string / fmt string
a1 — value for an additional parameter (e.g. an event code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_info APIs are provided for easily logging generic "informational" events with call site information. They are similar to the Log_print APIs in that they do not require you to define an event-- you simply pass an informative printf-style string which can optionally be formatted with additional arguments. The info record is logged with the predefined event 'L_info'.
The Log_info APIs log the L_info event which uses the 'INFO' diags category. They do not allow you to specify an event priority.
Log_info prepends the filename and line number of the call site to the message.
EXAMPLES
The following example demonstrates a typical usage.
  Int load;

  Log_info1("Current load: %d", load);
The above event is formatted as, for example:
  "MyCode.c", line 15: Current load: 25
Log_print0() // module-wide
index URL

Generate a Log "print event" with 0 arguments

C synopsis target-domain
macro Void Log_print0(Diags_Mask mask, String fmt);
SEE
print6
Log_print1() // module-wide
index URL

Generate a Log "print event" with 1 argument

C synopsis target-domain
macro Void Log_print1(Diags_Mask mask, String fmt, IArg a1);
SEE
print6
Log_print2() // module-wide
index URL

Generate a Log "print event" with 2 arguments

C synopsis target-domain
macro Void Log_print2(Diags_Mask mask, String fmt, IArg a1, IArg a2);
SEE
print6
Log_print3() // module-wide
index URL

Generate a Log "print event" with 3 arguments

C synopsis target-domain
macro Void Log_print3(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3);
SEE
print6
Log_print4() // module-wide
index URL

Generate a Log "print event" with 4 arguments

C synopsis target-domain
macro Void Log_print4(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
SEE
print6
Log_print5() // module-wide
index URL

Generate a Log "print event" with 5 arguments

C synopsis target-domain
macro Void Log_print5(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
SEE
print6
Log_print6() // module-wide
index URL

Generate a Log "print event" with 6 arguments

C synopsis target-domain
macro Void Log_print6(Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
ARGUMENTS
mask — enable bits and optional detail level for this event
fmt — a printf style format string
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
a5 — value for fifth format conversion character
a6 — value for sixth format conversion character
DETAILS
As a convenience to C (as well as assembly language) programmers, the Log module provides a variation of the ever-popular printf function. The print[0-6] functions generate a Log "print event" and route it to the current module's logger.
The arguments passed to print[0-6] may be characters, integers, strings, or pointers. However, because the declared type of the arguments is IArg, all pointer arguments must be cast to an IArg type. IArg is an integral type large enough to hold any pointer or an int. So, casting a pointer to an IArg does not cause any loss of information and C's normal integer conversions make the cast unnecessary for integral arguments.
The format string can use the following conversion characters. However, it is important to recall that all arguments referenced by these conversion characters have been converted to an IArg prior to conversion; so, the use of "length modifiers" should be avoided.
  Conversion Character    Description
  ------------------------------------------------
  %c                      Character
  %d                      Signed integer
  %u                      Unsigned integer
  %x                      Unsigned hexadecimal integer
  %o                      Unsigned octal integer
  %s                      Character string
  %p                      Pointer
  %f                      Single precision floating point (float)
Format strings, while very convenient, are a well known source of portability problems: each format specification must precisely match the types of the arguments passed. Underlying "printf" functions use the format string to determine how far to advance through their argument list. For targets where pointer types and integers are the same size there are no problems. However, suppose a target's pointer type is larger than its integer type. In this case, because integer arguments are widened to be of type IArg, a format specification of "%d" causes an underlying printf() implementation to read the extended part of the integer argument as part of the next argument(!).
To get around this problem and still allow the use of "natural" format specifications (e.g., %d and %x with optional width specifications), System.aprintf() is used which assumes that all arguments have been widened to be of type IArg.
See System.printf for complete details.
The %f format specifier is used to print a single precision float value. Note that %f assumes that sizeof(Float) <= sizeof(IArg). Most clients that interpret float values expect that they are represented in IEEE 754 floating point format. Therefore, it is recommended that the float values be converted into that format prior to supplying the values to Log functions in cases where targets do not generate the float values in IEEE 754 floating point format by default.
The first argument to a Log_print call is the diags category to be associated with the event.
It is also possible to associate an event level with the event to enable filtering of events based on event level. Conceptually, it is best to regard the event level as completely separate from the event's diags category; however, the priority value actually occupies a part of the diags mask. For this reason, it is possible to specify an event level by OR'ing the level with the diags mask. For example, to print an Diags_INFO event of Diags_LEVEL2, you'd simply write: (Diags_INFO | Diags_LEVEL2)
Specifying an event level is optional. Log_print calls which do not specify a level will receive the highest priority by default.
EXAMPLES
The following example demonstrates a typical usage.
  String  list[];
  UInt    i;

  Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
Note that the IArg cast above is only necessary for pointer arguments; C's normal parameter conversions implicitly convert integral arguments.
To simplify the conversion from float arguments to IArg, the standard header xdc/std.h provides a macro, named floatToArg(), to do this conversion in a type safe manner. So, the following statement will print "float = 2.3456":
    Log_print1(Diags_USER1, "float = %f", floatToArg(2.34567));
Note that, if you are formatting events on the target, you must also add support for floating point to ASCII conversion to System.printf; for more information, see the System.extendedFormats reference documenation. For example:
      var System = xdc.useModule('xdc.runtime.System');
      System.extendedFormats = "%f";
Log_put0() // module-wide
index URL

Unconditionally put the specified Log event with 0 arguments

C synopsis target-domain
macro Void Log_put0(Log_Event evt, Types_ModuleId mid);
SEE
put4
Log_put1() // module-wide
index URL

Unconditionally put the specified Log event and 1 argument

C synopsis target-domain
macro Void Log_put1(Log_Event evt, Types_ModuleId mid, IArg a1);
SEE
put4
Log_put2() // module-wide
index URL

Unconditionally put the specified Log event and 2 arguments

C synopsis target-domain
macro Void Log_put2(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
SEE
put4
Log_put4() // module-wide
index URL

Unconditionally put the specified Log event

C synopsis target-domain
macro Void Log_put4(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
ARGUMENTS
evt — the Log event to put into the log
mid — module ID of the module putting the event
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
DETAILS
This method unconditionally puts the specified Event evt into the log. The Types.ModuleId mid should be the module ID of the module which is putting the event.
SEE
put8
Log_put8() // module-wide
index URL

Unconditionally put the specified Log event and 8 arguments

C synopsis target-domain
macro Void Log_put8(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
SEE
put4
Log_warning0() // module-wide
index URL

Generate a Log "warning event" with 0 arguments

C synopsis target-domain
macro Void Log_warning0(String fmt);
SEE
warning5
Log_warning1() // module-wide
index URL

Generate a Log "warning event" with 1 argument

C synopsis target-domain
macro Void Log_warning1(String fmt, IArg a1);
SEE
warning5
Log_warning2() // module-wide
index URL

Generate a Log "warning event" with 2 arguments

C synopsis target-domain
macro Void Log_warning2(String fmt, IArg a1, IArg a2);
SEE
warning5
Log_warning3() // module-wide
index URL

Generate a Log "warning event" with 3 arguments

C synopsis target-domain
macro Void Log_warning3(String fmt, IArg a1, IArg a2, IArg a3);
SEE
warning5
Log_warning4() // module-wide
index URL

Generate a Log "warning event" with 4 arguments

C synopsis target-domain
macro Void Log_warning4(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
SEE
warning5
Log_warning5() // module-wide
index URL

Generate a Log "warning event" with 5 arguments

C synopsis target-domain
macro Void Log_warning5(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
ARGUMENTS
fmt — reference to a constant warning string / fmt string
a1 — value for an additional parameter (e.g. a warning code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_warning APIs provide the same features as the Log_error APIs, but are used to specifically log "warning" events.
The Log_warning APIs are equivalent to the Log_error APIs except that they use the predefined L_warning event. Log_warning prepends a string to the message which identifies it as a WARNING and specifies the filename and line number of the Log_warning call site.
SEE
error5
EXAMPLES
The following example demonstrates a typical usage.
  Int myArg;

  Log_warning1("Value may be too high: %d", myArg);
The above event is formatted as:
  WARNING: "MyCode.c", line 50: Value may be too high: 4096
Log_write0() // module-wide
index URL

Generate a Log event with 0 arguments

C synopsis target-domain
macro Void Log_write0(Log_Event evt);
SEE
write8
Log_write1() // module-wide
index URL

Generate a Log event with 1 argument

C synopsis target-domain
macro Void Log_write1(Log_Event evt, IArg a1);
SEE
write8
Log_write2() // module-wide
index URL

Generate a Log event with 2 arguments

C synopsis target-domain
macro Void Log_write2(Log_Event evt, IArg a1, IArg a2);
SEE
write8
Log_write3() // module-wide
index URL

Generate a Log event with 3 arguments

C synopsis target-domain
macro Void Log_write3(Log_Event evt, IArg a1, IArg a2, IArg a3);
SEE
write8
Log_write4() // module-wide
index URL

Generate a Log event with 4 arguments

C synopsis target-domain
macro Void Log_write4(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
SEE
write8
Log_write5() // module-wide
index URL

Generate a Log event with 5 arguments

C synopsis target-domain
macro Void Log_write5(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
SEE
write8
Log_write6() // module-wide
index URL

Generate a Log event with 6 arguments

C synopsis target-domain
macro Void Log_write6(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
SEE
write8
Log_write7() // module-wide
index URL

Generate a Log event with 7 arguments

C synopsis target-domain
macro Void Log_write7(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7);
SEE
write8
Log_write8() // module-wide
index URL

Generate a Log event with 8 arguments

C synopsis target-domain
macro Void Log_write8(Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
ARGUMENTS
evt — the Log event to write
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
a5 — value for fifth format conversion character
a6 — value for sixth format conversion character
a7 — value for seventh format conversion character
a8 — value for eighth format conversion character
DETAILS
If the mask in the specified Log event has any bit set which is also set in the current module's diagnostics mask, then this call to write will "raise" the given Log event.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Log_Module_id();
// Get this module's unique id
Bool Log_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Log_Module_heap();
// The heap from which this module allocates memory
Bool Log_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Log_Module_getMask();
// Returns the diagnostics mask for this module
Void Log_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Log.xdc
var Log = xdc.useModule('xdc.runtime.Log');
module-wide constants & types
    const Log.NUMARGS// Maximum number of arguments supported in Log events = 8;
    const Log.PRINTFID// The EventId for Log_print() events = 0;
    var obj = new Log.EventDesc// Log event descriptor;
        obj.mask// event enable mask = Bits16 ...
        obj.level// event level relative to other events = Diags.EventLevel ...
        obj.msg// event "printf" message format string = String ...
    var obj = new Log.EventRec// The target representation of a recorded event;
        obj.tstamp// time event was written = Types.Timestamp64 ...
        obj.serial// serial number of event = Bits32 ...
        obj.evt// target encoding of an Event = Bits32 ...
        obj.arg// arguments passed via Log_write/print = IArg[Log.NUMARGS] ...
module-wide config parameters
     Log.L_construct// Lifecycle event posted when an instance is constructed = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "<-- construct: %p('%s')"
    };
     Log.L_create// Lifecycle event posted when an instance is created = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "<-- create: %p('%s')"
    };
     Log.L_delete// Lifecycle event posted when an instance is deleted = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "--> delete: (%p)"
    };
     Log.L_destruct// Lifecycle event posted when an instance is destructed = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "--> destruct: (%p)"
    };
     Log.L_error// Error event posted by Log_errorX API = Log.EventDesc {
        mask: Diags.STATUS,
        level: Diags.ERROR,
        msg: "ERROR: %$F%$S"
    };
     Log.L_info// Info event posted by Log_infoX API = Log.EventDesc {
        mask: Diags.INFO,
        msg: "%$F%$S"
    };
     Log.L_warning// Warning event posted by Log_warningX API = Log.EventDesc {
        mask: Diags.STATUS,
        level: Diags.WARNING,
        msg: "WARNING: %$F%$S"
    };
     Log.common$// Common module configuration parameters = Types.Common$ undefined;
const Log.NUMARGS
index URL

Maximum number of arguments supported in Log events

XDCscript usage meta-domain
const Log.NUMARGS = 8;
C SYNOPSIS
Log_NUMARGS
const Log.PRINTFID
index URL

The EventId for Log_print() events

XDCscript usage meta-domain
const Log.PRINTFID = 0;
C SYNOPSIS
Log_PRINTFID
metaonly struct Log.EventDesc
index URL

Log event descriptor

XDCscript usage meta-domain
var obj = new Log.EventDesc;
    obj.mask = Bits16 ...
    // event enable mask
    obj.level = Diags.EventLevel ...
    // event level relative to other events
    obj.msg = String ...
    // event "printf" message format string
DETAILS
Each Log event is defined by a Log event descriptor.
The mask defines which bits in the module's diagnostics mask enable this Log event. Events "posted" via Log_write are only written to the underlying logger if one of the mask's bits matches the caller's module diagnostics settings (see xdc.runtime.Types.common$).
The 'level' defines the event level of the event. While the diags bits selected in the 'mask' signify the "category" of the event (e.g. Entry/Exit, Analysis, Info), the 'level' field allows you to assign a "priority" or "detail level" to the event relative to other events in that category. There are four event levels defined by 'xdc.runtime.Diags.EventLevel'.
Filtering of events by level is handled by the ILogger implementation. ILogger implementations which also implement the IFilterLogger interface support filtering of events based on priority level.
Specifying an event level is optional. Events that don't specify a level will receive Diags.LEVEL1 by default, making them the highest priority and ensuring that they will not inadvertently be filtered out by level-based filtering.
The msg defines a printf style format string that defines how to render the arguments passed along the event in a Log_write call. For a description of the allowable format strings see print6.
SEE
write8, print6
struct Log.EventRec
index URL

The target representation of a recorded event

XDCscript usage meta-domain
var obj = new Log.EventRec;
    obj.tstamp = Types.Timestamp64 ...
    // time event was written
    obj.serial = Bits32 ...
    // serial number of event
    obj.evt = Bits32 ...
    // target encoding of an Event
    obj.arg = IArg[Log.NUMARGS] ...
    // arguments passed via Log_write/print
DETAILS
This structure defines how events are recorded on the target.
C SYNOPSIS
Log_EventRec
config Log.L_construct // module-wide
index URL

Lifecycle event posted when an instance is constructed

XDCscript usage meta-domain
Log.L_construct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- construct: %p('%s')"
};
C SYNOPSIS
Log_L_construct
config Log.L_create // module-wide
index URL

Lifecycle event posted when an instance is created

XDCscript usage meta-domain
Log.L_create = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- create: %p('%s')"
};
C SYNOPSIS
Log_L_create
config Log.L_delete // module-wide
index URL

Lifecycle event posted when an instance is deleted

XDCscript usage meta-domain
Log.L_delete = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> delete: (%p)"
};
C SYNOPSIS
Log_L_delete
config Log.L_destruct // module-wide
index URL

Lifecycle event posted when an instance is destructed

XDCscript usage meta-domain
Log.L_destruct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> destruct: (%p)"
};
C SYNOPSIS
Log_L_destruct
config Log.L_error // module-wide
index URL

Error event posted by Log_errorX API

XDCscript usage meta-domain
Log.L_error = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.ERROR,
    msg: "ERROR: %$F%$S"
};
DETAILS
This event is marked as a STATUS event and given the priority level of ERROR.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
C SYNOPSIS
Log_L_error
config Log.L_info // module-wide
index URL

Info event posted by Log_infoX API

XDCscript usage meta-domain
Log.L_info = Log.EventDesc {
    mask: Diags.INFO,
    msg: "%$F%$S"
};
DETAILS
This event is marked as an INFO event. The event priority is not specified in the event definition. Rather, it is specified as an argument to the Log_infoX APIs.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
C SYNOPSIS
Log_L_info
config Log.L_warning // module-wide
index URL

Warning event posted by Log_warningX API

XDCscript usage meta-domain
Log.L_warning = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.WARNING,
    msg: "WARNING: %$F%$S"
};
DETAILS
This event is marked as a STATUS event and given the priority level of WARNING.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
C SYNOPSIS
Log_L_warning
metaonly config Log.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Log.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.LoggerBuf
index URL

A logger which stores Log events in a buffer

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
This module provides a logger which captures Log events to a buffer in realtime. The Log events stored in the buffer are unformatted; Log event formatting is deferred until some client reads the raw event data from the buffer. You can use LoggerBuf_flush() to process the Log events stored in the buffer and stream the formatted output to stdout (via System.printf). Alternatively, you can read a raw event (via getNextEntry) and send it to another client that has the resources to format the event for display. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/LoggerBuf.xdc
#include <xdc/runtime/LoggerBuf.h>
Functions
Void
LoggerBuf_construct// Initialize a new instance object inside the provided structure(LoggerBuf_Struct *structP, const LoggerBuf_Params *params, Error_Block *eb);
LoggerBuf_Handle
LoggerBuf_create// Allocate and initialize a new instance object and return its handle(const LoggerBuf_Params *params, Error_Block *eb);
Void
LoggerBuf_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(LoggerBuf_Handle *handleP);
Void
LoggerBuf_destruct// Finalize the instance object inside the provided structure(LoggerBuf_Struct *structP);
Void
LoggerBuf_flush// Read, clear, and output the contents of the log(LoggerBuf_Handle handle);
Void
LoggerBuf_flushAll// Flush logs of all instances that set exitFlush to true();
Int
LoggerBuf_getNextEntry// Fills the passed Log.EventRec with the next entry in the log(LoggerBuf_Handle handle, Log_EventRec *evtRec);
Void
LoggerBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LoggerBuf_Params *params);
Void
LoggerBuf_reset// Reset a log to empty state and enable it(LoggerBuf_Handle handle);
Functions common to all ILogger modules
Bool
LoggerBuf_disable// Disable a log(LoggerBuf_Handle handle);
Bool
LoggerBuf_enable// Enable a log(LoggerBuf_Handle handle);
Void
LoggerBuf_write0// Process a log event with 0 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid);
Void
LoggerBuf_write1// Process a log event with 1 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
Void
LoggerBuf_write2// Process a log event with 2 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
Void
LoggerBuf_write4// Process a log event with up to 4 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
Void
LoggerBuf_write8// Process a log event with up to 8 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Functions common to all IFilterLogger modules
Diags_Mask
LoggerBuf_getFilterLevel// Returns the mask of diags categories currently set to the specified level(LoggerBuf_Handle handle, Diags_EventLevel level);
Void
LoggerBuf_setFilterLevel// Set the level of detail that instances will log(LoggerBuf_Handle handle, Diags_Mask mask, Diags_EventLevel filterLevel);
Functions common to all target instances
LoggerBuf_handle// Convert this instance structure pointer into an instance handle, LoggerBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, LoggerBuf_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, LoggerBuf_Handle_label// The label associated with this instance object, LoggerBuf_Handle_name// The name of this instance object, LoggerBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy, LoggerBuf_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, LoggerBuf_Object_count// The number of statically-created instance objects, LoggerBuf_Object_first// The handle of the first dynamically-created instance object, or NULL, LoggerBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL), LoggerBuf_Object_heap// The heap used to allocate dynamically-created instance objects, LoggerBuf_Object_next// The handle of the next dynamically-created instance object, or NULL, LoggerBuf_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
LoggerBuf_Module_getMask// Returns the diagnostics mask for this module, LoggerBuf_Module_hasMask// Test whether this module has a diagnostics mask, LoggerBuf_Module_heap// The heap from which this module allocates memory, LoggerBuf_Module_id// Get this module's unique id, LoggerBuf_Module_setMask// Set the diagnostics mask for this module, LoggerBuf_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum
LoggerBuf_BufType// Type of log buffer ...
typedef LoggerBuf_Object *
LoggerBuf_Handle// Client reference to an instance object;
typedef struct
LoggerBuf_Object// Opaque internal representation of an instance object LoggerBuf_Object;
typedef struct
LoggerBuf_Params// Instance config-params structure ...
typedef struct
LoggerBuf_Struct// Opaque client structure large enough to hold an instance object LoggerBuf_Struct;
Constants
extern const Bool
LoggerBuf_enableFlush// Flush all logs at system exit;
extern const Error_Id
LoggerBuf_E_badLevel// Error raised if get or setFilterLevel receives a bad level value;
extern const Bool
LoggerBuf_filterByLevel// Support filtering of events by event level;
extern const Diags_Mask
LoggerBuf_level1Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL1;
extern const Diags_Mask
LoggerBuf_level2Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL2;
extern const Diags_Mask
LoggerBuf_level3Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL3;
extern const Diags_Mask
LoggerBuf_level4Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL4;
extern const ILogger_Handle
LoggerBuf_statusLogger// Route all 'STATUS' (error and warning) events to this logger;
DETAILS
This module provides a logger which captures Log events to a buffer in realtime. The Log events stored in the buffer are unformatted; Log event formatting is deferred until some client reads the raw event data from the buffer. You can use LoggerBuf_flush() to process the Log events stored in the buffer and stream the formatted output to stdout (via System.printf). Alternatively, you can read a raw event (via getNextEntry) and send it to another client that has the resources to format the event for display.
The implementation of this logger is fast with minimal stack usage making it appropriate for a realtime application. This logger writes all Log events to a circular buffer. As a result, the execution time of all Log methods bound to this type of logger are deterministic (and quite short) because there are no additional memory allocation calls after the circular buffer was allocated.
If this logger is used in a preemptive environment, then an appropriate gate must be assigned to the module. For example, if events are generated from an interrupt context, then a gate that disables interrupts must be used.
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
  LoggerBuf.common$.gate = ...some gate instance...
If the buffer type is circular, the log buffer of size numEntries contains the last numEntries of Log events. If the buffer type is fixed, the log buffer contains the first numEntries events.
LoggerBuf supports routing of 'STATUS' events (errors and warnings) to a separate ILogger instance. This is helpful in preserving these critical events, which may otherwise be overwritten by lower priority events. This feature is disabled by default. See statusLogger.
LoggerBuf implements the IFilterLogger interface and optionally supports filtering of events based on their detail level. This feature is disabled by default. See IFilterLogger.
EXAMPLES
Configuration example: The following XDC configuration statements create a logger instance, assign it as the default logger for all modules, and enable USER1 logging in all modules of the package my.pkg. See the Diags.setMaskMeta() function for details on specifying the module names.
  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

  LoggerBuf.enableFlush = true;
  var LoggerBufParams = new LoggerBuf.Params();
  LoggerBufParams.exitFlush = true;
  Defaults.common$.logger = LoggerBuf.create(LoggerBufParams);
  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
enum LoggerBuf_BufType
index URL

Type of log buffer

C synopsis target-domain
typedef enum LoggerBuf_BufType {
    LoggerBuf_BufType_CIRCULAR,
    // The log buffer wraps, overwriting old entries
    LoggerBuf_BufType_FIXED
    // The log buffer halts collection when full
} LoggerBuf_BufType;
config LoggerBuf_E_badLevel // module-wide
index URL

Error raised if get or setFilterLevel receives a bad level value

C synopsis target-domain
extern const Error_Id LoggerBuf_E_badLevel;
config LoggerBuf_enableFlush // module-wide
index URL

Flush all logs at system exit

C synopsis target-domain
extern const Bool LoggerBuf_enableFlush;
config LoggerBuf_filterByLevel // module-wide
index URL

Support filtering of events by event level

C synopsis target-domain
extern const Bool LoggerBuf_filterByLevel;
DETAILS
To improve logging performance, this feature can be disabled by setting filterByLevel to false.
See 'setFilterLevel' for an explanation of level filtering.
config LoggerBuf_level1Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL1

C synopsis target-domain
extern const Diags_Mask LoggerBuf_level1Mask;
DETAILS
See 'level4Mask' for details.
config LoggerBuf_level2Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL2

C synopsis target-domain
extern const Diags_Mask LoggerBuf_level2Mask;
DETAILS
See 'level4Mask' for details.
config LoggerBuf_level3Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL3

C synopsis target-domain
extern const Diags_Mask LoggerBuf_level3Mask;
DETAILS
See 'level4Mask' for details.
config LoggerBuf_level4Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL4

C synopsis target-domain
extern const Diags_Mask LoggerBuf_level4Mask;
DETAILS
If IFilterLogger.filterByLevel is true, then all LoggerBuf instances will filter incoming events based on their event level.
The LoggerBuf module allows for specifying a different filter level for every Diags bit. These filtering levels are module wide; LoggerBuf does not support specifying the levels on a per-instance basis.
The IFilterLogger.setFilterLevel function can be used to change the filtering levels at runtime.
The default filtering levels are assigned using the level1Mask - level4Mask config parameters. These are used to specify, for each of the four event levels, the set of bits which should filter at that level by default.
The default filtering configuration sets the filter level to Diags.LEVEL4 for all logging-related diags bits so that all events are logged by default.
config LoggerBuf_statusLogger // module-wide
index URL

Route all 'STATUS' (error and warning) events to this logger

C synopsis target-domain
extern const ILogger_Handle LoggerBuf_statusLogger;
DETAILS
If a statusLogger is specified, all LoggerBuf instances will check to determine if any of the events they receive are errors or warnings (if their diags mask includes the STATUS category), and will log these events to the statusLogger.
Error events are infrequent, but it's generally critical that they be seen. In a typical system, non-error events easily outnumber any error events, and the logger is likely to wrap, overwriting any error events. To protect these events from being overwritten and lost, they can be sent to their own separate logger to preserve them.
The default value is null, indicating that the STATUS events will just be logged by the logger they were sent to.
LoggerBuf_flushAll() // module-wide
index URL

Flush logs of all instances that set exitFlush to true

C synopsis target-domain
Void LoggerBuf_flushAll();
DETAILS
The user is responsible for making sure that no LoggerBuf instances are created or deleted during the execution of this function.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId LoggerBuf_Module_id();
// Get this module's unique id
Bool LoggerBuf_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle LoggerBuf_Module_heap();
// The heap from which this module allocates memory
Bool LoggerBuf_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 LoggerBuf_Module_getMask();
// Returns the diagnostics mask for this module
Void LoggerBuf_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct LoggerBuf_Object LoggerBuf_Object;
// Opaque internal representation of an instance object
typedef LoggerBuf_Object *LoggerBuf_Handle;
// Client reference to an instance object
typedef struct LoggerBuf_Struct LoggerBuf_Struct;
// Opaque client structure large enough to hold an instance object
LoggerBuf_Handle LoggerBuf_handle(LoggerBuf_Struct *structP);
// Convert this instance structure pointer into an instance handle
LoggerBuf_Struct *LoggerBuf_struct(LoggerBuf_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct LoggerBuf_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     IHeap_Handle bufHeap;
    // The heap that contains the Log buffer for dynamic instances
     LoggerBuf_BufType bufType;
    // Log buffer type
    Bool exitFlush;
    // Flush log at system exit
    Int numEntries;
    // Number of entries in buffer
} LoggerBuf_Params;
Void LoggerBuf_Params_init(LoggerBuf_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config LoggerBuf_bufHeap // instance
index URL

The heap that contains the Log buffer for dynamic instances

C synopsis target-domain
struct LoggerBuf_Params {
     ...
     IHeap_Handle bufHeap;
DETAILS
The default value null means the buffer will be allocated from the Memory.defaultHeapInstance heap.
config LoggerBuf_bufType // instance
index URL

Log buffer type

C synopsis target-domain
struct LoggerBuf_Params {
     ...
     LoggerBuf_BufType bufType;
config LoggerBuf_exitFlush // instance
index URL

Flush log at system exit

C synopsis target-domain
struct LoggerBuf_Params {
     ...
    Bool exitFlush;
DETAILS
Only used when module parameter enableFlush is true.
config LoggerBuf_numEntries // instance
index URL

Number of entries in buffer

C synopsis target-domain
struct LoggerBuf_Params {
     ...
    Int numEntries;
DETAILS
Each entry is large enough to store one Log event containing up to 4 optional arguments. Events containing more than 4 arguments (such as those from Log.write5) use 2 entries.
numEntries must be a power of 2.
Instance Creation
index URL

C synopsis target-domain
LoggerBuf_Handle LoggerBuf_create(const LoggerBuf_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void LoggerBuf_construct(LoggerBuf_Struct *structP, const LoggerBuf_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
SEE
LoggerBuf.Params
Instance Deletion
index URL

C synopsis target-domain
Void LoggerBuf_delete(LoggerBuf_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void LoggerBuf_destruct(LoggerBuf_Struct *structP);
// Finalize the instance object inside the provided structure
LoggerBuf_disable() // instance
index URL

Disable a log

C synopsis target-domain
Bool LoggerBuf_disable(LoggerBuf_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
Events written to a disabled log are silently discarded.
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
LoggerBuf_enable() // instance
index URL

Enable a log

C synopsis target-domain
Bool LoggerBuf_enable(LoggerBuf_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
LoggerBuf_flush() // instance
index URL

Read, clear, and output the contents of the log

C synopsis target-domain
Void LoggerBuf_flush(LoggerBuf_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
This method reads, clears, and "prints" each Log event (via System.printf) in the log.
LoggerBuf_getFilterLevel() // instance
index URL

Returns the mask of diags categories currently set to the specified level

C synopsis target-domain
Diags_Mask LoggerBuf_getFilterLevel(LoggerBuf_Handle handle, Diags_EventLevel level);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
See 'setFilterLevel' for an explanation of level filtering.
LoggerBuf_getNextEntry() // instance
index URL

Fills the passed Log.EventRec with the next entry in the log

C synopsis target-domain
Int LoggerBuf_getNextEntry(LoggerBuf_Handle handle, Log_EventRec *evtRec);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
evtRec — pointer to a supplied EventRec object where the next entry in the log is copied to
DETAILS
This function is used to read and clear Log events from the buffer maintained by the LoggerBuf instance. The Log event can then be transmitted and displayed on a host.
A read pointer is maintained in the LoggerBuf instance and points to the next record to read. Entries are not necessarily returned in chronological order, since buffers of type BufType_CIRCULAR can wrap.
RETURNS
This function reports the number of entries actually read. The only values that can be returned are:
  • 0 no more entries to read
  • 1 or 2 read a complete entry written by write4 or write8
  • -1 cleared an incomplete/overwritten entry, more entries to read
LoggerBuf_reset() // instance
index URL

Reset a log to empty state and enable it

C synopsis target-domain
Void LoggerBuf_reset(LoggerBuf_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
WARNING
This method is not synchronized with other instance methods and, as a result, it must never be called when there is a chance that another instance method is currently in operation or when another method on this instance may preempt this call.
LoggerBuf_setFilterLevel() // instance
index URL

Set the level of detail that instances will log

C synopsis target-domain
Void LoggerBuf_setFilterLevel(LoggerBuf_Handle handle, Diags_Mask mask, Diags_EventLevel filterLevel);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
mask — The diags categories to set the level for
filterLevel — The new filtering level for the specified categories
DETAILS
Events with the specified level or higher will be logged, events below the specified level will be dropped.
Events are filtered first by diags category, then by level. If an event's diags category is disabled in the module's diags mask, then it will be filtered out regardless of level. The event will not even be passed to the logger.
This API allows for setting the filtering level for more than one diags category at a time. The mask parameter can be a single category or multiple categories combined, and the level will be set for all of those categories.
LoggerBuf_write0() // instance
index URL

Process a log event with 0 arguments

C synopsis target-domain
Void LoggerBuf_write0(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
Same as write4 except with 0 arguments rather than 4.
SEE
ILogger.write4()
LoggerBuf_write1() // instance
index URL

Process a log event with 1 arguments

C synopsis target-domain
Void LoggerBuf_write1(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
Same as write4 except with 1 arguments rather than 4.
SEE
ILogger.write4()
LoggerBuf_write2() // instance
index URL

Process a log event with 2 arguments

C synopsis target-domain
Void LoggerBuf_write2(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
Same as write4 except with 2 arguments rather than 4.
SEE
ILogger.write4()
LoggerBuf_write4() // instance
index URL

Process a log event with up to 4 arguments

C synopsis target-domain
Void LoggerBuf_write4(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
evt — event to be logged
mid — module ID of the module which logged the event
a1 — arbitrary argument passed by caller
DETAILS
The evt argument is of type Log.Event, which encodes the Log.EventId, the Diags.Mask, and the Diags.EventLevel of the event. The event ID can be obtained via Types.getEventId(evt), the Diags mask can be obtained via Diags.getMask(evt), and the event level can be obtained via Diags.getLevel(evt).
The modId argument is the module ID of the module that logged the event.
The event information can be used by the logger to handle different events specially. For example, the event ID can be used to compare against other known Log.Events.
      if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
          :
      }
The Diags mask and event level can be used for filtering of events based on event level (see IFilterLogger), or even routing events to separate loggers based on diags category (see, for example, LoggerBuf.statusLogger).
The Diags mask and event level are useful for handling the event, but are generally not recorded by the logger because they are not needed in decoding and displaying the event. A more suitable value to record is a Types.Event, which encodes the event ID and module ID. For example, the Log.EventRec type stores a Types.Event in its record definition. A Types.Event can be created using the Types.makeEvent API given the event ID and module ID.
The event ID value of 0 is used to indicate an event triggered by a call to one of the Log_print[0-6] methods. These methods take a format string rather than a Log_Event argument and, as a result, the event ID encoded in evt is 0 and the parameter a1 is the format string.
Non-zero event IDs can also be used to access the msg string associated with the Log.EventDesc that originally defined the Log event.
      Log_EventId id = Log_getEventId(evt));
      if (id != 0) {
          String msg = Text_ropeText(id);
          System_aprintf(msg, a1, a2, a3, a4);
      }
This works because an event's ID is simply an offset into a table of characters (maintained by the Text module) containing the event's msg string.
The arguments a1, a2, etc. are parameters that are to be interpreted according to the message format string associated with evt.
SEE
Log.Event, Log.EventDesc, Text.ropeText, Log.getEventId
LoggerBuf_write8() // instance
index URL

Process a log event with up to 8 arguments

C synopsis target-domain
Void LoggerBuf_write8(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
ARGUMENTS
handle — handle of a previously-created LoggerBuf instance object
DETAILS
Same as write4 except with 8 arguments rather than 4.
SEE
ILogger.write4()
Instance Convertors
index URL

C synopsis target-domain
IFilterLogger_Handle LoggerBuf_Handle_upCast(LoggerBuf_Handle handle);
// unconditionally move one level up the inheritance hierarchy
LoggerBuf_Handle LoggerBuf_Handle_downCast(IFilterLogger_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
ILogger_Handle LoggerBuf_Handle_upCast2(LoggerBuf_Handle handle);
// unconditionally move 2 levels up the inheritance hierarchy
LoggerBuf_Handle LoggerBuf_Handle_downCast2(ILogger_Handle handle);
// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int LoggerBuf_Object_count();
// The number of statically-created instance objects
LoggerBuf_Handle LoggerBuf_Object_get(LoggerBuf_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
LoggerBuf_Handle LoggerBuf_Object_first();
// The handle of the first dynamically-created instance object, or NULL
LoggerBuf_Handle LoggerBuf_Object_next(LoggerBuf_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle LoggerBuf_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *LoggerBuf_Handle_label(LoggerBuf_Handle handle, Types_Label *buf);
// The label associated with this instance object
String LoggerBuf_Handle_name(LoggerBuf_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/LoggerBuf.xdc
var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
local proxy modules
     LoggerBuf.TimestampProxy// User supplied time-stamp proxy = ITimestampClient.Module null
         LoggerBuf.TimestampProxy.delegate$ = ITimestampClient.Module null
module-wide constants & types
    values of type LoggerBuf.BufType// Type of log buffer
        const LoggerBuf.BufType_CIRCULAR// The log buffer wraps, overwriting old entries;
        const LoggerBuf.BufType_FIXED// The log buffer halts collection when full;
    var obj = new LoggerBuf.BasicView// ;
        obj.label = String ...
        obj.lastSerial = Int ...
        obj.numEntries = Int ...
        obj.type = String ...
        obj.enabledFlag = Bool ...
    var obj = new LoggerBuf.RecordView// ;
        obj.serial = Int ...
        obj.timestampRaw = Long ...
        obj.modName = String ...
        obj.text = String ...
        obj.eventId = Int ...
        obj.eventName = String ...
        obj.arg0 = IArg ...
        obj.arg1 = IArg ...
        obj.arg2 = IArg ...
        obj.arg3 = IArg ...
        obj.arg4 = IArg ...
        obj.arg5 = IArg ...
        obj.arg6 = IArg ...
        obj.arg7 = IArg ...
    var obj = new LoggerBuf.StopModeData// Data added to the RTA MetaData file to support stop mode RTA;
        obj.bufferSymbol = String ...
        obj.bufferSize = Int ...
module-wide config parameters
     LoggerBuf.E_badLevel// Error raised if get or setFilterLevel receives a bad level value = Error.Desc {
        msg: "E_badLevel: Bad filter level value: %d"
    };
     LoggerBuf.enableFlush// Flush all logs at system exit = Bool false;
     LoggerBuf.filterByLevel// Support filtering of events by event level = Bool false;
     LoggerBuf.level1Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL1 = Bits16 0;
     LoggerBuf.level2Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL2 = Bits16 0;
     LoggerBuf.level3Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL3 = Bits16 0;
     LoggerBuf.level4Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL4 = Bits16 Diags.ALL_LOGGING;
     LoggerBuf.statusLogger// Route all 'STATUS' (error and warning) events to this logger = ILogger.Handle null;
     LoggerBuf.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     LoggerBuf.getMetaArgs// Returns any meta data needed to support RTA(Any inst, Any instNum) returns Any
per-instance config parameters
    var params = new LoggerBuf.Params// Instance config-params object;
        params.bufHeap// The heap that contains the Log buffer for dynamic instances = IHeap.Handle null;
        params.bufSection// Section name for the buffer managed by the static instance = String null;
        params.bufType// Log buffer type = LoggerBuf.BufType LoggerBuf.BufType_CIRCULAR;
        params.exitFlush// Flush log at system exit = Bool false;
        params.numEntries// Number of entries in buffer = Int 64;
per-instance creation
    var inst = LoggerBuf.create// Create an instance-object(params);
proxy LoggerBuf.TimestampProxy
index URL

User supplied time-stamp proxy

XDCscript usage meta-domain
LoggerBuf.TimestampProxy = ITimestampClient.Module null
// some delegate module inheriting the ITimestampClient interface
    LoggerBuf.TimestampProxy.delegate$ = ITimestampClient.Module null
    // explicit access to the currently bound delegate module
DETAILS
This proxy allows LoggerBuf to use a timestamp server different from the server used by xdc.runtime.Timestamp. However, if not supplied by a user, this proxy defaults to whichever timestamp server is used by Timestamp.
enum LoggerBuf.BufType
index URL

Type of log buffer

XDCscript usage meta-domain
values of type LoggerBuf.BufType
    const LoggerBuf.BufType_CIRCULAR;
    // The log buffer wraps, overwriting old entries
    const LoggerBuf.BufType_FIXED;
    // The log buffer halts collection when full
C SYNOPSIS
LoggerBuf_BufType
metaonly struct LoggerBuf.BasicView
index URL
XDCscript usage meta-domain
var obj = new LoggerBuf.BasicView;
    obj.label = String ...
    obj.lastSerial = Int ...
    obj.numEntries = Int ...
    obj.type = String ...
    obj.enabledFlag = Bool ...
metaonly struct LoggerBuf.RecordView
index URL
XDCscript usage meta-domain
var obj = new LoggerBuf.RecordView;
    obj.serial = Int ...
    obj.timestampRaw = Long ...
    obj.modName = String ...
    obj.text = String ...
    obj.eventId = Int ...
    obj.eventName = String ...
    obj.arg0 = IArg ...
    obj.arg1 = IArg ...
    obj.arg2 = IArg ...
    obj.arg3 = IArg ...
    obj.arg4 = IArg ...
    obj.arg5 = IArg ...
    obj.arg6 = IArg ...
    obj.arg7 = IArg ...
metaonly struct LoggerBuf.StopModeData
index URL

Data added to the RTA MetaData file to support stop mode RTA

XDCscript usage meta-domain
var obj = new LoggerBuf.StopModeData;
    obj.bufferSymbol = String ...
    obj.bufferSize = Int ...
config LoggerBuf.E_badLevel // module-wide
index URL

Error raised if get or setFilterLevel receives a bad level value

XDCscript usage meta-domain
LoggerBuf.E_badLevel = Error.Desc {
    msg: "E_badLevel: Bad filter level value: %d"
};
C SYNOPSIS
LoggerBuf_E_badLevel
config LoggerBuf.enableFlush // module-wide
index URL

Flush all logs at system exit

XDCscript usage meta-domain
LoggerBuf.enableFlush = Bool false;
C SYNOPSIS
LoggerBuf_enableFlush
config LoggerBuf.filterByLevel // module-wide
index URL

Support filtering of events by event level

XDCscript usage meta-domain
LoggerBuf.filterByLevel = Bool false;
DETAILS
To improve logging performance, this feature can be disabled by setting filterByLevel to false.
See 'setFilterLevel' for an explanation of level filtering.
C SYNOPSIS
LoggerBuf_filterByLevel
config LoggerBuf.level1Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL1

XDCscript usage meta-domain
LoggerBuf.level1Mask = Bits16 0;
DETAILS
See 'level4Mask' for details.
C SYNOPSIS
LoggerBuf_level1Mask
config LoggerBuf.level2Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL2

XDCscript usage meta-domain
LoggerBuf.level2Mask = Bits16 0;
DETAILS
See 'level4Mask' for details.
C SYNOPSIS
LoggerBuf_level2Mask
config LoggerBuf.level3Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL3

XDCscript usage meta-domain
LoggerBuf.level3Mask = Bits16 0;
DETAILS
See 'level4Mask' for details.
C SYNOPSIS
LoggerBuf_level3Mask
config LoggerBuf.level4Mask // module-wide
index URL

Mask of diags categories whose initial filtering level is Diags.LEVEL4

XDCscript usage meta-domain
LoggerBuf.level4Mask = Bits16 Diags.ALL_LOGGING;
DETAILS
If IFilterLogger.filterByLevel is true, then all LoggerBuf instances will filter incoming events based on their event level.
The LoggerBuf module allows for specifying a different filter level for every Diags bit. These filtering levels are module wide; LoggerBuf does not support specifying the levels on a per-instance basis.
The IFilterLogger.setFilterLevel function can be used to change the filtering levels at runtime.
The default filtering levels are assigned using the level1Mask - level4Mask config parameters. These are used to specify, for each of the four event levels, the set of bits which should filter at that level by default.
The default filtering configuration sets the filter level to Diags.LEVEL4 for all logging-related diags bits so that all events are logged by default.
C SYNOPSIS
LoggerBuf_level4Mask
config LoggerBuf.statusLogger // module-wide
index URL

Route all 'STATUS' (error and warning) events to this logger

XDCscript usage meta-domain
LoggerBuf.statusLogger = ILogger.Handle null;
DETAILS
If a statusLogger is specified, all LoggerBuf instances will check to determine if any of the events they receive are errors or warnings (if their diags mask includes the STATUS category), and will log these events to the statusLogger.
Error events are infrequent, but it's generally critical that they be seen. In a typical system, non-error events easily outnumber any error events, and the logger is likely to wrap, overwriting any error events. To protect these events from being overwritten and lost, they can be sent to their own separate logger to preserve them.
The default value is null, indicating that the STATUS events will just be logged by the logger they were sent to.
C SYNOPSIS
LoggerBuf_statusLogger
metaonly config LoggerBuf.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
LoggerBuf.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly LoggerBuf.getMetaArgs() // module-wide
index URL

Returns any meta data needed to support RTA

XDCscript usage meta-domain
LoggerBuf.getMetaArgs(Any inst, Any instNum) returns Any
DETAILS
This meta data should be returned in the form of a structure which can be converted into XML. This data is added to the RTA XML file during the application's configuration, and can be accessed later through the xdc.rta.MetaData module.
The MetaData is returned per instance of the ILogger module. The instance object is passed to the function as the first argument.
The second argument is the index of the instance in the list of the ILogger's static instances.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
// Instance config-params object
    params.bufHeap = IHeap.Handle null;
    // The heap that contains the Log buffer for dynamic instances
    params.bufSection = String null;
    // Section name for the buffer managed by the static instance
    params.bufType = LoggerBuf.BufType LoggerBuf.BufType_CIRCULAR;
    // Log buffer type
    params.exitFlush = Bool false;
    // Flush log at system exit
    params.numEntries = Int 64;
    // Number of entries in buffer
config LoggerBuf.bufHeap // instance
index URL

The heap that contains the Log buffer for dynamic instances

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
...
params.bufHeap = IHeap.Handle null;
DETAILS
The default value null means the buffer will be allocated from the Memory.defaultHeapInstance heap.
C SYNOPSIS
null
config LoggerBuf.bufType // instance
index URL

Log buffer type

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
...
params.bufType = LoggerBuf.BufType LoggerBuf.BufType_CIRCULAR;
C SYNOPSIS
null
config LoggerBuf.exitFlush // instance
index URL

Flush log at system exit

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
...
params.exitFlush = Bool false;
DETAILS
Only used when module parameter enableFlush is true.
C SYNOPSIS
null
config LoggerBuf.numEntries // instance
index URL

Number of entries in buffer

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
...
params.numEntries = Int 64;
DETAILS
Each entry is large enough to store one Log event containing up to 4 optional arguments. Events containing more than 4 arguments (such as those from Log.write5) use 2 entries.
numEntries must be a power of 2.
C SYNOPSIS
null
metaonly config LoggerBuf.bufSection // instance
index URL

Section name for the buffer managed by the static instance

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
...
params.bufSection = String null;
DETAILS
The default section is the 'dataSection' in the platform.
Instance Creation
index URL

XDCscript usage meta-domain
var params = new LoggerBuf.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = LoggerBuf.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
SEE
LoggerBuf.Params
generated on Fri, 17 Jun 2011 00:24:32 GMT


module xdc.runtime.LoggerSys
index URL

A logger which routes events to the System_printf function

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
This logger processes log events as they are generated and routes them through the System_printf() function. The final disposition of the log event is dependent on which system provider has been assigned to the System.SupportProxy configuration parameter. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/LoggerSys.xdc
#include <xdc/runtime/LoggerSys.h>
Functions
Void | LoggerSys_construct// Initialize a new instance object inside the provided structure(LoggerSys_Struct *structP, const LoggerSys_Params *params);
LoggerSys_Handle | LoggerSys_create// Allocate and initialize a new instance object and return its handle(const LoggerSys_Params *params, Error_Block *eb);
Void | LoggerSys_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(LoggerSys_Handle *handleP);
Void | LoggerSys_destruct// Finalize the instance object inside the provided structure(LoggerSys_Struct *structP);
Void | LoggerSys_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LoggerSys_Params *params);
Functions common to all ILogger modules
Bool | LoggerSys_disable// Disable a log(LoggerSys_Handle handle);
Bool | LoggerSys_enable// Enable a log(LoggerSys_Handle handle);
Void | LoggerSys_write0// Process a log event with 0 arguments(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid);
Void | LoggerSys_write1// Process a log event with 1 arguments(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
Void | LoggerSys_write2// Process a log event with 2 arguments(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
Void | LoggerSys_write4// Process a log event with up to 4 arguments(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
Void | LoggerSys_write8// Process a log event with up to 8 arguments(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Functions common to all target instances
 | LoggerSys_handle// Convert this instance structure pointer into an instance handle, LoggerSys_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, LoggerSys_Handle_label// The label associated with this instance object, LoggerSys_Handle_name// The name of this instance object, LoggerSys_Handle_upCast// unconditionally move one level up the inheritance hierarchy, LoggerSys_Object_count// The number of statically-created instance objects, LoggerSys_Object_first// The handle of the first dynamically-created instance object, or NULL, LoggerSys_Object_get// The handle of the i-th statically-created instance object (array == NULL), LoggerSys_Object_heap// The heap used to allocate dynamically-created instance objects, LoggerSys_Object_next// The handle of the next dynamically-created instance object, or NULL, LoggerSys_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | LoggerSys_Module_getMask// Returns the diagnostics mask for this module, LoggerSys_Module_hasMask// Test whether this module has a diagnostics mask, LoggerSys_Module_heap// The heap from which this module allocates memory, LoggerSys_Module_id// Get this module's unique id, LoggerSys_Module_setMask// Set the diagnostics mask for this module, LoggerSys_Module_startupDone// Test if this module has completed startup
Typedefs
typedef LoggerSys_Object * | LoggerSys_Handle// Client reference to an instance object;
typedef struct | LoggerSys_Object// Opaque internal representation of an instance object LoggerSys_Object;
typedef struct | LoggerSys_Params// Instance config-params structure ...
typedef struct | LoggerSys_Struct// Opaque client structure large enough to hold an instance object LoggerSys_Struct;
DETAILS
This logger processes log events as they are generated and routes them through the System_printf() function. The final disposition of the log event is dependent on which system provider has been assigned to the System.SupportProxy configuration parameter.
Note that the log events are processed within the runtime context of the Log_write() or Log_print() function that generated the event. It is important to account for the processing overhead and stack usage imposed on the runtime context. The cost of this processing is defined by the implementation of the system provider.
EXAMPLES
Configuration example: The following XDC configuration statements create a logger instance, assign it as the default logger for all modules, and enable USER1 logging in all modules of the package my.pkg. See the Diags.setMaskMeta() function for details on specifying the module names.
  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');

  var LoggerSysParams = new LoggerSys.Params();
  Defaults.common$.logger = LoggerSys.create(LoggerSysParams);
  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId LoggerSys_Module_id();
// Get this module's unique id
Bool LoggerSys_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle LoggerSys_Module_heap();
// The heap from which this module allocates memory
Bool LoggerSys_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 LoggerSys_Module_getMask();
// Returns the diagnostics mask for this module
Void LoggerSys_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct LoggerSys_Object LoggerSys_Object;
// Opaque internal representation of an instance object
typedef LoggerSys_Object *LoggerSys_Handle;
// Client reference to an instance object
typedef struct LoggerSys_Struct LoggerSys_Struct;
// Opaque client structure large enough to hold an instance object
LoggerSys_Handle LoggerSys_handle(LoggerSys_Struct *structP);
// Convert this instance structure pointer into an instance handle
LoggerSys_Struct *LoggerSys_struct(LoggerSys_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct LoggerSys_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} LoggerSys_Params;
Void LoggerSys_Params_init(LoggerSys_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
LoggerSys_Handle LoggerSys_create(const LoggerSys_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void LoggerSys_construct(LoggerSys_Struct *structP, const LoggerSys_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
The logger instance will route all log events it receives to the System.printf function.
Instance Deletion
index URL

C synopsis target-domain
Void LoggerSys_delete(LoggerSys_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void LoggerSys_destruct(LoggerSys_Struct *structP);
// Finalize the instance object inside the provided structure
LoggerSys_disable() // instance
index URL

Disable a log

C synopsis target-domain
Bool LoggerSys_disable(LoggerSys_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
DETAILS
Events written to a disabled log are silently discarded.
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
LoggerSys_enable() // instance
index URL

Enable a log

C synopsis target-domain
Bool LoggerSys_enable(LoggerSys_Handle handle);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
RETURNS
The function returns the state of the log (TRUE if enabled, FALSE if disabled) before the call. This return value allows clients to restore the previous state. Note: not thread safe.
LoggerSys_write0() // instance
index URL

Process a log event with 0 arguments

C synopsis target-domain
Void LoggerSys_write0(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
DETAILS
Same as write4 except with 0 arguments rather than 4.
SEE
ILogger.write4()
LoggerSys_write1() // instance
index URL

Process a log event with 1 arguments

C synopsis target-domain
Void LoggerSys_write1(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
DETAILS
Same as write4 except with 1 arguments rather than 4.
SEE
ILogger.write4()
LoggerSys_write2() // instance
index URL

Process a log event with 2 arguments

C synopsis target-domain
Void LoggerSys_write2(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
DETAILS
Same as write4 except with 2 arguments rather than 4.
SEE
ILogger.write4()
LoggerSys_write4() // instance
index URL

Process a log event with up to 4 arguments

C synopsis target-domain
Void LoggerSys_write4(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
evt — event to be logged
mid — module ID of the module which logged the event
a1 — arbitrary argument passed by caller
DETAILS
The evt argument is of type Log.Event, which encodes the Log.EventId, the Diags.Mask, and the Diags.EventLevel of the event. The event ID can be obtained via Types.getEventId(evt), the Diags mask can be obtained via Diags.getMask(evt), and the event level can be obtained via Diags.getLevel(evt).
The modId argument is the module ID of the module that logged the event.
The event information can be used by the logger to handle different events specially. For example, the event ID can be used to compare against other known Log.Events.
      if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
          :
      }
The Diags mask and event level can be used for filtering of events based on event level (see IFilterLogger), or even routing events to separate loggers based on diags category (see, for example, LoggerBuf.statusLogger).
The Diags mask and event level are useful for handling the event, but are generally not recorded by the logger because they are not needed in decoding and displaying the event. A more suitable value to record is a Types.Event, which encodes the event ID and module ID. For example, the Log.EventRec type stores a Types.Event in its record definition. A Types.Event can be created using the Types.makeEvent API given the event ID and module ID.
The event ID value of 0 is used to indicate an event triggered by a call to one of the Log_print[0-6] methods. These methods take a format string rather than a Log_Event argument and, as a result, the event ID encoded in evt is 0 and the parameter a1 is the format string.
Non-zero event IDs can also be used to access the msg string associated with the Log.EventDesc that originally defined the Log event.
      Log_EventId id = Log_getEventId(evt));
      if (id != 0) {
          String msg = Text_ropeText(id);
          System_aprintf(msg, a1, a2, a3, a4);
      }
This works because an event's ID is simply an offset into a table of characters (maintained by the Text module) containing the event's msg string.
The arguments a1, a2, etc. are parameters that are to be interpreted according to the message format string associated with evt.
SEE
Log.Event, Log.EventDesc, Text.ropeText, Log.getEventId
LoggerSys_write8() // instance
index URL

Process a log event with up to 8 arguments

C synopsis target-domain
Void LoggerSys_write8(LoggerSys_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
ARGUMENTS
handle — handle of a previously-created LoggerSys instance object
DETAILS
Same as write4 except with 8 arguments rather than 4.
SEE
ILogger.write4()
Instance Convertors
index URL

C synopsis target-domain
ILogger_Handle LoggerSys_Handle_upCast(LoggerSys_Handle handle);
// unconditionally move one level up the inheritance hierarchy
LoggerSys_Handle LoggerSys_Handle_downCast(ILogger_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int LoggerSys_Object_count();
// The number of statically-created instance objects
LoggerSys_Handle LoggerSys_Object_get(LoggerSys_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
LoggerSys_Handle LoggerSys_Object_first();
// The handle of the first dynamically-created instance object, or NULL
LoggerSys_Handle LoggerSys_Object_next(LoggerSys_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle LoggerSys_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *LoggerSys_Handle_label(LoggerSys_Handle handle, Types_Label *buf);
// The label associated with this instance object
String LoggerSys_Handle_name(LoggerSys_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/LoggerSys.xdc
var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
local proxy modules
     LoggerSys.TimestampProxy// User supplied time-stamp proxy = ITimestampClient.Module null
         LoggerSys.TimestampProxy.delegate$ = ITimestampClient.Module null
module-wide config parameters
     LoggerSys.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     LoggerSys.getMetaArgs// Returns any meta data needed to support RTA(Any inst, Any instNum) returns Any
per-instance config parameters
    var params = new LoggerSys.Params// Instance config-params object;
per-instance creation
    var inst = LoggerSys.create// Create an instance-object(params);
proxy LoggerSys.TimestampProxy
index URL

User supplied time-stamp proxy

XDCscript usage meta-domain
LoggerSys.TimestampProxy = ITimestampClient.Module null
// some delegate module inheriting the ITimestampClient interface
    LoggerSys.TimestampProxy.delegate$ = ITimestampClient.Module null
    // explicit access to the currently bound delegate module
DETAILS
This proxy allows LoggerSys to use a timestamp server different from the server used by xdc.runtime.Timestamp. However, if not supplied by a user, this proxy defaults to whichever timestamp server is used by Timestamp.
metaonly config LoggerSys.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
LoggerSys.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly LoggerSys.getMetaArgs() // module-wide
index URL

Returns any meta data needed to support RTA

XDCscript usage meta-domain
LoggerSys.getMetaArgs(Any inst, Any instNum) returns Any
DETAILS
This meta data should be returned in the form of a structure which can be converted into XML. This data is added to the RTA XML file during the application's configuration, and can be accessed later through the xdc.rta.MetaData module.
The MetaData is returned per instance of the ILogger module. The instance object is passed to the function as the first argument.
The second argument is the index of the instance in the list of the ILogger's static instances.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new LoggerSys.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new LoggerSys.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = LoggerSys.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
The logger instance will route all log events it receives to the System.printf function.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Main
index URL

Configuration "stand-in" for application code

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module is used to enable "module" configuration of application code that is not part of a module. Configuration of this Main module is used for all code not in a module. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Main.xdc
#include <xdc/runtime/Main.h>
Functions common to all target modules
Main_Module_getMask// Returns the diagnostics mask for this module, Main_Module_hasMask// Test whether this module has a diagnostics mask, Main_Module_heap// The heap from which this module allocates memory, Main_Module_id// Get this module's unique id, Main_Module_setMask// Set the diagnostics mask for this module, Main_Module_startupDone// Test if this module has completed startup
DETAILS
This module is used to enable "module" configuration of application code that is not part of a module. Configuration of this Main module is used for all code not in a module.
For example, an ILogger "service provider" for all code that is not in a RTSC module can be configured by setting this module's logger; when code that is not in a module calls Log_print(), for example, this module's ILogger handles the event.
Since this module is "gated", the user can also assign a gate to this module for use by any code that is not in a module. This gate can be used to serialize access to global data by multiple threads in the system.
      #include <xdc/runtime/Main.h>
      #include <xdc/runtime/Gate.h>
          :
      int global = 0;
      int main() {
          :       // create a bunch of threads
      }

      void thread() {
          IArg key = Gate_enterModule();  // enter critical section
          global++;                       // safely update global data
          Gate_leaveModule(key);          // leave critical section
      }
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Main_Module_id();
// Get this module's unique id
Bool Main_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Main_Module_heap();
// The heap from which this module allocates memory
Bool Main_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Main_Module_getMask();
// Returns the diagnostics mask for this module
Void Main_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Main.xdc
var Main = xdc.useModule('xdc.runtime.Main');
module-wide config parameters
     Main.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config Main.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Main.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Memory
index URL

Static and run-time memory manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
All memory allocations are executed via staticPlace() at the config time or through Memory_alloc() (or Memory_calloc() or Memory_valloc()) at run-time. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Memory.xdc
#include <xdc/runtime/Memory.h>
Functions
Ptr | Memory_alloc// Allocate a block of memory from a heap(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
Ptr | Memory_calloc// Allocate a block of memory from a heap and zero out the contents(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
Void | Memory_free// Frees the space if the heap manager offers such functionality(IHeap_Handle heap, Ptr block, SizeT size);
SizeT | Memory_getMaxDefaultTypeAlign// Return the largest alignment required by the target();
Void | Memory_getStats// Obtain statistics from a heap(IHeap_Handle heap, Memory_Stats *stats);
Bool | Memory_query// Test for a particular xdc.runtime.IHeap quality(IHeap_Handle heap, Int qual);
Ptr | Memory_valloc// Allocate a block of memory from a heap and initialize the contents to the value specified(IHeap_Handle heap, SizeT size, SizeT align, Char value, Error_Block *eb);
Functions common to all target modules
 | Memory_Module_getMask// Returns the diagnostics mask for this module, Memory_Module_hasMask// Test whether this module has a diagnostics mask, Memory_Module_heap// The heap from which this module allocates memory, Memory_Module_id// Get this module's unique id, Memory_Module_setMask// Set the diagnostics mask for this module, Memory_Module_startupDone// Test if this module has completed startup
Defines
#define | Memory_Q_BLOCKING// Blocking quality (Int)1
Typedefs
typedef UArg | Memory_Size// Type to be used to specify heap buffer sizes;
typedef struct | Memory_Stats// Memory heap statistics ...
Constants
extern const IHeap_Handle | Memory_defaultHeapInstance// The default heap;
DETAILS
All memory allocations are executed via staticPlace() at the config time or through Memory_alloc() (or Memory_calloc() or Memory_valloc()) at run-time.
The actual memory management is performed by modules that implement xdc.runtime.IHeap. Heap instances are created statically or dynamically via the heap specific create functions and these instances are then passed as input parameters to the Memory calls with xdc.runtime.IHeap.Handle parameters.
const Memory_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define Memory_Q_BLOCKING (Int)1
DETAILS
xdc.runtime.IHeaps with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
typedef Memory_Size
index URL

Type to be used to specify heap buffer sizes

C synopsis target-domain
typedef UArg Memory_Size;
struct Memory_Stats
index URL

Memory heap statistics

C synopsis target-domain
typedef struct Memory_Stats {
     Memory_Size totalSize;
     Memory_Size totalFreeSize;
     Memory_Size largestFreeSize;
} Memory_Stats;
FIELDS
totalSize — total size (in MADUs) of heap.
totalFreeSize — current size (in MADUs) of free memory in the heap
largestFreeSize — current largest contiguous free block (in MADUs)
DETAILS
This structure defines generic statistics that must be supplied by each module that implements the xdc.runtime.IHeap interface.
config Memory_defaultHeapInstance // module-wide
index URL

The default heap

C synopsis target-domain
extern const IHeap_Handle Memory_defaultHeapInstance;
DETAILS
If no heap is specified in the Memory module's methods (i.e. heap == NULL) defaultHeapInstance is used. If defaultHeapInstance is not set (or set to null), a xdc.runtime.HeapStd heap instance is created and assigned to this configuration parameter. The size of the heap is determined by the defaultHeapSize parameter.
By default, all modules are configured with a null instance heap. Instances created by modules with a null instance heap are allocated from the defaultHeapInstance heap.
Memory_alloc() // module-wide
index URL

Allocate a block of memory from a heap

C synopsis target-domain
Ptr Memory_alloc(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_alloc() returns non-NULL pointer to the allocated and uninitialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
Memory_calloc() // module-wide
index URL

Allocate a block of memory from a heap and zero out the contents

C synopsis target-domain
Ptr Memory_calloc(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_calloc() returns non-NULL pointer to the allocated and initialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
Memory_free() // module-wide
index URL

Frees the space if the heap manager offers such functionality

C synopsis target-domain
Void Memory_free(IHeap_Handle heap, Ptr block, SizeT size);
ARGUMENTS
heap — heap that the block of memory will be freed back to.
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
block — block of memory to free back to the heap
size — size (in MADUs) of the block of memory to free.
Memory_getMaxDefaultTypeAlign() // module-wide
index URL

Return the largest alignment required by the target

C synopsis target-domain
SizeT Memory_getMaxDefaultTypeAlign();
DETAILS
getMaxDefaultTypeAlign returns the largest alignment required for all the standard base types supported by the current configuration's target (Program.build.target)
This is the runtime version of the getMaxDefaultTypeAlignMeta function.
RETURNS
Returns target-specific alignment in MADUs.
SEE
getMaxDefaultTypeAlignMeta
Memory_getStats() // module-wide
index URL

Obtain statistics from a heap

C synopsis target-domain
Void Memory_getStats(IHeap_Handle heap, Memory_Stats *stats);
ARGUMENTS
heap — the heap to get the statistics from
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
stats — the output buffer for the returned statistics
Memory_query() // module-wide
index URL

Test for a particular xdc.runtime.IHeap quality

C synopsis target-domain
Bool Memory_query(IHeap_Handle heap, Int qual);
ARGUMENTS
heap — the heap to query
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is queried
qual — quality to test
For example: Q_BLOCKING.
DETAILS
There currently is only one quality, namely Q_BLOCKING.
RETURNS
If heap has the qual quality, this method returns TRUE, otherwise it returns FALSE.
Memory_valloc() // module-wide
index URL

Allocate a block of memory from a heap and initialize the contents to the value specified

C synopsis target-domain
Ptr Memory_valloc(IHeap_Handle heap, SizeT size, SizeT align, Char value, Error_Block *eb);
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
value — value to initialize the contents of the block
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_valloc() returns non-NULL pointer to the allocated and initialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Memory_Module_id();
// Get this module's unique id
Bool Memory_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Memory_Module_heap();
// The heap from which this module allocates memory
Bool Memory_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Memory_Module_getMask();
// Returns the diagnostics mask for this module
Void Memory_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Memory.xdc
var Memory = xdc.useModule('xdc.runtime.Memory');
module-wide constants & types
    const Memory.Q_BLOCKING// Blocking quality = 1;
    var obj = new Memory.Stats// Memory heap statistics;
        obj.totalSize = UArg ...
        obj.totalFreeSize = UArg ...
        obj.largestFreeSize = UArg ...
module-wide config parameters
     Memory.defaultHeapInstance// The default heap = IHeap.Handle undefined;
     Memory.common$// Common module configuration parameters = Types.Common$ undefined;
     Memory.defaultHeapSize// The size (in target MADUs) of the defaultHeapInstance = Int 0x1000;
module-wide functions
     Memory.getMaxDefaultTypeAlignMeta// Return the largest alignment required by the target() returns SizeT
     Memory.staticPlace// Statically places buffers(Any obj, SizeT align, String section) returns Bool
const Memory.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const Memory.Q_BLOCKING = 1;
DETAILS
xdc.runtime.IHeaps with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
Memory_Q_BLOCKING
struct Memory.Stats
index URL

Memory heap statistics

XDCscript usage meta-domain
var obj = new Memory.Stats;
    obj.totalSize = UArg ...
    obj.totalFreeSize = UArg ...
    obj.largestFreeSize = UArg ...
FIELDS
totalSize — total size (in MADUs) of heap.
totalFreeSize — current size (in MADUs) of free memory in the heap
largestFreeSize — current largest contiguous free block (in MADUs)
DETAILS
This structure defines generic statistics that must be supplied by each module that implements the xdc.runtime.IHeap interface.
C SYNOPSIS
Memory_Stats
config Memory.defaultHeapInstance // module-wide
index URL

The default heap

XDCscript usage meta-domain
Memory.defaultHeapInstance = IHeap.Handle undefined;
DETAILS
If no heap is specified in the Memory module's methods (i.e. heap == NULL) defaultHeapInstance is used. If defaultHeapInstance is not set (or set to null), a xdc.runtime.HeapStd heap instance is created and assigned to this configuration parameter. The size of the heap is determined by the defaultHeapSize parameter.
By default, all modules are configured with a null instance heap. Instances created by modules with a null instance heap are allocated from the defaultHeapInstance heap.
C SYNOPSIS
Memory_defaultHeapInstance
metaonly config Memory.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Memory.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Memory.defaultHeapSize // module-wide
index URL

The size (in target MADUs) of the defaultHeapInstance

XDCscript usage meta-domain
Memory.defaultHeapSize = Int 0x1000;
DETAILS
This parameters is used when the defaultHeapInstance is not configured.
metaonly Memory.getMaxDefaultTypeAlignMeta() // module-wide
index URL

Return the largest alignment required by the target

XDCscript usage meta-domain
Memory.getMaxDefaultTypeAlignMeta() returns SizeT
DETAILS
This method scans the standard base types supported by the current configuration's target (Program.build.target) and returns the largest alignment required for these types.
RETURNS
Returns target-specific alignment in MADUs.
SEE
xdc.bld.ITarget.stdTypes
metaonly Memory.staticPlace() // module-wide
index URL

Statically places buffers

XDCscript usage meta-domain
Memory.staticPlace(Any obj, SizeT align, String section) returns Bool
ARGUMENTS
obj — object to place
This object always has the length property; obj.length determines the size of the allocated buffer for obj
align — the alignment required by obj
section — section name to contain obj
This parameter names the section where obj will be placed. If this parameter is null, no explicit placement is done.
DETAILS
This function places the object specified by obj into the specified memory section. The section string is a target-specific name that is interpreted by the underlying target tool-chain. In the case of TI tool-chains, this section can be a subsection (e.g. ".data:someSection").
The amount of memory that is created for obj is dependent on its size and the value of the property length. The length (number of elements in an array) is set before the staticPlace() is called. For example, setting obj.length = 5; before calling staticPlace(), will create 5 * sizeof (obj) MADUs of memory.
If 0 is specified for the alignment, the allocated buffer is aligned as determined by the target toolchain. For instance, if obj is an array of structs that have only 16-bit integers, the alignment would be on a 16-bit boundary.
All non-zero alignments must be a power of 2. Not all targets support directives that allow one to specify alignment. The readonly config parameter Program.build.target.alignDirectiveSupported can be used to determine if the target supports alignment directives.
RETURNS
Returns false if the alignment request cannot be honored. The obj is still placed regardless of the return code.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Registry
index URL

Register modules that are not statically configured

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides a mechanism by which legacy C code can have its own module logging support, including having a name and its own diags mask. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Registry.xdc
#include <xdc/runtime/Registry.h>
Functions
Registry_Result | Registry_addModule// Add a runtime module to the registry with the specified name(Registry_Desc *desc, String modName);
Registry_Desc * | Registry_findById// Find registered module's descriptor from it's module ID(Types_ModuleId mid);
Registry_Desc * | Registry_findByName// Find the registered module with the given name(String modName);
Bool | Registry_getMask// Get the specified module's diagnostic mask(String name, Types_DiagsMask *mask);
Types_ModuleId | Registry_getModuleId// Get the module id associated with a specified module descriptor(Registry_Desc *desc);
String | Registry_getModuleName// Get the module name associated with a specified module descriptor(Registry_Desc *desc);
Registry_Desc * | Registry_getNextModule// Scan the current list of registered modules(Registry_Desc *desc);
Bool | Registry_isMember// Determines if the specified module ID belongs to a registered module(Types_ModuleId mid);
Functions common to all target modules
 | Registry_Module_getMask// Returns the diagnostics mask for this module, Registry_Module_hasMask// Test whether this module has a diagnostics mask, Registry_Module_heap// The heap from which this module allocates memory, Registry_Module_id// Get this module's unique id, Registry_Module_setMask// Set the diagnostics mask for this module, Registry_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Types_RegDesc | Registry_Desc// Registry module descriptor;
typedef enum | Registry_Result// Status codes ...
DETAILS
This module provides a mechanism by which legacy C code can have its own module logging support, including having a name and its own diags mask.
Without the Registry, all logging done by legacy C code is handled by the xdc.runtime.Main module. This means that all Log events will be marked as coming from "xdc.runtime.Main", and there is only a single diagnostics mask for the runtime control of logging across all legacy C code. The Registry module allows legacy C code to have the same granular control over logging as statically defined RTSC modules.
To use the Registry module, legacy code must define the symbol Registry_CURDESC to be the name of an externally declared Registery_Desc structure. This symbol must be defined before the inclusion of any xdc/runtime header files. If any xdc/runtime header files are included before the definition of this symbol, the Registry module may not function properly.
Note: by defining this symbol on the compile line, rather than in the file, one can easily compile code to be used in one of two environments:
  1. a fixed configuration environment where modules are registered via Registry_addModule(), or
  2. a "normal" configurable environment in which this code is assumed to be part of the Main module.
The Registry_Desc structure must then be registered by calling Registry_addModule(). The structure is typically registered and initialized within main().
For example:
  //Define the required symbol, Registry_CURDESC, to this file's
  //Registry_Desc object
  #define Registry_CURDESC    mainDesc
  #include <xdc/runtime/Registry.h>

  //Declare the Registry_Desc object, the name is unimportant
  Registry_Desc mainDesc;

  Int main(Int argc, String argv[]) {

  //Register this file as a module "main"
  Registry_addModule(&mainDesc, "main");
Once registered, the legacy code may call Log APIs without any other change and the formatted Log events will show as coming from the registered modules. Also, the logging by the legacy code is now filtered by its own diagnostic mask. The bits of this mask can be set using Diags_setMask.
Continuing the previous example:
  //Initialize the legacy code's diags mask to enable USER1.
  Diags_setMask("main=1");
All events logged registered modules will be sent to the logger configured for the Registry module. For example, to configure the logger for use by all modules managed by Registry:
  Registry.common$.logger = LoggerBuf.create();
Since the registered modules are not known until runtime, it is not possible to statically configure the diagnostics masks for individual registered modules. However, it is possible to configure diagnostics categories to be permanently off or on for ALL registered modules. This is done by configuring the diagnostic mask for the Registry module. Diagnostic categories set to Diags.ALWAYS_OFF will be permanently off for all Registry modules. Categories set to Diags.ALWAYS_ON will be permanently on for all modules managed by Registry.
In order to enable runtime configuration of individual Registry module masks, all relevant diagnostic categories must be set to Diags.RUNTIME_OFF or Diags.RUNTIME_ON in the Registry module's mask.
enum Registry_Result
index URL

Status codes

C synopsis target-domain
typedef enum Registry_Result {
    Registry_SUCCESS,
    // The module was added successfully
    Registry_ALLOC_FAILED,
    // reserved
    Registry_ALREADY_ADDED,
    // The module has already been added or another module with the same name is present
    Registry_ALL_IDS_USED
    // No more module ids available for new modules
} Registry_Result;
typedef Registry_Desc
index URL

Registry module descriptor

C synopsis target-domain
typedef Types_RegDesc Registry_Desc;
Registry_addModule() // module-wide
index URL

Add a runtime module to the registry with the specified name

C synopsis target-domain
Registry_Result Registry_addModule(Registry_Desc *desc, String modName);
ARGUMENTS
desc — non-NULL pointer to a {#Desc Registry_Desc} structure.
modName — non-NULL string name of the module being registered.
DETAILS
The desc parameter and the modName string provided must both be permanent since the Registry will maintain references to both of these.
RETURNS
Registry_addModule returns one of the following Result status values indicating success or the cause of failure:
  • SUCCESS
  • ALREADY_ADDED
  • ALL_IDS_USED There are a total of 16,384 - 1 module ids available for use by Registry.
Registry_findById() // module-wide
index URL

Find registered module's descriptor from it's module ID

C synopsis target-domain
Registry_Desc *Registry_findById(Types_ModuleId mid);
ARGUMENTS
mid — any module id
RETURNS
If the ID mid is registered via Registry_addModule(), this function returns the pointer to the registered Registry_Desc structure; otherwise it returns NULL.
Registry_findByName() // module-wide
index URL

Find the registered module with the given name

C synopsis target-domain
Registry_Desc *Registry_findByName(String modName);
ARGUMENTS
modName — non-NULL string name of a registered module
RETURNS
If the name modName is registered via Registry_addModule(), this function returns the pointer to the registered Registry_Desc structure; otherwise it returns NULL.
Registry_getMask() // module-wide
index URL

Get the specified module's diagnostic mask

C synopsis target-domain
Bool Registry_getMask(String name, Types_DiagsMask *mask);
ARGUMENTS
modName — non-NULL string name of a registered module
mask — non-NULL pointer to a mask to be initialized to the the current state of the diagnostics mask associated with modName
RETURNS
The function returns TRUE if name identifies a registered module; otherwise, it return FALSE.
Registry_getModuleId() // module-wide
index URL

Get the module id associated with a specified module descriptor

C synopsis target-domain
Types_ModuleId Registry_getModuleId(Registry_Desc *desc);
ARGUMENTS
desc — non-NULL pointer to a {#Desc Registry_Desc} structure.
RETURNS
If the specified module descriptor has been initialized via a successful call to Registry_addModule(), this function returns the module id assigned by Registry_addModule(); otherwise, its return value is indeterminate.
Registry_getModuleName() // module-wide
index URL

Get the module name associated with a specified module descriptor

C synopsis target-domain
String Registry_getModuleName(Registry_Desc *desc);
ARGUMENTS
desc — non-NULL pointer to a {#Desc Registry_Desc} structure.
RETURNS
If the specified module descriptor has been initialized via a successful call to Registry_addModule(), this function returns the module name passed Registry_addModule(); otherwise, its return value is indeterminate.
Registry_getNextModule() // module-wide
index URL

Scan the current list of registered modules

C synopsis target-domain
Registry_Desc *Registry_getNextModule(Registry_Desc *desc);
ARGUMENTS
desc — optionally NULL pointer to a Registry_Desc structure. If desc is NULL, a pointer to the first structure is returned. If desc is non-NULL and equal to a previous return value of this function, a pointer to the "next" Registry_Desc structure is returned.
DETAILS
This function used to scan the list of all Registry_Desc structures currently being managed by the Registry module.
RETURNS
This function returns a non-NULL pointer to one of the Registry_Desc structures added via Registry_Desc structures or NULL in the case that
  • there are no more module's in the list after desc, or
  • there are no modules registered
Registry_isMember() // module-wide
index URL

Determines if the specified module ID belongs to a registered module

C synopsis target-domain
Bool Registry_isMember(Types_ModuleId mid);
ARGUMENTS
mid — any module id
RETURNS
This function returns TRUE if and only if the specified module id is a valid Registry module id. It does not search registered module ids, but simply checks if the id is within the range of valid Registry module ids.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Registry_Module_id();
// Get this module's unique id
Bool Registry_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Registry_Module_heap();
// The heap from which this module allocates memory
Bool Registry_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Registry_Module_getMask();
// Returns the diagnostics mask for this module
Void Registry_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Registry.xdc
var Registry = xdc.useModule('xdc.runtime.Registry');
module-wide constants & types
    values of type Registry.Result// Status codes
        const Registry.SUCCESS// The module was added successfully;
        const Registry.ALLOC_FAILED// reserved;
        const Registry.ALREADY_ADDED// The module has already been added or another module with the same name is present;
        const Registry.ALL_IDS_USED// No more module ids available for new modules;
module-wide config parameters
     Registry.common$// Common module configuration parameters = Types.Common$ undefined;
enum Registry.Result
index URL

Status codes

XDCscript usage meta-domain
values of type Registry.Result
    const Registry.SUCCESS;
    // The module was added successfully
    const Registry.ALLOC_FAILED;
    // reserved
    const Registry.ALREADY_ADDED;
    // The module has already been added or another module with the same name is present
    const Registry.ALL_IDS_USED;
    // No more module ids available for new modules
C SYNOPSIS
Registry_Result
metaonly config Registry.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Registry.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Reset

metaonly module xdc.runtime.Reset
index URL

Startup reset function manager

  • DETAILS
  • WARNING
  • SEE
  • XDCscript usage
  • Individual elements
This module defines an initial reset function and can be used without requiring any other xdc.runtime module. The reset function is called as early as possible in the application startup and is intended for platform-specific hardware initialization. [ more ... ]
XDCscript usage meta-domain sourced in xdc/runtime/Reset.xdc
var Reset = xdc.useModule('xdc.runtime.Reset');
module-wide config parameters
     Reset.fxns// List of functions to call at reset = Startup.InitFxn[] [ ];
DETAILS
This module defines an initial reset function and can be used without requiring any other xdc.runtime module. The reset function is called as early as possible in the application startup and is intended for platform-specific hardware initialization.
The reset function sequentially calls each of the functions added to the fxns array starting from index 0. If Startup.resetFxn is defined, it is called before any of the functions defined by the fxns array.
By providing an array of startup functions, rather than a single function as {@ilnk Startup} does, modules that need very early initialization can simply add their initialization to the list of functions to be called without having to implement a "chaining" mechanism or requiring the user to implement and maintain an application reset function.
WARNING
The reset function is _not_ supported on all platforms and, as a result, you should never place any "portable" code that is required for your application in this function. Use the @{link Startup} module to define required application startup functions.
SEE
Startup
config Reset.fxns // module-wide
index URL

List of functions to call at reset

XDCscript usage meta-domain
Reset.fxns = Startup.InitFxn[] [ ];
DETAILS
This array defines the functions that will be executed by the reset initialization function (xdc_runtime_Startup_reset__I) _in addition to_ the function specified by @{link Startup#resetFxn}.
The following code fragment shows how to add the externally defined function myReset() to this array.
      var Reset = xdc.useModule("xdc.runtime.Reset");
      Reset.fxns[Reset.fxns.length++] = "&myReset";
WARNING
Although the functions specified in fxns[] are ordinary C functions, they are often called _before_ the C runtime is fully initialized; e.g., they may be called _before_ static variables are initialized. Reset functions should only assume that a minimal execution stack has initialized.
SEE
Startup.resetFxn
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Rta
index URL

The Rta module contains target and configuration code for providing RTA support

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The 'Command' enum defines the available control commands, and the 'CommandPacket' structure defines the format of commands received from the host. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Rta.xdc
#include <xdc/runtime/Rta.h>
Functions
Void | Rta_acknowledgeCmd// (Rta_ResponsePacket *resp);
Void | Rta_changePeriod// (Rta_ResponsePacket *resp, UArg period);
Void | Rta_disableLog// (Rta_ResponsePacket *resp, UArg log);
Void | Rta_enableLog// (Rta_ResponsePacket *resp, UArg log);
Void | Rta_getCpuSpeed// (Rta_ResponsePacket *resp);
Void | Rta_processCommand// Executes a command packet and prepares the response packet(Rta_CommandPacket *cmd, Rta_ResponsePacket *resp);
Void | Rta_readMask// (Rta_ResponsePacket *resp, UArg addr);
Void | Rta_resetLog// (Rta_ResponsePacket *resp, UArg log);
Void | Rta_writeMask// (Rta_ResponsePacket *resp, UArg addr, UArg val);
Functions common to all target modules
 | Rta_Module_getMask// Returns the diagnostics mask for this module, Rta_Module_hasMask// Test whether this module has a diagnostics mask, Rta_Module_heap// The heap from which this module allocates memory, Rta_Module_id// Get this module's unique id, Rta_Module_setMask// Set the diagnostics mask for this module, Rta_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Int | Rta_Command// Command ids;
typedef struct | Rta_CommandPacket// Structure of command received from host TODO - Either the types should be changed to 32-bits, or the packet size information should be added to the RTA XML file ...
typedef struct | Rta_ResponsePacket// Structure of response packet sent back to host ...
Constants
extern const Assert_Id | Rta_A_invalidLogger// Assert if logger id in control command is invalid;
extern const String | Rta_controlTransportClassName// The name of the xdc.rta.IControlTransport class to use;
extern const String | Rta_dataTransportClassName// The name of the xdc.rta.IDataTransport class to use;
extern const Error_Id | Rta_E_badCommand// Error raised if Agent receives an invalid command;
extern const Log_Event | Rta_LD_cmdRcvd// Logged when the Agent receives a command;
extern const Log_Event | Rta_LD_writeMask// Logged when a diags mask is changed;
DETAILS
The 'Command' enum defines the available control commands, and the 'CommandPacket' structure defines the format of commands received from the host.
All commands should send back a response, even if only to acknowledge receipt and completion of the command. The format of the response is defined by the 'ResponsePacket' structure.
The Rta_processCommand can be used to process commands received from a host to call the appropriate API. Alternatively, the individual APIs can be called if not all of the defined commands are used.
enum Rta_Command
index URL

Command ids

C synopsis target-domain
typedef Int Rta_Command;
enum {
    Rta_Command_READ_MASK,
    Rta_Command_WRITE_MASK,
    Rta_Command_LOGGER_OFF,
    Rta_Command_LOGGER_ON,
    Rta_Command_GET_CPU_SPEED,
    Rta_Command_RESET_LOGGER,
    Rta_Command_CHANGE_PERIOD,
    Rta_Command_START_TX,
    Rta_Command_STOP_TX
} ;
struct Rta_CommandPacket
index URL

Structure of command received from host TODO - Either the types should be changed to 32-bits, or the packet size information should be added to the RTA XML file

C synopsis target-domain
typedef struct Rta_CommandPacket {
     Rta_Command cmdId;
    UArg arg0;
    UArg arg1;
} Rta_CommandPacket;
struct Rta_ResponsePacket
index URL

Structure of response packet sent back to host

C synopsis target-domain
typedef struct Rta_ResponsePacket {
     Rta_Command cmdId;
    UArg resp0;
    UArg resp1;
} Rta_ResponsePacket;
config Rta_A_invalidLogger // module-wide
index URL

Assert if logger id in control command is invalid

C synopsis target-domain
extern const Assert_Id Rta_A_invalidLogger;
config Rta_E_badCommand // module-wide
index URL

Error raised if Agent receives an invalid command

C synopsis target-domain
extern const Error_Id Rta_E_badCommand;
config Rta_LD_cmdRcvd // module-wide
index URL

Logged when the Agent receives a command

C synopsis target-domain
extern const Log_Event Rta_LD_cmdRcvd;
config Rta_LD_writeMask // module-wide
index URL

Logged when a diags mask is changed

C synopsis target-domain
extern const Log_Event Rta_LD_writeMask;
config Rta_controlTransportClassName // module-wide
index URL

The name of the xdc.rta.IControlTransport class to use

C synopsis target-domain
extern const String Rta_controlTransportClassName;
DETAILS
The class specified here can be used on the host for communicating with this target application to send control commands and receive responses.
config Rta_dataTransportClassName // module-wide
index URL

The name of the xdc.rta.IDataTransport class to use

C synopsis target-domain
extern const String Rta_dataTransportClassName;
DETAILS
The class specified here can be used on the host for reading RTA data from this target application.
Rta_acknowledgeCmd() // module-wide
index URL
C synopsis target-domain
Void Rta_acknowledgeCmd(Rta_ResponsePacket *resp);
Rta_changePeriod() // module-wide
index URL
C synopsis target-domain
Void Rta_changePeriod(Rta_ResponsePacket *resp, UArg period);
Rta_disableLog() // module-wide
index URL
C synopsis target-domain
Void Rta_disableLog(Rta_ResponsePacket *resp, UArg log);
Rta_enableLog() // module-wide
index URL
C synopsis target-domain
Void Rta_enableLog(Rta_ResponsePacket *resp, UArg log);
Rta_getCpuSpeed() // module-wide
index URL
C synopsis target-domain
Void Rta_getCpuSpeed(Rta_ResponsePacket *resp);
Rta_processCommand() // module-wide
index URL

Executes a command packet and prepares the response packet

C synopsis target-domain
Void Rta_processCommand(Rta_CommandPacket *cmd, Rta_ResponsePacket *resp);
ARGUMENTS
cmd — The CommandPacket to execute.
resp — The ResponsePacket to populate with the response.
DETAILS
This API will execute the command specified by the command packet argument, and will store the response information in the response packet argument.
Rta_readMask() // module-wide
index URL
C synopsis target-domain
Void Rta_readMask(Rta_ResponsePacket *resp, UArg addr);
Rta_resetLog() // module-wide
index URL
C synopsis target-domain
Void Rta_resetLog(Rta_ResponsePacket *resp, UArg log);
Rta_writeMask() // module-wide
index URL
C synopsis target-domain
Void Rta_writeMask(Rta_ResponsePacket *resp, UArg addr, UArg val);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Rta_Module_id();
// Get this module's unique id
Bool Rta_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Rta_Module_heap();
// The heap from which this module allocates memory
Bool Rta_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Rta_Module_getMask();
// Returns the diagnostics mask for this module
Void Rta_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Rta.xdc
var Rta = xdc.useModule('xdc.runtime.Rta');
module-wide constants & types
    values of type Rta.Command// Command ids
        const Rta.Command_READ_MASK;
        const Rta.Command_WRITE_MASK;
        const Rta.Command_LOGGER_OFF;
        const Rta.Command_LOGGER_ON;
        const Rta.Command_GET_CPU_SPEED;
        const Rta.Command_RESET_LOGGER;
        const Rta.Command_CHANGE_PERIOD;
        const Rta.Command_START_TX;
        const Rta.Command_STOP_TX;
    var obj = new Rta.CommandPacket// Structure of command received from host TODO - Either the types should be changed to 32-bits, or the packet size information should be added to the RTA XML file;
        obj.cmdId = Rta.Command ...
        obj.arg0 = UArg ...
        obj.arg1 = UArg ...
    var obj = new Rta.ResponsePacket// Structure of response packet sent back to host;
        obj.cmdId = Rta.Command ...
        obj.resp0 = UArg ...
        obj.resp1 = UArg ...
module-wide config parameters
     Rta.A_invalidLogger// Assert if logger id in control command is invalid = Assert.Desc {
        msg: "A_invalidLogger: The logger id %d is invalid."
    };
     Rta.E_badCommand// Error raised if Agent receives an invalid command = Error.Desc {
        msg: "E_badCommand: Received invalid command, id: %d."
    };
     Rta.LD_cmdRcvd// Logged when the Agent receives a command = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
    };
     Rta.LD_writeMask// Logged when a diags mask is changed = Log.EventDesc {
        mask: Diags.USER2,
        msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
    };
     Rta.controlTransportClassName// The name of the xdc.rta.IControlTransport class to use = String "";
     Rta.dataTransportClassName// The name of the xdc.rta.IDataTransport class to use = String "";
     Rta.common$// Common module configuration parameters = Types.Common$ undefined;
enum Rta.Command
index URL

Command ids

XDCscript usage meta-domain
values of type Rta.Command
    const Rta.Command_READ_MASK;
    const Rta.Command_WRITE_MASK;
    const Rta.Command_LOGGER_OFF;
    const Rta.Command_LOGGER_ON;
    const Rta.Command_GET_CPU_SPEED;
    const Rta.Command_RESET_LOGGER;
    const Rta.Command_CHANGE_PERIOD;
    const Rta.Command_START_TX;
    const Rta.Command_STOP_TX;
C SYNOPSIS
Rta_Command
struct Rta.CommandPacket
index URL

Structure of command received from host TODO - Either the types should be changed to 32-bits, or the packet size information should be added to the RTA XML file

XDCscript usage meta-domain
var obj = new Rta.CommandPacket;
    obj.cmdId = Rta.Command ...
    obj.arg0 = UArg ...
    obj.arg1 = UArg ...
C SYNOPSIS
Rta_CommandPacket
struct Rta.ResponsePacket
index URL

Structure of response packet sent back to host

XDCscript usage meta-domain
var obj = new Rta.ResponsePacket;
    obj.cmdId = Rta.Command ...
    obj.resp0 = UArg ...
    obj.resp1 = UArg ...
C SYNOPSIS
Rta_ResponsePacket
config Rta.A_invalidLogger // module-wide
index URL

Assert if logger id in control command is invalid

XDCscript usage meta-domain
Rta.A_invalidLogger = Assert.Desc {
    msg: "A_invalidLogger: The logger id %d is invalid."
};
C SYNOPSIS
Rta_A_invalidLogger
config Rta.E_badCommand // module-wide
index URL

Error raised if Agent receives an invalid command

XDCscript usage meta-domain
Rta.E_badCommand = Error.Desc {
    msg: "E_badCommand: Received invalid command, id: %d."
};
C SYNOPSIS
Rta_E_badCommand
config Rta.LD_cmdRcvd // module-wide
index URL

Logged when the Agent receives a command

XDCscript usage meta-domain
Rta.LD_cmdRcvd = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
};
C SYNOPSIS
Rta_LD_cmdRcvd
config Rta.LD_writeMask // module-wide
index URL

Logged when a diags mask is changed

XDCscript usage meta-domain
Rta.LD_writeMask = Log.EventDesc {
    mask: Diags.USER2,
    msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
};
C SYNOPSIS
Rta_LD_writeMask
config Rta.controlTransportClassName // module-wide
index URL

The name of the xdc.rta.IControlTransport class to use

XDCscript usage meta-domain
Rta.controlTransportClassName = String "";
DETAILS
The class specified here can be used on the host for communicating with this target application to send control commands and receive responses.
C SYNOPSIS
Rta_controlTransportClassName
config Rta.dataTransportClassName // module-wide
index URL

The name of the xdc.rta.IDataTransport class to use

XDCscript usage meta-domain
Rta.dataTransportClassName = String "";
DETAILS
The class specified here can be used on the host for reading RTA data from this target application.
C SYNOPSIS
Rta_dataTransportClassName
metaonly config Rta.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Rta.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Startup
index URL

The xdc.runtime startup bootstrap

  • C synopsis
  • Individual elements
  • DETAILS
  • STARTUP SEQUENCE
  • XDCscript usage
  • Individual elements
Every module can optionally define a startup function which is called before main(). Modules declare that they want to participate in this startup sequence via the @ModuleStartup attribute in the module's spec file. Modules that use this attribute must also implement the following startup function: [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Startup.xdc
#include <xdc/runtime/Startup.h>
Functions
Void | Startup_exec// Execute the startup functions of all resident modules();
Bool | Startup_rtsDone// Query the state of the xdc.runtime package();
Functions common to all target modules
 | Startup_Module_getMask// Returns the diagnostics mask for this module, Startup_Module_hasMask// Test whether this module has a diagnostics mask, Startup_Module_heap// The heap from which this module allocates memory, Startup_Module_id// Get this module's unique id, Startup_Module_setMask// Set the diagnostics mask for this module, Startup_Module_startupDone// Test if this module has completed startup
Defines
#define | Startup_DONE// Returned from module startup functions no further calls are required (Int)-1
#define | Startup_NOTDONE// Initial value of state argument passed to module startup functions (Int)0
Typedefs
typedef Void | (*Startup_InitFxn// Type of function assignable to firstFxns, lastFxns, or resetFxn)();
Constants
extern const Startup_InitFxn | Startup_firstFxns// List of functions called before module startup[length];
extern const Startup_InitFxn | Startup_lastFxns// List of functions called after module startup[length];
extern const Int | Startup_maxPasses// Max number of iterations over the set of startup functions;
DETAILS
Every module can optionally define a startup function which is called before main(). Modules declare that they want to participate in this startup sequence via the @ModuleStartup attribute in the module's spec file. Modules that use this attribute must also implement the following startup function:
      Int Mod_Module_startup(Int state);
where "Mod" is the name of the module requesting startup support.
The parameter to the startup function serves as "state variable" whose initial value will be Startup_NOTDONE. If startup() returns a value other than Startup_DONE, it will be called in a subsequent pass with this return value passed in as state. To ensure this process terminates, no startup function is ever called more than maxPasses times.
For situations in which the startup of one module depends upon another having completed its startup processing, the following function is automatically defined for all modules and proxies:
      Bool Mod_Module_startupDone();
where "Mod" is the name of some module or proxy. These predicates can be used as guards inside of a startup function to probe whether a particular module has completed its own startup processing. As a convenience, the function Startup_rtsDone() probes the necessary set of xdc.runtime modules required to support instance create() functions, and should be called before any startup-time instance creation and/or memory allocation is performed.
      Int Mod_Module_startup(Int state)
      {
          if (!Startup_rtsDone()) {
              return (Startup_NOTDONE);
          }
              .
              .
              .
          return (Startup_DONE);
      }
STARTUP SEQUENCE
The following list defines when in the startup sequence the user provided startup functions are being invoked:
  1. CPU is initialized and C stack setup is performed.
  2. Function specified by Startup.resetFxn is called. Startup.resetFxn is called only on platforms where reset is performed before running a program. For example, boot code for all TI targets invokes Startup.resetFxn, while that function is not invoked on Microsoft targets.
  3. C runtime initialization is performed.
  4. Functions from the array Startup.firstFxns are called.
  5. All Mod_Module_startup functions are called in a loop until all such functions return Startup_DONE or maxPasses threshold is reached.
  6. Functions from the array Startup.lastFxns are called.
  7. The function main is called.
The steps 4 - 6 occur during C++ static object initialization. Since the ANSI C++ Language Standard does not provide a means to control the order of C++ constructors, if a C++ constructor uses an XDC module, there is no guarantee that the module's startup function already ran. Therefore, any C++ constructor that needs XDC modules' services should call Startup_exec first to force all startup related functions from steps 4 - 6 to run, before the constructor uses any XDC module.
Also, if a target does not support C++, the steps 4 - 6 will not run automatically. It is then up to a user's code to invoke Startup_exec, possibly as the first step in main.
const Startup_DONE
index URL

Returned from module startup functions no further calls are required

C synopsis target-domain
#define Startup_DONE (Int)-1
const Startup_NOTDONE
index URL

Initial value of state argument passed to module startup functions

C synopsis target-domain
#define Startup_NOTDONE (Int)0
typedef Startup_InitFxn
index URL

Type of function assignable to firstFxns, lastFxns, or resetFxn

C synopsis target-domain
typedef Void (*Startup_InitFxn)();
config Startup_firstFxns // module-wide
index URL

List of functions called before module startup

C synopsis target-domain
extern const Startup_InitFxn Startup_firstFxns[length];
config Startup_lastFxns // module-wide
index URL

List of functions called after module startup

C synopsis target-domain
extern const Startup_InitFxn Startup_lastFxns[length];
config Startup_maxPasses // module-wide
index URL

Max number of iterations over the set of startup functions

C synopsis target-domain
extern const Int Startup_maxPasses;
Startup_exec() // module-wide
index URL

Execute the startup functions of all resident modules

C synopsis target-domain
Void Startup_exec();
DETAILS
Note that this function is idempotent, and can be called at any point in the platform/target startup sequence in which "ordinary" C functions can execute. By default, this function is called as part of the standard C++ static initialization sequence.
If your target compiler does not support C++, this function must be called at least once prior to using any xdc.runtime modules. Simply call this function at the very beginning of main().
Startup_rtsDone() // module-wide
index URL

Query the state of the xdc.runtime package

C synopsis target-domain
Bool Startup_rtsDone();
DETAILS
This function is used by module startup functions to determine when it is possible to use the xdc.runtime modules; e.g. to allocate memory, create instances managed by some module (even those outside the xdc.runtime package), call a Log function, etc.
RETURNS
Returns TRUE when all xdc.runtime modules have completed initialization.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Startup_Module_id();
// Get this module's unique id
Bool Startup_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Startup_Module_heap();
// The heap from which this module allocates memory
Bool Startup_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Startup_Module_getMask();
// Returns the diagnostics mask for this module
Void Startup_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Startup.xdc
var Startup = xdc.useModule('xdc.runtime.Startup');
module-wide constants & types
    const Startup.DONE// Returned from module startup functions no further calls are required = -1;
    const Startup.NOTDONE// Initial value of state argument passed to module startup functions = 0;
module-wide config parameters
     Startup.firstFxns// List of functions called before module startup = Startup.InitFxn[length] [ ];
     Startup.lastFxns// List of functions called after module startup = Startup.InitFxn[length] [ ];
     Startup.maxPasses// Max number of iterations over the set of startup functions = Int 32;
     Startup.common$// Common module configuration parameters = Types.Common$ undefined;
     Startup.resetFxn// Function to be called by during initialization = Void(*)() null;
const Startup.DONE
index URL

Returned from module startup functions no further calls are required

XDCscript usage meta-domain
const Startup.DONE = -1;
C SYNOPSIS
Startup_DONE
const Startup.NOTDONE
index URL

Initial value of state argument passed to module startup functions

XDCscript usage meta-domain
const Startup.NOTDONE = 0;
C SYNOPSIS
Startup_NOTDONE
config Startup.firstFxns // module-wide
index URL

List of functions called before module startup

XDCscript usage meta-domain
Startup.firstFxns = Startup.InitFxn[length] [ ];
C SYNOPSIS
Startup_firstFxns
config Startup.lastFxns // module-wide
index URL

List of functions called after module startup

XDCscript usage meta-domain
Startup.lastFxns = Startup.InitFxn[length] [ ];
C SYNOPSIS
Startup_lastFxns
config Startup.maxPasses // module-wide
index URL

Max number of iterations over the set of startup functions

XDCscript usage meta-domain
Startup.maxPasses = Int 32;
C SYNOPSIS
Startup_maxPasses
metaonly config Startup.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Startup.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config Startup.resetFxn // module-wide
index URL

Function to be called by during initialization

XDCscript usage meta-domain
Startup.resetFxn = Void(*)() null;
DETAILS
This function is called only on platforms where reset is performed before running the program. The purpose of this function is to set up the hardware registers (cache, external memory interface, etc.) before any other code executes.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.SysMin
index URL

Minimal implementation of ISystemSupport

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This implementation provides a fully functional implementation of all methods specified by ISystemSupport. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/SysMin.xdc
#include <xdc/runtime/SysMin.h>
Functions common to all ISystemSupport modules
Void | SysMin_abort// Backend for System.abort()(String str);
Void | SysMin_exit// Backend for System.exit()(Int stat);
Void | SysMin_flush// Backend for System.flush()();
Void | SysMin_putch// Backend for System.printf() and System.putch()(Char ch);
Bool | SysMin_ready// Test if character output can proceed();
Functions common to all target modules
 | SysMin_Module_getMask// Returns the diagnostics mask for this module, SysMin_Module_hasMask// Test whether this module has a diagnostics mask, SysMin_Module_heap// The heap from which this module allocates memory, SysMin_Module_id// Get this module's unique id, SysMin_Module_setMask// Set the diagnostics mask for this module, SysMin_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void | (*SysMin_OutputFxn// Output characters in the specified buffer)(Char*,UInt);
Constants
extern const SizeT | SysMin_bufSize// Size (in MAUs) of the output;
extern const Bool | SysMin_flushAtExit// Flush the internal buffer during exit or abort;
extern const SysMin_OutputFxn | SysMin_outputFxn// User suplied character output function;
DETAILS
This implementation provides a fully functional implementation of all methods specified by ISystemSupport.
The module maintains an internal buffer (with a configurable size) that stores on the "output". When full, the data is over-written. When System_flush() is called the characters in the internal buffer are "output" using the user configuratble outputFxn.
As with all ISystemSupport modules, this module is the back-end for the System module; application code does not directly call these functions.
typedef SysMin_OutputFxn
index URL

Output characters in the specified buffer

C synopsis target-domain
typedef Void (*SysMin_OutputFxn)(Char*,UInt);
DETAILS
The first parameter is a pointer to a buffer of characters to be output. The second parameter is the number of characters in the buffer to output.
This function may be called with 0 as the second parameter. In this case, the function should simply return.
config SysMin_bufSize // module-wide
index URL

Size (in MAUs) of the output

C synopsis target-domain
extern const SizeT SysMin_bufSize;
DETAILS
An internal buffer of this size is allocated. All output is stored in this internal buffer.
If 0 is specified for the size, no buffer is created.
config SysMin_flushAtExit // module-wide
index URL

Flush the internal buffer during exit or abort

C synopsis target-domain
extern const Bool SysMin_flushAtExit;
DETAILS
If the application's target is a TI target, the internal buffer is flushed via the HOSTwrite function in the TI C Run Time Support (RTS) library.
If the application's target is not a TI target, the internal buffer is flushed to stdout via fwrite(..., stdout).
Setting this parameter to false reduces the footprint of the application at the expense of not getting output when the application ends via a System_exit(), System_abort(), exit() or abort().
config SysMin_outputFxn // module-wide
index URL

User suplied character output function

C synopsis target-domain
extern const SysMin_OutputFxn SysMin_outputFxn;
DETAILS
If this parameter is set to a non-null value, the specified function will be called by to output characters buffered within SysMin.
For example, if you define a function named myOutputFxn, the following configuration fragment will cause SysMin to call myOutputFxn whenever the character buffer is flushed.
      var SysMin = xdc.useModule("xdc.runtime.SysMin");
      SysMin.outputFxn = "&myOutputFxn";
If this parameter is not set, a default function will be used which uses the ANSI C Standard Library function fwrite() (or HOSTwrite in the TI C Run Time Support library) to output accumulated output characters.
SEE
OutputFxn
SysMin_abort() // module-wide
index URL

Backend for System.abort()

C synopsis target-domain
Void SysMin_abort(String str);
ARGUMENTS
str — message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
DETAILS
This function is called by System.abort() prior to calling the ANSI C Standard library function abort(). So, to ensure the abort processing of the system's ANSI C Standard library completes, this function should return to its caller.
This abort function writes the string to the internal output buffer and then gives all internal output to the outputFxn function if the flushAtExit configuration parameter is true.
SEE
ISystemSupport.abort
SysMin_exit() // module-wide
index URL

Backend for System.exit()

C synopsis target-domain
Void SysMin_exit(Int stat);
ARGUMENTS
stat — status value passed to all "atexit" handlers
This value is passed to all "atexit" handles bound via System.atexit(). If the application exits via the ANSI C Standard exit() function rather than via System_exit(), stat will be equal to System.STATUS_UNKNOWN.
DETAILS
This function is called as part the normal "atexit" processing performed by the ANSI C Standard Library's exit() function; System.exit() directly calls ANSI exit().
This function is called after all "atexit" handlers bound via System.atexit() are run and it is always called while "inside" the the System gate.
To ensure that all exit processing of the system's ANSI C Standard Library completes, this function should return to its caller. Exit handlers bound using the ANSI C Standard Library atexit() function may run before or after this function.
This exit function gives all internal output to the outputFxn function if the flushAtExit configuration parameter is true.
SEE
System.atexit, ISystemSupport.exit
SysMin_flush() // module-wide
index URL

Backend for System.flush()

C synopsis target-domain
Void SysMin_flush();
DETAILS
This function is simply called by System_flush to output any characters buffered by the underlying SystemSupport module to an output device.
The flush writes the contents of the internal character buffer via the outputFxn function.
WARNING
The System gate is used for thread safety during the entire flush operation, so care must be taken when flushing with this ISystemSupport module. Depending on the nature of the System gate, your application's interrupt latency may become a function of the bufSize parameter!
SEE
ISystemSupport.flush
SysMin_putch() // module-wide
index URL

Backend for System.printf() and System.putch()

C synopsis target-domain
Void SysMin_putch(Char ch);
ARGUMENTS
ch — character to output
DETAILS
Output a single character. This function is called by System_printf() to write each character of formated output specified by its arguments.
Places the character into an internal buffer. The flush sends the internal buffer to the outputFxn function. The internal buffer is also sent to the SysMin_outputFxn function by exit and abort if the flushAtExit configuration parameter is true.
SEE
ISystemSupport.putch
SysMin_ready() // module-wide
index URL

Test if character output can proceed

C synopsis target-domain
Bool SysMin_ready();
DETAILS
This function is called by System prior to performing any character output. If this function returns FALSE, the System functions that would normally call putch() simply return (with an appropriate error status) without ever calling putch.
This function returns true if the internal buffer is non-zero.
SEE
ISystemSupport.ready
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SysMin_Module_id();
// Get this module's unique id
Bool SysMin_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SysMin_Module_heap();
// The heap from which this module allocates memory
Bool SysMin_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SysMin_Module_getMask();
// Returns the diagnostics mask for this module
Void SysMin_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/SysMin.xdc
var SysMin = xdc.useModule('xdc.runtime.SysMin');
module-wide constants & types
    var obj = new SysMin.BufferEntryView// ;
        obj.entry = String ...
    var obj = new SysMin.ModuleView// ;
        obj.outBuf = Ptr ...
        obj.outBufIndex = UInt ...
        obj.wrapped = Bool ...
module-wide config parameters
     SysMin.bufSize// Size (in MAUs) of the output = SizeT 1024;
     SysMin.flushAtExit// Flush the internal buffer during exit or abort = Bool true;
     SysMin.outputFxn// User suplied character output function = Void(*)(Char*,UInt) null;
     SysMin.common$// Common module configuration parameters = Types.Common$ undefined;
     SysMin.sectionName// Section where the internal character output buffer is placed = String null;
metaonly struct SysMin.BufferEntryView
index URL
XDCscript usage meta-domain
var obj = new SysMin.BufferEntryView;
    obj.entry = String ...
metaonly struct SysMin.ModuleView
index URL
XDCscript usage meta-domain
var obj = new SysMin.ModuleView;
    obj.outBuf = Ptr ...
    obj.outBufIndex = UInt ...
    obj.wrapped = Bool ...
config SysMin.bufSize // module-wide
index URL

Size (in MAUs) of the output

XDCscript usage meta-domain
SysMin.bufSize = SizeT 1024;
DETAILS
An internal buffer of this size is allocated. All output is stored in this internal buffer.
If 0 is specified for the size, no buffer is created.
C SYNOPSIS
SysMin_bufSize
config SysMin.flushAtExit // module-wide
index URL

Flush the internal buffer during exit or abort

XDCscript usage meta-domain
SysMin.flushAtExit = Bool true;
DETAILS
If the application's target is a TI target, the internal buffer is flushed via the HOSTwrite function in the TI C Run Time Support (RTS) library.
If the application's target is not a TI target, the internal buffer is flushed to stdout via fwrite(..., stdout).
Setting this parameter to false reduces the footprint of the application at the expense of not getting output when the application ends via a System_exit(), System_abort(), exit() or abort().
C SYNOPSIS
SysMin_flushAtExit
config SysMin.outputFxn // module-wide
index URL

User suplied character output function

XDCscript usage meta-domain
SysMin.outputFxn = Void(*)(Char*,UInt) null;
DETAILS
If this parameter is set to a non-null value, the specified function will be called by to output characters buffered within SysMin.
For example, if you define a function named myOutputFxn, the following configuration fragment will cause SysMin to call myOutputFxn whenever the character buffer is flushed.
      var SysMin = xdc.useModule("xdc.runtime.SysMin");
      SysMin.outputFxn = "&myOutputFxn";
If this parameter is not set, a default function will be used which uses the ANSI C Standard Library function fwrite() (or HOSTwrite in the TI C Run Time Support library) to output accumulated output characters.
SEE
OutputFxn
C SYNOPSIS
SysMin_outputFxn
metaonly config SysMin.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SysMin.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config SysMin.sectionName // module-wide
index URL

Section where the internal character output buffer is placed

XDCscript usage meta-domain
SysMin.sectionName = String null;
DETAILS
The default is to have no explicit placement; i.e., the linker is free to place it anywhere in the memory map.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.SysStd
index URL

Implementation of ISystemSupport using ANSI C Standard Library

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This implementation provides a fully functional implementation of all methods specified by ISystemSupport. As with all ISystemSupport modules, this module is the back-end for the System module. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/SysStd.xdc
#include <xdc/runtime/SysStd.h>
Functions common to all ISystemSupport modules
Void | SysStd_abort// Backend for System.abort()(String str);
Void | SysStd_exit// Backend for System.exit()(Int stat);
Void | SysStd_flush// Backend for System.flush()();
Void | SysStd_putch// Backend for System.printf() and System.putch()(Char ch);
Bool | SysStd_ready// Test if character output can proceed();
Functions common to all target modules
 | SysStd_Module_getMask// Returns the diagnostics mask for this module, SysStd_Module_hasMask// Test whether this module has a diagnostics mask, SysStd_Module_heap// The heap from which this module allocates memory, SysStd_Module_id// Get this module's unique id, SysStd_Module_setMask// Set the diagnostics mask for this module, SysStd_Module_startupDone// Test if this module has completed startup
DETAILS
This implementation provides a fully functional implementation of all methods specified by ISystemSupport. As with all ISystemSupport modules, this module is the back-end for the System module.
This implementation relies on the target's runtime support libraries (i.e. fflush() and putchar()). Therefore the functions are re-entrant (thread-safe) if the underlying rts library is re-entrant.
SysStd_abort() // module-wide
index URL

Backend for System.abort()

C synopsis target-domain
Void SysStd_abort(String str);
ARGUMENTS
str — message to output just prior to aborting
If non-NULL, this string should be output just prior to terminating.
DETAILS
This function is called by System.abort() prior to calling the ANSI C Standard library function abort(). So, to ensure the abort processing of the system's ANSI C Standard library completes, this function should return to its caller.
This abort function writes the string via putchar() and flushes via fflush() to stdout.
SEE
ISystemSupport.abort
SysStd_exit() // module-wide
index URL

Backend for System.exit()

C synopsis target-domain
Void SysStd_exit(Int stat);
ARGUMENTS
stat — status value passed to all "atexit" handlers
This value is passed to all "atexit" handles bound via System.atexit(). If the application exits via the ANSI C Standard exit() function rather than via System_exit(), stat will be equal to System.STATUS_UNKNOWN.
DETAILS
This function is called as part the normal "atexit" processing performed by the ANSI C Standard Library's exit() function; System.exit() directly calls ANSI exit().
This function is called after all "atexit" handlers bound via System.atexit() are run and it is always called while "inside" the the System gate.
To ensure that all exit processing of the system's ANSI C Standard Library completes, this function should return to its caller. Exit handlers bound using the ANSI C Standard Library atexit() function may run before or after this function.
This exit function flushes via fflush() to stdout.
SEE
System.atexit, ISystemSupport.exit
SysStd_flush() // module-wide
index URL

Backend for System.flush()

C synopsis target-domain
Void SysStd_flush();
DETAILS
This function is simply called by System_flush to output any characters buffered by the underlying SystemSupport module to an output device.
This flush function flushes via fflush() to stdout.
SEE
ISystemSupport.flush
SysStd_putch() // module-wide
index URL

Backend for System.printf() and System.putch()

C synopsis target-domain
Void SysStd_putch(Char ch);
ARGUMENTS
ch — character to output
DETAILS
Output a single character. This function is called by System_printf() to write each character of formated output specified by its arguments.
This function outputs the character via putchar().
SEE
ISystemSupport.putch
SysStd_ready() // module-wide
index URL

Test if character output can proceed

C synopsis target-domain
Bool SysStd_ready();
DETAILS
This function is called by System prior to performing any character output. If this function returns FALSE, the System functions that would normally call putch() simply return (with an appropriate error status) without ever calling putch.
This always returns TRUE.
SEE
ISystemSupport.ready
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SysStd_Module_id();
// Get this module's unique id
Bool SysStd_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SysStd_Module_heap();
// The heap from which this module allocates memory
Bool SysStd_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SysStd_Module_getMask();
// Returns the diagnostics mask for this module
Void SysStd_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/SysStd.xdc
var SysStd = xdc.useModule('xdc.runtime.SysStd');
module-wide config parameters
     SysStd.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config SysStd.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SysStd.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.System
index URL

Basic system services

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides basic low-level "system" services; e.g., character output, printf-like output, and exit handling. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/System.xdc
#include <xdc/runtime/System.h>
Functions
Void | System_abort// Print a message and abort currently running executable(String str);
Int | System_aprintf// printf where all optional arguments are IArgs(String fmt, ...);
Int | System_asprintf// sprintf where all optional arguments are IArgs(Char buf[], String fmt, ...);
Bool | System_atexit// Add an exit handler(System_AtexitHandler handler);
Int | System_avprintf// vprintf where all optional arguments are IArgs(String fmt, VaList va);
Int | System_avsprintf// vsprintf where all optional arguments are IArgs(Char buf[], String fmt, VaList va);
Void | System_exit// Exit currently running executable(Int stat);
Void | System_flush// Flush standard System I/O();
Int | System_printf// A smaller faster printf(String fmt, ...);
Void | System_putch// Output a single character(Char ch);
Int | System_sprintf// Write formated output to a character buffer(Char buf[], String fmt, ...);
Int | System_vprintf// A VaList printf(String fmt, VaList va);
Int | System_vsprintf// A VaList sprintf(Char buf[], String fmt, VaList va);
Functions common to all target modules
 | System_Module_getMask// Returns the diagnostics mask for this module, System_Module_hasMask// Test whether this module has a diagnostics mask, System_Module_heap// The heap from which this module allocates memory, System_Module_id// Get this module's unique id, System_Module_setMask// Set the diagnostics mask for this module, System_Module_startupDone// Test if this module has completed startup
Defines
#define | System_STATUS_UNKNOWN// Unknown exit status value (Int)0xCAFE
Typedefs
typedef Void | (*System_AtexitHandler// System's atexit function prototype)(Int);
Constants
extern const Assert_Id | System_A_cannotFitIntoArg// Assert that the target's Float type fits in an IArg;
extern const Int | System_maxAtexitHandlers// Maximum number of dynamic atexit handlers allowed in the system;
DETAILS
This module provides basic low-level "system" services; e.g., character output, printf-like output, and exit handling.
This module is gated and other modules use its gate via the Gate.enterSystem and Gate.leaveSystem. The System gate must be enterable by any thread in a multi-threaded environments. For example, in many real-time multi-threaded environments some types of threads, such as Interrupt Service Routines (ISRs), are not allowed to call operations that block the caller. In such an environment, either the System gate must disable all interrupts or ISRs must never call a function in the xdc.runtime package.
const System_STATUS_UNKNOWN
index URL

Unknown exit status value

C synopsis target-domain
#define System_STATUS_UNKNOWN (Int)0xCAFE
DETAILS
When the program exits by calling System_exit() the System's atexit functions are passed the status value passed to System_exit(). However, if the program exits using the ANSI C Standard Library exit() function, the System's atexit functions are passed System_STATUS_UNKNOWN; ANSI C atexit functions are not passed the exit status.
typedef System_AtexitHandler
index URL

System's atexit function prototype

C synopsis target-domain
typedef Void (*System_AtexitHandler)(Int);
DETAILS
Fuctions of this type can be added to the list of functions that are executed during application termination.
SEE
atexit
config System_A_cannotFitIntoArg // module-wide
index URL

Assert that the target's Float type fits in an IArg

C synopsis target-domain
extern const Assert_Id System_A_cannotFitIntoArg;
DETAILS
This assertion is triggered when the %f format specifier is used, the argument treated as an IArg, but for the current target sizeof(Float) > sizeof(IArg).
config System_maxAtexitHandlers // module-wide
index URL

Maximum number of dynamic atexit handlers allowed in the system

C synopsis target-domain
extern const Int System_maxAtexitHandlers;
DETAILS
Maximum number of System atexit handlers set during runtime via the System.atexit function.
System_abort() // module-wide
index URL

Print a message and abort currently running executable

C synopsis target-domain
Void System_abort(String str);
ARGUMENTS
str — abort message (not a format string)
DETAILS
This is called when an executable abnormally terminates. The System gate is entered, the SupportProxy's abort function is called and abort is called. No exit functions bound via System_atexit() or the ANSI C Standard Library atexit() functions are executed.
System_aprintf() // module-wide
index URL

printf where all optional arguments are IArgs

C synopsis target-domain
Int System_aprintf(String fmt, ...);
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the printf function
SEE
printf
System_asprintf() // module-wide
index URL

sprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_asprintf(Char buf[], String fmt, ...);
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the sprintf function.
SEE
sprintf
System_atexit() // module-wide
index URL

Add an exit handler

C synopsis target-domain
Bool System_atexit(System_AtexitHandler handler);
ARGUMENTS
handler — the AtexitHandler to invoke during system exit processing.
DETAILS
System_atexit pushes handler onto an internal stack of functions to be executed when system is exiting (e.g. System_exit or exit is called). Up to maxAtexitHandlers functions can be specified in this manner. During the exit processing, the functions are popped off the internal stack and called until the stack is empty.
The System gate is entered before the System_atexit functions are called.
The SupportProxy's ISystemSupport.exit function is called after all the atexit functions are called.
RETURNS
If FALSE is returned, the exit handler was not added and it will not be called during an exit.
System_avprintf() // module-wide
index URL

vprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_avprintf(String fmt, VaList va);
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the vprintf function.
SEE
vprintf
System_avsprintf() // module-wide
index URL

vsprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_avsprintf(Char buf[], String fmt, VaList va);
DETAILS
This function is identical to sprintf except that its arguments are passed via a VaList (a "varargs list").
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the vsprintf function
SEE
vsprintf
System_exit() // module-wide
index URL

Exit currently running executable

C synopsis target-domain
Void System_exit(Int stat);
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This function is called when an executable needs to terminate normally. This function sets the exit code and simply calls exit. All functions bound via System_atexit or the ANSI C Standar Library atexit function are then executed. The SupportProxy's exit function is called during this time.
System_flush() // module-wide
index URL

Flush standard System I/O

C synopsis target-domain
Void System_flush();
DETAILS
This function causes any buffered output characters are "written" to the output device.
The SupportProxy's flush function is called by this function.
System_printf() // module-wide
index URL

A smaller faster printf

C synopsis target-domain
Int System_printf(String fmt, ...);
ARGUMENTS
fmt — a 'printf-style' format string
DETAILS
This function behaves much like the ANSI C Standard printf but does not support the full range of format strings specified by the C Standard. In addition, several non-standard format specifiers are recognized.
FORMAT STRINGS
The format string is a character string composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, an optional precision and an optional length modifier.
FLAGS
The following flags are supported:
-
The converted value is to be left adjusted on the field boundary (the default is right justification.)
0
The value should be zero padded. For d, i, o, u, and x conversions, the converted value is padded on the left with zeros rather than blanks.
FIELD WIDTH
The optional field width specifier is a decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write * to specify that the field width is given in the next argument. A negative field width is taken as a '-' flag followed by a positive field width.
PRECISION
The optional precision specifier is a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write * to specify that the precision is given in the next argument which must be of type int.
If the precision is given as just '.', or the precision is negative, the precision is taken to be zero. This gives the minimum number of digits to appear for d, i, o, u, and x conversions, or the maximum number of characters to be printed from a string for s conversions.
LENGTH MODIFIERS
The optional length modifier is a single character from the following list.
l
A following integer conversion corresponds to a long int or unsigned long int argument
CONVERSION SPECIFIERS
The following conversion specifiers are supported.
d, i
signed integer
u
unsigned decimal
x
unsigned hex
o
unsigned octal
p
pointer (@ + hex num)
c
character
s
string
EXTENDED CONVERSION SPECIFIERS
The following conversion specifiers are optionally supported. See the extendedFormats configuration parameter for more information about how to enable these conversion specifiers.
f
decimal floating point.
$
non-ANSI conversion prefix. This prefix indicates that the next character identifies a non-ANSI standard conversion. See the next section for details.
NON ANSI CONVERSION SPECIFIERS
Among the extended conversion specifiers are unique specifiers which are not part of ANSI printf. These are specified using a $, for example %$L.
These unique specifiers do not support the minimum field width attribute. Certain specifiers have additional restrictions; see below.
'$L'
The argument is treated as a pointer to a Types.Label and is converted to an appropriate string.
'$F'
Displays a file and line number; used for displaying the call site. This specifier consumes two arguments, the file and line number, in that order. See an example below.
'$S'
The argument is treated as a format string, and is recursively formatted using any following arguments. This specifier does not support the use of the "precision" field for specifying maximum string length.
The following are example uses of the %$F and %$S format specifiers.
In this call using %$F, the compiler recognizes these symbols and fills in the file and line number.
  System_printf("%$F", __FILE__, __LINE__);
This call outputs, for example,
  "MyCode.c", line 35:
Here is an example using %$S, passing a recursive format string.
  System_printf("Msg: %$S", "My msg, code: %d", 5);
This outputs:
  Msg: My msg, code: 5
RETURNS
printf returns the number of characters printed.
System_putch() // module-wide
index URL

Output a single character

C synopsis target-domain
Void System_putch(Char ch);
ARGUMENTS
ch — character to be output.
DETAILS
The SupportProxy's putch function is called by this function.
System_sprintf() // module-wide
index URL

Write formated output to a character buffer

C synopsis target-domain
Int System_sprintf(Char buf[], String fmt, ...);
ARGUMENTS
buf — a character output buffer
fmt — a 'printf-style' format string
DETAILS
This function is identical to printf except that the output is copied to the specified character buffer buf followed by a terminating '\0' character.
RETURNS
sprintf returns the number of characters output not including the '\0' termination character.
System_vprintf() // module-wide
index URL

A VaList printf

C synopsis target-domain
Int System_vprintf(String fmt, VaList va);
ARGUMENTS
fmt — a standard 'printf-style' format string.
va — an args list that points to the arguments referenced by the fmt string
DETAILS
This function is identical to printf except that its arguments are passed via a VaList (a "varargs list").
RETURNS
vprintf returns the number of characters output.
System_vsprintf() // module-wide
index URL

A VaList sprintf

C synopsis target-domain
Int System_vsprintf(Char buf[], String fmt, VaList va);
ARGUMENTS
buf — a character output buffer
fmt — a standard 'printf-style' format string.
va — an arguments list that points to the arguments referenced by the fmt string
DETAILS
This function is identical to sprintf except that its arguments are passed via a VaList (a "varargs list").
RETURNS
vsprintf returns the number of characters output.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId System_Module_id();
// Get this module's unique id
Bool System_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle System_Module_heap();
// The heap from which this module allocates memory
Bool System_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 System_Module_getMask();
// Returns the diagnostics mask for this module
Void System_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/System.xdc
var System = xdc.useModule('xdc.runtime.System');
local proxy modules
     System.SupportProxy// The implementation module of the low-level system functions = ISystemSupport.Module null
         System.SupportProxy.delegate$ = ISystemSupport.Module null
module-wide constants & types
    const System.STATUS_UNKNOWN// Unknown exit status value = 0xCAFE;
module-wide config parameters
     System.A_cannotFitIntoArg// Assert that the target's Float type fits in an IArg = Assert.Desc {
        msg: "A_cannotFitIntoArg: sizeof(Float) > sizeof(Arg)"
    };
     System.maxAtexitHandlers// Maximum number of dynamic atexit handlers allowed in the system = Int 8;
     System.common$// Common module configuration parameters = Types.Common$ undefined;
     System.extendedFormats// Optional conversions supported by System_printf = String "%$L%$S%$F";
module-wide functions
     System.atexitMeta// Add an exit handler during configuration(Void(*)(Int) handler) returns Void
proxy System.SupportProxy
index URL

The implementation module of the low-level system functions

XDCscript usage meta-domain
System.SupportProxy = ISystemSupport.Module null
// some delegate module inheriting the ISystemSupport interface
    System.SupportProxy.delegate$ = ISystemSupport.Module null
    // explicit access to the currently bound delegate module
DETAILS
This configuration parameter allows one to "bind" a different implementation of the low-level services required to implement System.
      var System = xdc.useModule("xdc.runtime.System");
      var SysStd = xdc.useModule("xdc.runtime.SysStd");
      System.SupportProxy = SysStd;
If this parameter is not set, it defaults to SysMin.
const System.STATUS_UNKNOWN
index URL

Unknown exit status value

XDCscript usage meta-domain
const System.STATUS_UNKNOWN = 0xCAFE;
DETAILS
When the program exits by calling System_exit() the System's atexit functions are passed the status value passed to System_exit(). However, if the program exits using the ANSI C Standard Library exit() function, the System's atexit functions are passed System_STATUS_UNKNOWN; ANSI C atexit functions are not passed the exit status.
C SYNOPSIS
System_STATUS_UNKNOWN
config System.A_cannotFitIntoArg // module-wide
index URL

Assert that the target's Float type fits in an IArg

XDCscript usage meta-domain
System.A_cannotFitIntoArg = Assert.Desc {
    msg: "A_cannotFitIntoArg: sizeof(Float) > sizeof(Arg)"
};
DETAILS
This assertion is triggered when the %f format specifier is used, the argument treated as an IArg, but for the current target sizeof(Float) > sizeof(IArg).
C SYNOPSIS
System_A_cannotFitIntoArg
config System.maxAtexitHandlers // module-wide
index URL

Maximum number of dynamic atexit handlers allowed in the system

XDCscript usage meta-domain
System.maxAtexitHandlers = Int 8;
DETAILS
Maximum number of System atexit handlers set during runtime via the System.atexit function.
C SYNOPSIS
System_maxAtexitHandlers
metaonly config System.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
System.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly config System.extendedFormats // module-wide
index URL

Optional conversions supported by System_printf

XDCscript usage meta-domain
System.extendedFormats = String "%$L%$S%$F";
DETAILS
This string specifies the set of optional argument conversion specifiers required by the application. By reducing the number of optional conversions understood by the System printf methods, it is possible to significantly reduce the code size footprint of the System module. This configuration parameter enables one to balance printf functionality against code size footprint.
The format of this string is simply a concatenated list of the desired conversion specifiers (with the leading % character). For example, to support both %f and %$L set extendedFormats to "%$L%f".
To disable all optional converstions, set extendedFormats to null or the empty string ("").
For a complete list of supported extensions, see the System_printf "Extended_Format_Specifiers" section.
NOTE
If an optional conversion is used by some part of the application and it is not specified in extendedFormats, the conversion character(s) and leading % are treated as ordinary characters to be output. As a result, all subsequent arguments will almost certainly be converted using the wrong conversion specifier!
SEE
printf
metaonly System.atexitMeta() // module-wide
index URL

Add an exit handler during configuration

XDCscript usage meta-domain
System.atexitMeta(Void(*)(Int) handler) returns Void
ARGUMENTS
handler — the AtexitHandler to invoke during system exit processing.
DETAILS
This is the static counterpart to System_atexit(). This method can be used to add atexit handlers at configuration time. These handlers do not count against the maxAtexitHandlers.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Text
index URL

Runtime text handling services

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module efficiently manages a collection of strings that have common substrings. Collections with a high degree of commonality are stored in much less space than as ordinary table of independent C strings. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Text.xdc
#include <xdc/runtime/Text.h>
Functions
Int | Text_putLab// Convert label to an ASCII character sequence(Types_Label *lab, Char **bufp, Int len);
Int | Text_putMod// Convert module ID to its ASCII name(Types_ModuleId mid, Char **bufp, Int len);
Int | Text_putSite// Convert call site structure to an ASCII character sequence(Types_Site *site, Char **bufp, Int len);
Functions common to all target modules
 | Text_Module_getMask// Returns the diagnostics mask for this module, Text_Module_hasMask// Test whether this module has a diagnostics mask, Text_Module_heap// The heap from which this module allocates memory, Text_Module_id// Get this module's unique id, Text_Module_setMask// Set the diagnostics mask for this module, Text_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Types_Label | Text_Label// ;
Constants
extern const Bool | Text_isLoaded// Ensure character-strings are loaded in target memory;
extern const String | Text_nameEmpty// Default NULL instance name;
extern const String | Text_nameStatic// Default static instance name;
extern const String | Text_nameUnknown// Default unknowable instance name;
DETAILS
This module efficiently manages a collection of strings that have common substrings. Collections with a high degree of commonality are stored in much less space than as ordinary table of independent C strings.
To further save space, the "compressed" representation need not even be loaded in the target's memory; see isLoaded.
The total space available for the compressed representation of text strings is limited to 64K characters; each string is represented by a 16-bit "rope id".
typedef Text_Label
index URL
C synopsis target-domain
typedef Types_Label Text_Label;
config Text_isLoaded // module-wide
index URL

Ensure character-strings are loaded in target memory

C synopsis target-domain
extern const Bool Text_isLoaded;
DETAILS
Character strings managed by this module are allocated together with other character strings, and loaded to the target, when this parameter is set to its default value true. If this parameter is set to false, the character strings managed by Text are separated in their own section xdc.noload, which is not loaded to the target.
NOTE
For TI and GNU targets, the section xdc.noload is not loaded to the target, but it can overlay other output sections. If the linker allocates xdc.noload so that it overlaps the section that contains character strings when isLoaded is false, ROV/RTA functionality can be affected. In such a case, an error message is displayed that indicates the overlap between xdc.noload and another section, whose name depends on the target (.const on TI targets, .rodata on GNU targets). The user can solve that problem by specifying an address for xdc.noload to unconfigured memory, and ensure that .const and xdc.noload do not overlap.
      Program.sectMap["xdc.noload"] = new prog.SectionSpec();
      Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
config Text_nameEmpty // module-wide
index URL

Default NULL instance name

C synopsis target-domain
extern const String Text_nameEmpty;
DETAILS
The name used if the instance's name has been set to NULL.
config Text_nameStatic // module-wide
index URL

Default static instance name

C synopsis target-domain
extern const String Text_nameStatic;
DETAILS
The name of an instance if the name exists but it's not loaded on the target.
config Text_nameUnknown // module-wide
index URL

Default unknowable instance name

C synopsis target-domain
extern const String Text_nameUnknown;
DETAILS
The name of an instance if the module's instances are configured to not have names.
Text_putLab() // module-wide
index URL

Convert label to an ASCII character sequence

C synopsis target-domain
Int Text_putLab(Types_Label *lab, Char **bufp, Int len);
ARGUMENTS
lab — address of the label to interpret
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the label's characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a Types.Label to a sequence of ASCII characters, writes the characters to the supplied buffer, updates the buffer pointer to point to the location after the last output character, and returns the number of characters output.
No more than len characters will be output. If the label would otherwise be longer, the output is truncated at the point where a potential overflow is detected. The return value always reflects the number of characters output, but it may be less than len.
Label structures can be initialized from any module's instance handle using the module's Mod_Handle_label() method. See Types.Label for more information.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
SEE
Types.Label
Text_putMod() // module-wide
index URL

Convert module ID to its ASCII name

C synopsis target-domain
Int Text_putMod(Types_ModuleId mid, Char **bufp, Int len);
ARGUMENTS
mid — ID of the module
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the module's name characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a Types.ModuleId to a sequence of ASCII characters, writes the characters to the supplied buffer, updates the buffer pointer to point to the location after the last output character, and returns the number of characters output.
No more than len characters will be output. If the module name would otherwise be longer, the output is truncated at the point where a potential overflow is detected. The return value always reflects the number of characters output, but it may be less than len.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
Text_putSite() // module-wide
index URL

Convert call site structure to an ASCII character sequence

C synopsis target-domain
Int Text_putSite(Types_Site *site, Char **bufp, Int len);
ARGUMENTS
site — address of the call site structure to interpret
bufp — address of the output buffer pointer or NULL
If bufp is NULL, the site's name characters are output via System.putch().
len — maximum number of characters to generate
If len is negative, the number of characters to be generated is not limited.
DETAILS
This function converts a Types.Site to a sequence of ASCII characters, writes the characters to the supplied buffer, updates the buffer pointer to point to the location after the last output character, and returns the number of characters output.
No more than len characters will be output. If the sequence would otherwise be longer, the output is truncated at the point where a potential overflow is detected.
RETURNS
The return value always reflects the number of characters output, but it may be less than len.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Text_Module_id();
// Get this module's unique id
Bool Text_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Text_Module_heap();
// The heap from which this module allocates memory
Bool Text_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Text_Module_getMask();
// Returns the diagnostics mask for this module
Void Text_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Text.xdc
var Text = xdc.useModule('xdc.runtime.Text');
module-wide config parameters
     Text.isLoaded// Ensure character-strings are loaded in target memory = Bool true;
     Text.nameEmpty// Default NULL instance name = String "{empty-instance-name}";
     Text.nameStatic// Default static instance name = String "{static-instance-name}";
     Text.nameUnknown// Default unknowable instance name = String "{unknown-instance-name}";
     Text.common$// Common module configuration parameters = Types.Common$ undefined;
config Text.isLoaded // module-wide
index URL

Ensure character-strings are loaded in target memory

XDCscript usage meta-domain
Text.isLoaded = Bool true;
DETAILS
Character strings managed by this module are allocated together with other character strings, and loaded to the target, when this parameter is set to its default value true. If this parameter is set to false, the character strings managed by Text are separated in their own section xdc.noload, which is not loaded to the target.
NOTE
For TI and GNU targets, the section xdc.noload is not loaded to the target, but it can overlay other output sections. If the linker allocates xdc.noload so that it overlaps the section that contains character strings when isLoaded is false, ROV/RTA functionality can be affected. In such a case, an error message is displayed that indicates the overlap between xdc.noload and another section, whose name depends on the target (.const on TI targets, .rodata on GNU targets). The user can solve that problem by specifying an address for xdc.noload to unconfigured memory, and ensure that .const and xdc.noload do not overlap.
      Program.sectMap["xdc.noload"] = new prog.SectionSpec();
      Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
C SYNOPSIS
Text_isLoaded
config Text.nameEmpty // module-wide
index URL

Default NULL instance name

XDCscript usage meta-domain
Text.nameEmpty = String "{empty-instance-name}";
DETAILS
The name used if the instance's name has been set to NULL.
C SYNOPSIS
Text_nameEmpty
config Text.nameStatic // module-wide
index URL

Default static instance name

XDCscript usage meta-domain
Text.nameStatic = String "{static-instance-name}";
DETAILS
The name of an instance if the name exists but it's not loaded on the target.
C SYNOPSIS
Text_nameStatic
config Text.nameUnknown // module-wide
index URL

Default unknowable instance name

XDCscript usage meta-domain
Text.nameUnknown = String "{unknown-instance-name}";
DETAILS
The name of an instance if the module's instances are configured to not have names.
C SYNOPSIS
Text_nameUnknown
metaonly config Text.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Text.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Timestamp
index URL

Timestamp services

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides xdc.runtime.ITimestampClient APIs for the xdc Runtime Support Library. Calls to these APIs are forwarded to a platform specific xdc.runtime.ITimestampProvider implementation. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Timestamp.xdc
#include <xdc/runtime/Timestamp.h>
Functions common to all ITimestampClient modules
Bits32 | Timestamp_get32// Return a 32-bit timestamp();
Void | Timestamp_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | Timestamp_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | Timestamp_Module_getMask// Returns the diagnostics mask for this module, Timestamp_Module_hasMask// Test whether this module has a diagnostics mask, Timestamp_Module_heap// The heap from which this module allocates memory, Timestamp_Module_id// Get this module's unique id, Timestamp_Module_setMask// Set the diagnostics mask for this module, Timestamp_Module_startupDone// Test if this module has completed startup
DETAILS
This module provides xdc.runtime.ITimestampClient APIs for the xdc Runtime Support Library. Calls to these APIs are forwarded to a platform specific xdc.runtime.ITimestampProvider implementation.
A user can attach their own ITimestampProvider module using the following config file command:
  xdc.runtime.Timestamp.SupportProxy = xdc.useModule("usersTimestampProvider");
If no such SupportProxy initialization is done, the xdc.runtime.TimestampNull ITimestampProvider implementation, which provides null stubs for the APIs, will be attached by default.
If the user is developing code using CCS, the xdc.runtime.TimestampStd ITimestampProvider implementation, which uses the ANSI C clock() function, may provide a satisfactory timestamp source (remember to enable the profile clock in CCS).
To use the TimestampStd implementation, add the following to your config script:
  xdc.runtime.Timestamp.SupportProxy = xdc.useModule("xdc.runtime.TimestampStd");
Timestamp_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 Timestamp_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
Timestamp_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void Timestamp_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
Timestamp_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void Timestamp_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Timestamp_Module_id();
// Get this module's unique id
Bool Timestamp_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Timestamp_Module_heap();
// The heap from which this module allocates memory
Bool Timestamp_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Timestamp_Module_getMask();
// Returns the diagnostics mask for this module
Void Timestamp_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Timestamp.xdc
var Timestamp = xdc.useModule('xdc.runtime.Timestamp');
local proxy modules
     Timestamp.SupportProxy// User supplied time stamp provider module = ITimestampProvider.Module null
         Timestamp.SupportProxy.delegate$ = ITimestampProvider.Module null
module-wide config parameters
     Timestamp.common$// Common module configuration parameters = Types.Common$ undefined;
proxy Timestamp.SupportProxy
index URL

User supplied time stamp provider module

XDCscript usage meta-domain
Timestamp.SupportProxy = ITimestampProvider.Module null
// some delegate module inheriting the ITimestampProvider interface
    Timestamp.SupportProxy.delegate$ = ITimestampProvider.Module null
    // explicit access to the currently bound delegate module
DETAILS
The SupportProxy module provides application/platform specific implementations of the xdc.runtime.ITimestampProvider APIs.
If not explicitly supplied by the user, this proxy defaults to xdc.runtime.TimestampNull, which provides null stubs for all of the ITimestampProvider APIs.
metaonly config Timestamp.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Timestamp.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.TimestampNull
index URL

Empty implementation of ITimestampProvider

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/TimestampNull.xdc
#include <xdc/runtime/TimestampNull.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampNull_get32// Return a 32-bit timestamp();
Void | TimestampNull_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampNull_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampNull_Module_getMask// Returns the diagnostics mask for this module, TimestampNull_Module_hasMask// Test whether this module has a diagnostics mask, TimestampNull_Module_heap// The heap from which this module allocates memory, TimestampNull_Module_id// Get this module's unique id, TimestampNull_Module_setMask// Set the diagnostics mask for this module, TimestampNull_Module_startupDone// Test if this module has completed startup
TimestampNull_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampNull_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampNull_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampNull_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampNull_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampNull_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampNull_Module_id();
// Get this module's unique id
Bool TimestampNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampNull_Module_heap();
// The heap from which this module allocates memory
Bool TimestampNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampNull_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/TimestampNull.xdc
var TimestampNull = xdc.useModule('xdc.runtime.TimestampNull');
module-wide config parameters
     TimestampNull.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.TimestampStd
index URL

Implementation of ITimestampProvider using ANSI C clock()

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/TimestampStd.xdc
#include <xdc/runtime/TimestampStd.h>
Functions common to all ITimestampClient modules
Bits32 | TimestampStd_get32// Return a 32-bit timestamp();
Void | TimestampStd_get64// Return a 64-bit timestamp(Types_Timestamp64 *result);
Void | TimestampStd_getFreq// Get the timestamp timer's frequency (in Hz)(Types_FreqHz *freq);
Functions common to all target modules
 | TimestampStd_Module_getMask// Returns the diagnostics mask for this module, TimestampStd_Module_hasMask// Test whether this module has a diagnostics mask, TimestampStd_Module_heap// The heap from which this module allocates memory, TimestampStd_Module_id// Get this module's unique id, TimestampStd_Module_setMask// Set the diagnostics mask for this module, TimestampStd_Module_startupDone// Test if this module has completed startup
TimestampStd_get32() // module-wide
index URL

Return a 32-bit timestamp

C synopsis target-domain
Bits32 TimestampStd_get32();
RETURNS
Returns a 32-bit timestamp value. Use getFreq to convert this value into units of real time.
SEE
get64
TimestampStd_get64() // module-wide
index URL

Return a 64-bit timestamp

C synopsis target-domain
Void TimestampStd_get64(Types_Timestamp64 *result);
ARGUMENTS
result — pointer to 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide timestamp value where the current timestamp is written.
If the underlying hardware does not support 64-bit resolution, the hi field of result is always set to 0; see xdc.runtime.Types.Timestamp64. So, it is possible for the lo field to wrap around without any change to the hi field. Use getFreq to convert this value into units of real time.
SEE
get32
TimestampStd_getFreq() // module-wide
index URL

Get the timestamp timer's frequency (in Hz)

C synopsis target-domain
Void TimestampStd_getFreq(Types_FreqHz *freq);
ARGUMENTS
freq — pointer to a 64-bit result
This parameter is a pointer to a structure representing a 64-bit wide frequency value where the timer's frequency (in Hz) is written; see xdc.runtime.Types.FreqHz. This function provides a way of converting timestamp values into units of real time.
SEE
get32, get64
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TimestampStd_Module_id();
// Get this module's unique id
Bool TimestampStd_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle TimestampStd_Module_heap();
// The heap from which this module allocates memory
Bool TimestampStd_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 TimestampStd_Module_getMask();
// Returns the diagnostics mask for this module
Void TimestampStd_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/TimestampStd.xdc
var TimestampStd = xdc.useModule('xdc.runtime.TimestampStd');
module-wide config parameters
     TimestampStd.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config TimestampStd.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TimestampStd.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:33 GMT


module xdc.runtime.Types
index URL

Basic constants and types

  • C synopsis
  • Individual elements
  • DETAILS
  • EXAMPLES
  • XDCscript usage
  • Individual elements
This module defines basic constants and types used throughout the xdc.runtime package and, in some cases, in every module. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Types.xdc
#include <xdc/runtime/Types.h>
Functions
macro Types_RopeId | Types_getEventId// Get event ID of the specified event(Types_Event evt);
macro Types_ModuleId | Types_getModuleId// Get the module ID for the specified event(Types_Event evt);
macro Types_Event | Types_makeEvent// Make an Event from an Event ID and a module ID(Types_RopeId id, Types_ModuleId callSite);
Functions common to all target modules
 | Types_Module_getMask// Returns the diagnostics mask for this module, Types_Module_hasMask// Test whether this module has a diagnostics mask, Types_Module_heap// The heap from which this module allocates memory, Types_Module_id// Get this module's unique id, Types_Module_setMask// Set the diagnostics mask for this module, Types_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum | Types_CreatePolicy// Instance creation policy ...
typedef Bits16 | Types_DiagsMask// ;
typedef Bits32 | Types_Event// ILogger event encoding;
typedef struct | Types_FreqHz// Frequency-in-hertz struct ...
typedef struct | Types_Label// Instance label struct ...
typedef Bits16 | Types_ModuleId// Unique module identifier;
typedef struct | Types_RegDesc// Registry module descriptor ...
typedef struct | Types_Site// Error site description struct ...
typedef struct | Types_Timestamp64// 64-bit timestamp struct ...
DETAILS
This module defines basic constants and types used throughout the xdc.runtime package and, in some cases, in every module.
The Common$ structure defined by the Types module is available for (or common to) all modules. Every field of the Common$ structure is a configuration parameter that may be set within a configuration script for any module (not just the xdc.runtime modules). The fields of this structure are typically read by the modules in the xdc.runtime package at configuration time to control the generation of data structures that are embedded in the application and referenced by these modules at runtime.
Every module has a configuration parameter named common$ that is of type Common$. This allows the user of any module to control the module's diagnostics, where its instances are allocated, how they are allocated, and (for gated modules) what gate it should use to protect critical sections.
EXAMPLES
Configuration example: The following configuration script specifies that the instance objects managed by the Memory module in the xdc.runtime package should be placed in the ".fast" memory section and that ENTRY diagnostics should be available at runtime.
      var Memory = xdc.useModule('xdc.runtime.Memory");
      Memory.common$.instanceSection = ".fast";
      Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF
Note that by setting Memory.common$.diags_ENTRY to Diags.RUNTIME_OFF we are both enabling ENTRY events and specifying that they are initially disabled; they must be explicitly enabled at runtime. See the Diags modules for additional information.
enum Types_CreatePolicy
index URL

Instance creation policy

C synopsis target-domain
typedef enum Types_CreatePolicy {
    Types_STATIC_POLICY,
    // static creation only; no runtime create/delete
    Types_CREATE_POLICY,
    // dynamic creation, but no deletion
    Types_DELETE_POLICY
    // dynamic creation and deletion
} Types_CreatePolicy;
typedef Types_DiagsMask
index URL
C synopsis target-domain
typedef Bits16 Types_DiagsMask;
typedef Types_Event
index URL

ILogger event encoding

C synopsis target-domain
typedef Bits32 Types_Event;
DETAILS
Whereas a Log.Event encodes an event ID and a mask, a Types_Event encodes the same event ID and the module ID of the module containing the call site that generated the Types_Event.
typedef Types_ModuleId
index URL

Unique module identifier

C synopsis target-domain
typedef Bits16 Types_ModuleId;
DETAILS
Module IDs are assigned at configuration time based in the set of modules that are "used" in the application. So, although each module has a unique 16-bit ID at runtime this ID may vary between configurations of the application.
To save precious data space, module names are managed by the Text module and it is this table that is used to assign module IDs. If the table is maintained on the target, the module ID is an "index" into this table; otherwise, the module ID is simply a unique integer less than the total number of modules in the application.
Although module IDs are not independent of an application's configuration, a module's ID may be compared to a runtime value symbolically. Every module has a (generated) method that returns the module's ID; e.g., a module named Task has a method named Task_Module_id() which returns Task's module ID.
      #include <xdc/runtime/Types.h>
      #include <ti/sysbios/knl/Task.h>
         :
      void checkId(Types_ModuleId modId) {
          if (Task_Module_id() == modId) {
              System_printf("Task module");
          }
      }
struct Types_FreqHz
index URL

Frequency-in-hertz struct

C synopsis target-domain
typedef struct Types_FreqHz {
    Bits32 hi;
    // most significant 32-bits of frequency
    Bits32 lo;
    // least significant 32-bits of frequency
} Types_FreqHz;
struct Types_Label
index URL

Instance label struct

C synopsis target-domain
typedef struct Types_Label {
    Ptr handle;
    // instance object address
     Types_ModuleId modId;
    // corresponding module id
    String iname;
    // name supplied during instance creation
    Bool named;
    // true, if iname is available
} Types_Label;
DETAILS
Label structures are used to provide human readable names for instance handles.
It is possible to initialize a Label from any instance handle. All modules that support instances provide a method named Mod_Handle_label() which, given an instance handle and a pointer to a Label structure, initializes the structure with all available information. For example, the following code fragment initializes a Label from an instance of the HeapMin module.
      HeapMin_Handle heap;
      Types_Label label;
      HeapMin_Handle_label(heap, &label);
Unless you explicitly disable it, System_printf can be used to convert a pointer to a Label into an human readable "instance name". Continuing with the example above, the following line can be used to print the an instance's label.
      System_printf("heap instance name: %$L\n", &label);
SEE
System.printf, System.extendedFormats, Text.putLabel
struct Types_RegDesc
index URL

Registry module descriptor

C synopsis target-domain
typedef struct Types_RegDesc {
     Types_RegDesc *next;
    String modName;
     Types_ModuleId id;
     Types_DiagsMask mask;
} Types_RegDesc;
struct Types_Site
index URL

Error site description struct

C synopsis target-domain
typedef struct Types_Site {
     Types_ModuleId mod;
    // module id of this site
    String file;
    // filename of this site
    Int line;
    // line number of this site
} Types_Site;
FIELDS
mod — the module id of the module containing the call site
file — the name of the file containing the call site or NULL; some call sites omit the file name to save data space.
line — the line number within the file named
DETAILS
This structure describes the location of the line that raised an error.
struct Types_Timestamp64
index URL

64-bit timestamp struct

C synopsis target-domain
typedef struct Types_Timestamp64 {
    Bits32 hi;
    // most significant 32-bits of timestamp
    Bits32 lo;
    // least significant 32-bits of timestamp
} Types_Timestamp64;
DETAILS
Some platforms only support 32-bit timestamps. In this case, the most significant 32-bits are always set to 0.
Types_getEventId() // module-wide
index URL

Get event ID of the specified event

C synopsis target-domain
macro Types_RopeId Types_getEventId(Types_Event evt);
ARGUMENTS
evt — an event created via makeEvent
DETAILS
This method is used to get an ID that can be compared to other "known" IDs. For example, after a Types_Event is generated, the following code determines if the event corresponds to a Log.L_create event:
      Bool isCreateEvent(Types_Event evt) {
          return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
      }
RETURNS
This function returns the event ID of a specified event.
Types_getModuleId() // module-wide
index URL

Get the module ID for the specified event

C synopsis target-domain
macro Types_ModuleId Types_getModuleId(Types_Event evt);
ARGUMENTS
evt — an event created via makeEvent
RETURNS
This function returns the module ID of a specified event.
Types_makeEvent() // module-wide
index URL

Make an Event from an Event ID and a module ID

C synopsis target-domain
macro Types_Event Types_makeEvent(Types_RopeId id, Types_ModuleId callSite);
ARGUMENTS
id — ID of the event itself
callSite — the module from which this event originated
RETURNS
This function returns an event.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Types_Module_id();
// Get this module's unique id
Bool Types_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Types_Module_heap();
// The heap from which this module allocates memory
Bool Types_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Types_Module_getMask();
// Returns the diagnostics mask for this module
Void Types_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/Types.xdc
var Types = xdc.useModule('xdc.runtime.Types');
module-wide constants & types
    values of type Types.CreatePolicy// Instance creation policy
        const Types.STATIC_POLICY// static creation only; no runtime create/delete;
        const Types.CREATE_POLICY// dynamic creation, but no deletion;
        const Types.DELETE_POLICY// dynamic creation and deletion;
    var obj = new Types.Common$// Common module config struct;
        obj.diags_ASSERT// module's Diags assert mode = Diags.Mode ...
        obj.diags_ENTRY// module's function entry Diags mode = Diags.Mode ...
        obj.diags_EXIT// module's function exit Diags mode = Diags.Mode ...
        obj.diags_INTERNAL// module's internal assert mode = Diags.Mode ...
        obj.diags_LIFECYCLE// module's instance lifecycle mode = Diags.Mode ...
        obj.diags_STATUS// module's errors and warnings = Diags.Mode ...
        obj.diags_USER1// module's user1 Diags mode = Diags.Mode ...
        obj.diags_USER2// module's user2 Diags mode = Diags.Mode ...
        obj.diags_USER3// module's user3 Diags mode = Diags.Mode ...
        obj.diags_USER4// module's user4 Diags mode = Diags.Mode ...
        obj.diags_USER5// module's user5 Diags mode = Diags.Mode ...
        obj.diags_USER6// module's user6 Diags mode = Diags.Mode ...
        obj.diags_USER7// module's user7 Diags mode = Diags.Mode ...
        obj.diags_INFO// module's informational event mode = Diags.Mode ...
        obj.diags_USER8// module's user8 Diags mode = Diags.Mode ...
        obj.diags_ANALYSIS// module's Diags analysis mode = Diags.Mode ...
        obj.fxntab = Bool ...
        obj.gate// module's gate = IGateProvider.Handle ...
        obj.gateParams// gate params for module created gates = Ptr ...
        obj.instanceHeap// module's instance heap = IHeap.Handle ...
        obj.instanceSection// memory section for module's instances = String ...
        obj.logger// module's logger = ILogger.Handle ...
        obj.memoryPolicy// module's memory policy = Types.CreatePolicy ...
        obj.namedInstance// true => instances have string names = Bool ...
        obj.namedModule// true => module's name is on target = Bool ...
        obj.romPatchTable = Bool ...
    var obj = new Types.FreqHz// Frequency-in-hertz struct;
        obj.hi// most significant 32-bits of frequency = Bits32 ...
        obj.lo// least significant 32-bits of frequency = Bits32 ...
    var obj = new Types.Label// Instance label struct;
        obj.handle// instance object address = Ptr ...
        obj.modId// corresponding module id = Bits16 ...
        obj.iname// name supplied during instance creation = String ...
        obj.named// true, if iname is available = Bool ...
    var obj = new Types.RegDesc// Registry module descriptor;
        obj.next = Types.RegDesc* ...
        obj.modName = String ...
        obj.id = Bits16 ...
        obj.mask = Bits16 ...
    var obj = new Types.Site// Error site description struct;
        obj.mod// module id of this site = Bits16 ...
        obj.file// filename of this site = String ...
        obj.line// line number of this site = Int ...
    var obj = new Types.Timestamp64// 64-bit timestamp struct;
        obj.hi// most significant 32-bits of timestamp = Bits32 ...
        obj.lo// least significant 32-bits of timestamp = Bits32 ...
module-wide config parameters
     Types.common$// Common module configuration parameters = Types.Common$ undefined;
enum Types.CreatePolicy
index URL

Instance creation policy

XDCscript usage meta-domain
values of type Types.CreatePolicy
    const Types.STATIC_POLICY;
    // static creation only; no runtime create/delete
    const Types.CREATE_POLICY;
    // dynamic creation, but no deletion
    const Types.DELETE_POLICY;
    // dynamic creation and deletion
C SYNOPSIS
Types_CreatePolicy
metaonly struct Types.Common$
index URL

Common module config struct

XDCscript usage meta-domain
var obj = new Types.Common$;
    obj.diags_ASSERT = Diags.Mode ...
    // module's Diags assert mode
    obj.diags_ENTRY = Diags.Mode ...
    // module's function entry Diags mode
    obj.diags_EXIT = Diags.Mode ...
    // module's function exit Diags mode
    obj.diags_INTERNAL = Diags.Mode ...
    // module's internal assert mode
    obj.diags_LIFECYCLE = Diags.Mode ...
    // module's instance lifecycle mode
    obj.diags_STATUS = Diags.Mode ...
    // module's errors and warnings
    obj.diags_USER1 = Diags.Mode ...
    // module's user1 Diags mode
    obj.diags_USER2 = Diags.Mode ...
    // module's user2 Diags mode
    obj.diags_USER3 = Diags.Mode ...
    // module's user3 Diags mode
    obj.diags_USER4 = Diags.Mode ...
    // module's user4 Diags mode
    obj.diags_USER5 = Diags.Mode ...
    // module's user5 Diags mode
    obj.diags_USER6 = Diags.Mode ...
    // module's user6 Diags mode
    obj.diags_USER7 = Diags.Mode ...
    // module's user7 Diags mode
    obj.diags_INFO = Diags.Mode ...
    // module's informational event mode
    obj.diags_USER8 = Diags.Mode ...
    // module's user8 Diags mode
    obj.diags_ANALYSIS = Diags.Mode ...
    // module's Diags analysis mode
    obj.fxntab = Bool ...
    obj.gate = IGateProvider.Handle ...
    // module's gate
    obj.gateParams = Ptr ...
    // gate params for module created gates
    obj.instanceHeap = IHeap.Handle ...
    // module's instance heap
    obj.instanceSection = String ...
    // memory section for module's instances
    obj.logger = ILogger.Handle ...
    // module's logger
    obj.memoryPolicy = Types.CreatePolicy ...
    // module's memory policy
    obj.namedInstance = Bool ...
    // true => instances have string names
    obj.namedModule = Bool ...
    // true => module's name is on target
    obj.romPatchTable = Bool ...
FIELDS
diags_ASSERT — The Diags.ASSERT bit of a module's diagnostics mask.
diags_ENTRY — The Diags.ENTRY category of a module's diagnostics mask.
diags_EXIT — The Diags.EXIT category of a module's diagnostics mask.
diags_INTERNAL — The Diags.INTERNAL bit of a module's diagnostics mask.
diags_LIFECYCLE — The Diags.LIFECYCLE category of a module's diagnostics mask.
diags_STATUS — The Diags.STATUS category of a module's diagnostics mask.
diags_USER1 — The Diags.USER1 category of a module's diagnostics mask.
diags_USER2 — The Diags.USER2 category of a module's diagnostics mask.
diags_USER3 — The Diags.USER3 category of a module's diagnostics mask.
diags_USER4 — The Diags.USER4 category of a module's diagnostics mask.
diags_USER5 — The Diags.USER5 category of a module's diagnostics mask.
diags_USER6 — The Diags.USER6 category of a module's diagnostics mask.
diags_USER7 — The Diags.USER7 category of a module's diagnostics mask. The bit for this category has been repurposed for the Diags.INFO category, so the use of USER7 has been deprecated.
diags_INFO — The Diags.INFO category of a module's diagnostics mask.
diags_USER8 — The Diags.USER8 category of a module's diagnostics mask. The bit for this category has been repurposed for the Diags.ANALYSIS category, so the use of USER8 has been deprecated.
diags_ANALYSIS — The Diags.ANALYSIS category of a module's diagnostics mask.
fxntab — This configurtation parameter is only applicable to modules that inherit an interface and have instance objects. Setting fxntab to false can save some data space but also prevents the application from using instance objects through abstract interfaces.
Function tables are used whenever it's necessary to call a module's methods via an abstract interface; e.g., the Memory module calls methods defined by the IHeap interface but there may be several distinct modules that implement this interface. In order for this type of call to be possible, instance objects contain a reference to a function table containing the instance module's functions; the caller gets the module's function from the instance object and calls through a function pointer. Every module that inherits an interface has such a table and modules that do not inherit an interface do not have a function table.
If this configuration parameter is set to false, the module's instance objects will NOT be initialized with a reference to their module's function table and, since the function table will not be referenced by the application, the resulting executable will be smaller. However, if this parameter is false you must never attempt to use this module's instance objects via reference this module through an abstract interface. Since this is often hard to determine, especially as an application evolves over time, you should only set this parameter to false when you are absolutely sure that the module's functions are always only being directly called and you need to absolutely minimize the data footprint of your application.
The default for this parameter is true.
gate — A handle to the module-level IGateProvider instance to be used when this module calls functions from Gate
gateParams — Gate parameters used by this module to create the gates used when this module calls Gate_allocInstance
instanceHeap — Identifies the heap from which this module should allocate memory.
instanceSection — Identifies the section in which instances created by this module should be placed.
logger — The handle of the logger instance used by the module. All log events generated by the module are routed to this logger instance. See ILogger for details on the logger interface. See LoggerBuf and LoggerSys for two examples of logger modules provided by the xdc.runtime package.
memoryPolicy — Specifies whether this module should allow static object creation only (STATIC_POLICY), dynamic object creation but not deletion (CREATE_POLICY), or both dynamic object creation and deletion (DELETE_POLICY).
namedInstance — If set to true, each instance object is given an additional field to hold a string name that is used when displaying information about an instance. Setting this to true increases the size of the module's instance objects by a single word but improves the usability of tools that display instance objects. If set to 'false', assignments of instance names are silently ignored. This allows one to remove instance name support to save space without having to change any source code. See IInstance.name for details.
namedModule — If set to true, this module's string name is retained on the target so that it can be displayed as part of Log and Error events. Setting this to false saves data space in the application at the expense of readability of log and error messages associated with this module.
Note: setting this to false also prevents one from controlling the module's diagnostics at runtime via Diags.setMask(). This method uses the module's name to lookup the module's diagnostics mask. It is still possible to control the module's diagnostics at design-time from a configuration script.
DETAILS
Every module contains this structure during the configuration phase. The fields of this structure are set in configuration scripts and referenced by the modules in the xdc.runtime package. For default values of these fields, see Defaults.
SEE
Diags, Defaults
struct Types.FreqHz
index URL

Frequency-in-hertz struct

XDCscript usage meta-domain
var obj = new Types.FreqHz;
    obj.hi = Bits32 ...
    // most significant 32-bits of frequency
    obj.lo = Bits32 ...
    // least significant 32-bits of frequency
C SYNOPSIS
Types_FreqHz
struct Types.Label
index URL

Instance label struct

XDCscript usage meta-domain
var obj = new Types.Label;
    obj.handle = Ptr ...
    // instance object address
    obj.modId = Bits16 ...
    // corresponding module id
    obj.iname = String ...
    // name supplied during instance creation
    obj.named = Bool ...
    // true, if iname is available
DETAILS
Label structures are used to provide human readable names for instance handles.
It is possible to initialize a Label from any instance handle. All modules that support instances provide a method named Mod_Handle_label() which, given an instance handle and a pointer to a Label structure, initializes the structure with all available information. For example, the following code fragment initializes a Label from an instance of the HeapMin module.
      HeapMin_Handle heap;
      Types_Label label;
      HeapMin_Handle_label(heap, &label);
Unless you explicitly disable it, System_printf can be used to convert a pointer to a Label into an human readable "instance name". Continuing with the example above, the following line can be used to print the an instance's label.
      System_printf("heap instance name: %$L\n", &label);
SEE
System.printf, System.extendedFormats, Text.putLabel
C SYNOPSIS
Types_Label
struct Types.RegDesc
index URL

Registry module descriptor

XDCscript usage meta-domain
var obj = new Types.RegDesc;
    obj.next = Types.RegDesc* ...
    obj.modName = String ...
    obj.id = Bits16 ...
    obj.mask = Bits16 ...
C SYNOPSIS
Types_RegDesc
struct Types.Site
index URL

Error site description struct

XDCscript usage meta-domain
var obj = new Types.Site;
    obj.mod = Bits16 ...
    // module id of this site
    obj.file = String ...
    // filename of this site
    obj.line = Int ...
    // line number of this site
FIELDS
mod — the module id of the module containing the call site
file — the name of the file containing the call site or NULL; some call sites omit the file name to save data space.
line — the line number within the file named
DETAILS
This structure describes the location of the line that raised an error.
C SYNOPSIS
Types_Site
struct Types.Timestamp64
index URL

64-bit timestamp struct

XDCscript usage meta-domain
var obj = new Types.Timestamp64;
    obj.hi = Bits32 ...
    // most significant 32-bits of timestamp
    obj.lo = Bits32 ...
    // least significant 32-bits of timestamp
DETAILS
Some platforms only support 32-bit timestamps. In this case, the most significant 32-bits are always set to 0.
C SYNOPSIS
Types_Timestamp64
metaonly config Types.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Types.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:34 GMT


package xdc.runtime.knl
index URL

XDC Runtime support for OS-related primitives

XDCspec declarations sourced in xdc/runtime/knl/package.xdc
package xdc.runtime.knl [1, 0, 0] {
    interface ICacheSupport;
    // Interface for OS specific back-end
    interface IGateProcessSupport;
    // Interface for OS specific back-end
    interface IGateThreadSupport;
    // Interface for OS specific back-end
    interface ISemProcessSupport;
    // Interface for OS specific back-end
    interface ISemThreadSupport;
    // Interface for OS specific back-end
    interface ISemaphore;
    // Interface implemented by all front-end semaphore providers
    interface ISync;
    // OS independent synchronization
    interface IThreadSupport;
    // Interface for OS specific back-end
    module Cache;
    // Cache Services
    module CacheSupportNull;
    // Empty ICacheSupport implementation
    module GateH;
    // Provides APIs to protect critical sections when an IGate.Handle is available
    module GateProcess;
    // Provides protection of critical sections across processes
    module GateProcessSupportNull;
    // Empty IGateProcessSupport implementation
    module GateThread;
    // Provides protection of critical sections across threads
    module GateThreadSupportNull;
    // Empty IGateProcessSupport implementation
    module SemProcess;
    // SemProcess Manager
    module SemThread;
    // SemThread Manager
    module Semaphore;
    // Provides semaphore services when an ISemaphore.Handle is available
    module Sync;
    // Provides synchronization APIs when an ISync.Handle is available
    module SyncGeneric;
    // Generic ISync implementation
    module SyncNull;
    // Empty ISync implementation used mainly for testing
    module SyncSemThread;
    // A ISync implementation based on a SemThread. [EXPERIMENTAL]
    module Thread;
    // Thread services
}
generated on Fri, 17 Jun 2011 00:24:39 GMT


module xdc.runtime.knl.Cache
index URL

Cache Services

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The Cache module provide APIs to allow applications to maintain cache coherency. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/Cache.xdc
#include <xdc/runtime/knl/Cache.h>
Functions
Bool | Cache_inv// Invalidate range of memory for all cache(s)(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Bool | Cache_wait// Wait for a previous cache operation to complete(Error_Block *eb);
Bool | Cache_wb// Writes back a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Bool | Cache_wbInv// Write back and invalidate range of memory(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Functions common to all target modules
 | Cache_Module_getMask// Returns the diagnostics mask for this module, Cache_Module_hasMask// Test whether this module has a diagnostics mask, Cache_Module_heap// The heap from which this module allocates memory, Cache_Module_id// Get this module's unique id, Cache_Module_setMask// Set the diagnostics mask for this module, Cache_Module_startupDone// Test if this module has completed startup
DETAILS
The Cache module provide APIs to allow applications to maintain cache coherency.
This module will use an OS specific delegate (back-end) to manipulate the cache. This module has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var Cache = xdc.useModule('xdc.runtime.knl.Cache');
  Cache.Proxy = xdc.useModule('ti.sysbios.xdcruntime.CacheSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
Cache_inv() // module-wide
index URL

Invalidate range of memory for all cache(s)

C synopsis target-domain
Bool Cache_inv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all cache types.
RETURNS
true for success; false for error.
Cache_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Bool Cache_wait(Error_Block *eb);
ARGUMENTS
eb — error block
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
RETURNS
true for success; false for error.
Cache_wb() // module-wide
index URL

Writes back a range of memory from all cache(s)

C synopsis target-domain
Bool Cache_wb(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes back the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in all caches and the data within the range will be written back to the source memory.
RETURNS
true for success; false for error.
Cache_wbInv() // module-wide
index URL

Write back and invalidate range of memory

C synopsis target-domain
Bool Cache_wbInv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes back and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written back to the source memory and then invalidated for all cache types.
RETURNS
true for success; false for error.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Cache_Module_id();
// Get this module's unique id
Bool Cache_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Cache_Module_heap();
// The heap from which this module allocates memory
Bool Cache_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Cache_Module_getMask();
// Returns the diagnostics mask for this module
Void Cache_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/knl/Cache.xdc
var Cache = xdc.useModule('xdc.runtime.knl.Cache');
local proxy modules
     Cache.Proxy// ICacheSupport proxy = ICacheSupport.Module null
         Cache.Proxy.delegate$ = ICacheSupport.Module null
module-wide config parameters
     Cache.common$// Common module configuration parameters = Types.Common$ undefined;
proxy Cache.Proxy
index URL

ICacheSupport proxy

XDCscript usage meta-domain
Cache.Proxy = ICacheSupport.Module null
// some delegate module inheriting the ICacheSupport interface
    Cache.Proxy.delegate$ = ICacheSupport.Module null
    // explicit access to the currently bound delegate module
DETAILS
Cache will use this proxy to access the cache hardware using OS specific APIs.
metaonly config Cache.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Cache.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.CacheSupportNull
index URL

Empty ICacheSupport implementation

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/knl/CacheSupportNull.xdc
#include <xdc/runtime/knl/CacheSupportNull.h>
Functions common to all ICacheSupport modules
Bool | CacheSupportNull_inv// Invalidates range of memory(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Bool | CacheSupportNull_wait// Wait for a previous cache operation to complete(Error_Block *eb);
Bool | CacheSupportNull_wb// Writes a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Bool | CacheSupportNull_wbInv// Writes back and invalidates range fo memory(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
Functions common to all target modules
 | CacheSupportNull_Module_getMask// Returns the diagnostics mask for this module, CacheSupportNull_Module_hasMask// Test whether this module has a diagnostics mask, CacheSupportNull_Module_heap// The heap from which this module allocates memory, CacheSupportNull_Module_id// Get this module's unique id, CacheSupportNull_Module_setMask// Set the diagnostics mask for this module, CacheSupportNull_Module_startupDone// Test if this module has completed startup
CacheSupportNull_inv() // module-wide
index URL

Invalidates range of memory

C synopsis target-domain
Bool CacheSupportNull_inv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches.
RETURNS
true for success; false for error.
CacheSupportNull_wait() // module-wide
index URL

Wait for a previous cache operation to complete

C synopsis target-domain
Bool CacheSupportNull_wait(Error_Block *eb);
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
RETURNS
true for success; false for error.
CacheSupportNull_wb() // module-wide
index URL

Writes a range of memory from all cache(s)

C synopsis target-domain
Bool CacheSupportNull_wb(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written to the source memory.
RETURNS
true for success; false for error.
CacheSupportNull_wbInv() // module-wide
index URL

Writes back and invalidates range fo memory

C synopsis target-domain
Bool CacheSupportNull_wbInv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error_Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written to the source memory and then invalidated for all 'type' caches.
RETURNS
true for success; false for error.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId CacheSupportNull_Module_id();
// Get this module's unique id
Bool CacheSupportNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle CacheSupportNull_Module_heap();
// The heap from which this module allocates memory
Bool CacheSupportNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 CacheSupportNull_Module_getMask();
// Returns the diagnostics mask for this module
Void CacheSupportNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/knl/CacheSupportNull.xdc
var CacheSupportNull = xdc.useModule('xdc.runtime.knl.CacheSupportNull');
module-wide config parameters
     CacheSupportNull.common$// Common module configuration parameters = Types.Common$ undefined;
metaonly config CacheSupportNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
CacheSupportNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.GateH
index URL

Provides APIs to protect critical sections when an IGate.Handle is available

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
An application can isolate itself from IGate implementations by using this module. The application must first obtain an IGate.Handle. It can get such a handle by directly calling GateThread.create or GateProcess.create. Then the application can use the generic APIs provided by this module. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/GateH.xdc
#include <xdc/runtime/knl/GateH.h>
Functions
IArg | GateH_enter// Enter a gate(IGateProvider_Handle hdl);
Void | GateH_leave// Leave a gate(IGateProvider_Handle hdl, IArg key);
Functions common to all target modules
 | GateH_Module_getMask// Returns the diagnostics mask for this module, GateH_Module_hasMask// Test whether this module has a diagnostics mask, GateH_Module_heap// The heap from which this module allocates memory, GateH_Module_id// Get this module's unique id, GateH_Module_setMask// Set the diagnostics mask for this module, GateH_Module_startupDone// Test if this module has completed startup
DETAILS
An application can isolate itself from IGate implementations by using this module. The application must first obtain an IGate.Handle. It can get such a handle by directly calling GateThread.create or GateProcess.create. Then the application can use the generic APIs provided by this module.
The underlying gates are nexting in nature and users have to leave the gate as many times as they entered it.
GateH_enter() // module-wide
index URL

Enter a gate

C synopsis target-domain
IArg GateH_enter(IGateProvider_Handle hdl);
ARGUMENTS
hdl — IGateProvider.Handle
RETURNS
key
GateH_leave() // module-wide
index URL

Leave a gate

C synopsis target-domain
Void GateH_leave(IGateProvider_Handle hdl, IArg key);
ARGUMENTS
hdl — IGateProvider.Handle
key — key returned by enter();
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateH_Module_id();
// Get this module's unique id
Bool GateH_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateH_Module_heap();
// The heap from which this module allocates memory
Bool GateH_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateH_Module_getMask();
// Returns the diagnostics mask for this module
Void GateH_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/knl/GateH.xdc
var GateH = xdc.useModule('xdc.runtime.knl.GateH');
local proxy modules
     GateH.Proxy// Proxy used for optimization = IGateProvider.Module null
         GateH.Proxy.delegate$ = IGateProvider.Module null
         GateH.Proxy.abstractInstances$ = false
module-wide config parameters
     GateH.common$// Common module configuration parameters = Types.Common$ undefined;
proxy GateH.Proxy
index URL

Proxy used for optimization

XDCscript usage meta-domain
GateH.Proxy = IGateProvider.Module null
// some delegate module inheriting the IGateProvider interface
    GateH.Proxy.delegate$ = IGateProvider.Module null
    // explicit access to the currently bound delegate module
    GateH.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
DETAILS
If ALL IGateProvider.Handles used by GateH are created using the same module (e.g GateProcess) then setting this Proxy to GateProcess and setting GateH.Proxy.abstractInstances$ = false, causes GateH APIs can have better performance.
metaonly config GateH.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateH.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.GateProcess
index URL

Provides protection of critical sections across processes

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides services through its proxy IGateProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/GateProcess.xdc
#include <xdc/runtime/knl/GateProcess.h>
Functions
Void | GateProcess_construct// Initialize a new instance object inside the provided structure(GateProcess_Struct *structP, const GateProcess_Params *params, Error_Block *eb);
GateProcess_Handle | GateProcess_create// Allocate and initialize a new instance object and return its handle(const GateProcess_Params *params, Error_Block *eb);
Void | GateProcess_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateProcess_Handle *handleP);
Void | GateProcess_destruct// Finalize the instance object inside the provided structure(GateProcess_Struct *structP);
Int | GateProcess_getReferenceCount// Get the number of processes with references to this Gate(GateProcess_Handle handle, Error_Block *eb);
Void | GateProcess_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateProcess_Params *params);
Functions common to all IGateProvider modules
IArg | GateProcess_enter// Enter this gate(GateProcess_Handle handle);
Void | GateProcess_leave// Leave this gate(GateProcess_Handle handle, IArg key);
Bool | GateProcess_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateProcess_handle// Convert this instance structure pointer into an instance handle, GateProcess_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateProcess_Handle_label// The label associated with this instance object, GateProcess_Handle_name// The name of this instance object, GateProcess_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateProcess_Object_count// The number of statically-created instance objects, GateProcess_Object_first// The handle of the first dynamically-created instance object, or NULL, GateProcess_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateProcess_Object_heap// The heap used to allocate dynamically-created instance objects, GateProcess_Object_next// The handle of the next dynamically-created instance object, or NULL, GateProcess_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateProcess_Module_getMask// Returns the diagnostics mask for this module, GateProcess_Module_hasMask// Test whether this module has a diagnostics mask, GateProcess_Module_heap// The heap from which this module allocates memory, GateProcess_Module_id// Get this module's unique id, GateProcess_Module_setMask// Set the diagnostics mask for this module, GateProcess_Module_startupDone// Test if this module has completed startup
Defines
#define | GateProcess_GETREFCOUNT_FAILED// Status returned by getReferenceCount when there is an error (Int)-1
#define | GateProcess_Q_BLOCKING// Blocking quality (Int)1
#define | GateProcess_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateProcess_Object * | GateProcess_Handle// Client reference to an instance object;
typedef struct | GateProcess_Object// Opaque internal representation of an instance object GateProcess_Object;
typedef struct | GateProcess_Params// Instance config-params structure ...
typedef struct | GateProcess_Struct// Opaque client structure large enough to hold an instance object GateProcess_Struct;
Constants
extern const Assert_Id | GateProcess_A_invalidKey// Assert when an invalid key is passed to create;
DETAILS
This module provides services through its proxy IGateProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var GateProcess = xdc.useModule('xdc.runtime.knl.GateProcess');
  GateProcess.Proxy =
      xdc.useModule('ti.sysbios.xdcruntime.GateProcessSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
const GateProcess_GETREFCOUNT_FAILED
index URL

Status returned by getReferenceCount when there is an error

C synopsis target-domain
#define GateProcess_GETREFCOUNT_FAILED (Int)-1
const GateProcess_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateProcess_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateProcess_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateProcess_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
config GateProcess_A_invalidKey // module-wide
index URL

Assert when an invalid key is passed to create

C synopsis target-domain
extern const Assert_Id GateProcess_A_invalidKey;
GateProcess_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateProcess_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateProcess_Module_id();
// Get this module's unique id
Bool GateProcess_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateProcess_Module_heap();
// The heap from which this module allocates memory
Bool GateProcess_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateProcess_Module_getMask();
// Returns the diagnostics mask for this module
Void GateProcess_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateProcess_Object GateProcess_Object;
// Opaque internal representation of an instance object
typedef GateProcess_Object *GateProcess_Handle;
// Client reference to an instance object
typedef struct GateProcess_Struct GateProcess_Struct;
// Opaque client structure large enough to hold an instance object
GateProcess_Handle GateProcess_handle(GateProcess_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateProcess_Struct *GateProcess_struct(GateProcess_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateProcess_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Int key;
    // globally unique key for SysV-style semaphore
} GateProcess_Params;
Void GateProcess_Params_init(GateProcess_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config GateProcess_key // instance
index URL

globally unique key for SysV-style semaphore

C synopsis target-domain
struct GateProcess_Params {
     ...
    Int key;
DETAILS
This is a required parameter.
Instance Creation
index URL

C synopsis target-domain
GateProcess_Handle GateProcess_create(const GateProcess_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateProcess_construct(GateProcess_Struct *structP, const GateProcess_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new GateProcess object which is initialized to count. All gates created with the same key reference the same underlying synchronization object and work between processes. For compatibility with the IGateProvider interface the argument key is passes in the params struct rather than as a full argument, but it is required. Therefore calling this function with a NULL params struct is illegal.
Instance Deletion
index URL

C synopsis target-domain
Void GateProcess_delete(GateProcess_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateProcess_destruct(GateProcess_Struct *structP);
// Finalize the instance object inside the provided structure
GateProcess_enter() // instance
index URL

Enter this gate

C synopsis target-domain
IArg GateProcess_enter(GateProcess_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateProcess instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
GateProcess_getReferenceCount() // instance
index URL

Get the number of processes with references to this Gate

C synopsis target-domain
Int GateProcess_getReferenceCount(GateProcess_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created GateProcess instance object
eb — Pointer to Error.Block
RETURNS
Returns the number of processes that possess a reference to this gate, or GETREFCOUNT_FAILED if an error occured.
GateProcess_leave() // instance
index URL

Leave this gate

C synopsis target-domain
Void GateProcess_leave(GateProcess_Handle handle, IArg key);
ARGUMENTS
handle — handle of a previously-created GateProcess instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateProcess_Handle_upCast(GateProcess_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateProcess_Handle GateProcess_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateProcess_Object_count();
// The number of statically-created instance objects
GateProcess_Handle GateProcess_Object_get(GateProcess_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateProcess_Handle GateProcess_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateProcess_Handle GateProcess_Object_next(GateProcess_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateProcess_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateProcess_Handle_label(GateProcess_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateProcess_Handle_name(GateProcess_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/GateProcess.xdc
var GateProcess = xdc.useModule('xdc.runtime.knl.GateProcess');
local proxy modules
     GateProcess.Proxy// Proxy that needs to be bound to an OS specific delegate = IGateProcessSupport.Module null
         GateProcess.Proxy.delegate$ = IGateProcessSupport.Module null
         GateProcess.Proxy.abstractInstances$ = false
module-wide constants & types
    const GateProcess.GETREFCOUNT_FAILED// Status returned by getReferenceCount when there is an error = -1;
    const GateProcess.Q_BLOCKING// Blocking quality = 1;
    const GateProcess.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateProcess.A_invalidKey// Assert when an invalid key is passed to create = Assert.Desc {
        msg: "A_invalidKey: the key must be set to a non-default value"
    };
     GateProcess.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateProcess.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateProcess.Params// Instance config-params object;
        params.key// globally unique key for SysV-style semaphore = Int -1;
per-instance creation
    var inst = GateProcess.create// Create an instance-object(params);
proxy GateProcess.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
GateProcess.Proxy = IGateProcessSupport.Module null
// some delegate module inheriting the IGateProcessSupport interface
    GateProcess.Proxy.delegate$ = IGateProcessSupport.Module null
    // explicit access to the currently bound delegate module
    GateProcess.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
const GateProcess.GETREFCOUNT_FAILED
index URL

Status returned by getReferenceCount when there is an error

XDCscript usage meta-domain
const GateProcess.GETREFCOUNT_FAILED = -1;
C SYNOPSIS
GateProcess_GETREFCOUNT_FAILED
const GateProcess.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateProcess.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateProcess_Q_BLOCKING
const GateProcess.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateProcess.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateProcess_Q_PREEMPTING
config GateProcess.A_invalidKey // module-wide
index URL

Assert when an invalid key is passed to create

XDCscript usage meta-domain
GateProcess.A_invalidKey = Assert.Desc {
    msg: "A_invalidKey: the key must be set to a non-default value"
};
C SYNOPSIS
GateProcess_A_invalidKey
metaonly config GateProcess.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateProcess.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateProcess.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateProcess.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateProcess.Params;
// Instance config-params object
    params.key = Int -1;
    // globally unique key for SysV-style semaphore
config GateProcess.key // instance
index URL

globally unique key for SysV-style semaphore

XDCscript usage meta-domain
var params = new GateProcess.Params;
...
params.key = Int -1;
DETAILS
This is a required parameter.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateProcess.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateProcess.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new GateProcess object which is initialized to count. All gates created with the same key reference the same underlying synchronization object and work between processes. For compatibility with the IGateProvider interface the argument key is passes in the params struct rather than as a full argument, but it is required. Therefore calling this function with a NULL params struct is illegal.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.GateProcessSupportNull
index URL

Empty IGateProcessSupport implementation

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/knl/GateProcessSupportNull.xdc
#include <xdc/runtime/knl/GateProcessSupportNull.h>
Functions
Void
GateProcessSupportNull_construct// Initialize a new instance object inside the provided structure(GateProcessSupportNull_Struct *structP, const GateProcessSupportNull_Params *params);
GateProcessSupportNull_Handle
GateProcessSupportNull_create// Allocate and initialize a new instance object and return its handle(const GateProcessSupportNull_Params *params, Error_Block *eb);
Void
GateProcessSupportNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateProcessSupportNull_Handle *handleP);
Void
GateProcessSupportNull_destruct// Finalize the instance object inside the provided structure(GateProcessSupportNull_Struct *structP);
Void
GateProcessSupportNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateProcessSupportNull_Params *params);
Functions common to all IGateProvider modules
IArg
GateProcessSupportNull_enter// Enter this gate(GateProcessSupportNull_Handle handle);
Void
GateProcessSupportNull_leave// Leave this gate(GateProcessSupportNull_Handle handle, IArg key);
Bool
GateProcessSupportNull_query// Runtime test for a particular gate quality(Int qual);
Functions common to all IGateProcessSupport modules
Int
GateProcessSupportNull_getReferenceCount// Get the number of processes with references to this Gate(GateProcessSupportNull_Handle handle, Error_Block *err);
Functions common to all target instances
GateProcessSupportNull_handle// Convert this instance structure pointer into an instance handle, GateProcessSupportNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateProcessSupportNull_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, GateProcessSupportNull_Handle_downCast3// conditionally move 3 levels down the inheritance hierarchy; NULL upon failure, GateProcessSupportNull_Handle_label// The label associated with this instance object, GateProcessSupportNull_Handle_name// The name of this instance object, GateProcessSupportNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateProcessSupportNull_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, GateProcessSupportNull_Handle_upCast3// unconditionally move 3 levels up the inheritance hierarchy, GateProcessSupportNull_Object_count// The number of statically-created instance objects, GateProcessSupportNull_Object_first// The handle of the first dynamically-created instance object, or NULL, GateProcessSupportNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateProcessSupportNull_Object_heap// The heap used to allocate dynamically-created instance objects, GateProcessSupportNull_Object_next// The handle of the next dynamically-created instance object, or NULL, GateProcessSupportNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
GateProcessSupportNull_Module_getMask// Returns the diagnostics mask for this module, GateProcessSupportNull_Module_hasMask// Test whether this module has a diagnostics mask, GateProcessSupportNull_Module_heap// The heap from which this module allocates memory, GateProcessSupportNull_Module_id// Get this module's unique id, GateProcessSupportNull_Module_setMask// Set the diagnostics mask for this module, GateProcessSupportNull_Module_startupDone// Test if this module has completed startup
Defines
#define
GateProcessSupportNull_GETREFCOUNT_FAILED// Status returned by getReferenceCount when there is an error (Int)-1
#define
GateProcessSupportNull_Q_BLOCKING// Blocking quality (Int)1
#define
GateProcessSupportNull_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateProcessSupportNull_Object *
GateProcessSupportNull_Handle// Client reference to an instance object;
typedef struct
GateProcessSupportNull_Object// Opaque internal representation of an instance object GateProcessSupportNull_Object;
typedef struct
GateProcessSupportNull_Params// Instance config-params structure ...
typedef struct
GateProcessSupportNull_Struct// Opaque client structure large enough to hold an instance object GateProcessSupportNull_Struct;
const GateProcessSupportNull_GETREFCOUNT_FAILED
index URL

Status returned by getReferenceCount when there is an error

C synopsis target-domain
#define GateProcessSupportNull_GETREFCOUNT_FAILED (Int)-1
const GateProcessSupportNull_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateProcessSupportNull_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateProcessSupportNull_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateProcessSupportNull_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateProcessSupportNull_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateProcessSupportNull_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateProcessSupportNull_Module_id();
// Get this module's unique id
Bool GateProcessSupportNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateProcessSupportNull_Module_heap();
// The heap from which this module allocates memory
Bool GateProcessSupportNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateProcessSupportNull_Module_getMask();
// Returns the diagnostics mask for this module
Void GateProcessSupportNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateProcessSupportNull_Object GateProcessSupportNull_Object;
// Opaque internal representation of an instance object
typedef GateProcessSupportNull_Object *GateProcessSupportNull_Handle;
// Client reference to an instance object
typedef struct GateProcessSupportNull_Struct GateProcessSupportNull_Struct;
// Opaque client structure large enough to hold an instance object
GateProcessSupportNull_Handle GateProcessSupportNull_handle(GateProcessSupportNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateProcessSupportNull_Struct *GateProcessSupportNull_struct(GateProcessSupportNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateProcessSupportNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    Int key;
    // globally unique key for SysV-style semaphore
} GateProcessSupportNull_Params;
Void GateProcessSupportNull_Params_init(GateProcessSupportNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config GateProcessSupportNull_key // instance
index URL

globally unique key for SysV-style semaphore

C synopsis target-domain
struct GateProcessSupportNull_Params {
     ...
    Int key;
Instance Creation
index URL

C synopsis target-domain
GateProcessSupportNull_Handle GateProcessSupportNull_create(const GateProcessSupportNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateProcessSupportNull_construct(GateProcessSupportNull_Struct *structP, const GateProcessSupportNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new GateProcess object which is initialized to count. All gates created with the same key reference the same underlying synchronization object and work between processes. The underlying synchronization object should be automatically deleted when all references to it have been deleted, and the reference count should An implementation for a platform on which this is technically impossible (e.g. an operating system that does not support multiple processes) may provide a 'toy' implemenation with behavior matching that of IGateProcessSupport.
Instance Deletion
index URL

C synopsis target-domain
Void GateProcessSupportNull_delete(GateProcessSupportNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateProcessSupportNull_destruct(GateProcessSupportNull_Struct *structP);
// Finalize the instance object inside the provided structure
GateProcessSupportNull_enter() // instance
index URL

Enter this gate

C synopsis target-domain
IArg GateProcessSupportNull_enter(GateProcessSupportNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateProcessSupportNull instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
GateProcessSupportNull_getReferenceCount() // instance
index URL

Get the number of processes with references to this Gate

C synopsis target-domain
Int GateProcessSupportNull_getReferenceCount(GateProcessSupportNull_Handle handle, Error_Block *err);
ARGUMENTS
handle — handle of a previously-created GateProcessSupportNull instance object
err — Pointer to Error.Block
RETURNS
Returns the number of processes that possess a reference to this gate, or GETREFCOUNT_FAILED if an error occured. A 'toy' implementation should always return 0.
GateProcessSupportNull_leave() // instance
index URL

Leave this gate

C synopsis target-domain
Void GateProcessSupportNull_leave(GateProcessSupportNull_Handle handle, IArg key);
ARGUMENTS
handle — handle of a previously-created GateProcessSupportNull instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
Instance Convertors
index URL

C synopsis target-domain
IGateProcessSupport_Handle GateProcessSupportNull_Handle_upCast(GateProcessSupportNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateProcessSupportNull_Handle GateProcessSupportNull_Handle_downCast(IGateProcessSupport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
IGateThreadSupport_Handle GateProcessSupportNull_Handle_upCast2(GateProcessSupportNull_Handle handle);
// unconditionally move 2 levels up the inheritance hierarchy
GateProcessSupportNull_Handle GateProcessSupportNull_Handle_downCast2(IGateThreadSupport_Handle handle);
// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure
IGateProvider_Handle GateProcessSupportNull_Handle_upCast3(GateProcessSupportNull_Handle handle);
// unconditionally move 3 levels up the inheritance hierarchy
GateProcessSupportNull_Handle GateProcessSupportNull_Handle_downCast3(IGateProvider_Handle handle);
// conditionally move 3 levels down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateProcessSupportNull_Object_count();
// The number of statically-created instance objects
GateProcessSupportNull_Handle GateProcessSupportNull_Object_get(GateProcessSupportNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateProcessSupportNull_Handle GateProcessSupportNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateProcessSupportNull_Handle GateProcessSupportNull_Object_next(GateProcessSupportNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateProcessSupportNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateProcessSupportNull_Handle_label(GateProcessSupportNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateProcessSupportNull_Handle_name(GateProcessSupportNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/GateProcessSupportNull.xdc
var GateProcessSupportNull = xdc.useModule('xdc.runtime.knl.GateProcessSupportNull');
module-wide constants & types
    const GateProcessSupportNull.GETREFCOUNT_FAILED// Status returned by getReferenceCount when there is an error = -1;
    const GateProcessSupportNull.Q_BLOCKING// Blocking quality = 1;
    const GateProcessSupportNull.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateProcessSupportNull.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateProcessSupportNull.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateProcessSupportNull.Params// Instance config-params object;
        params.key// globally unique key for SysV-style semaphore = Int -1;
per-instance creation
    var inst = GateProcessSupportNull.create// Create an instance-object(params);
const GateProcessSupportNull.GETREFCOUNT_FAILED
index URL

Status returned by getReferenceCount when there is an error

XDCscript usage meta-domain
const GateProcessSupportNull.GETREFCOUNT_FAILED = -1;
C SYNOPSIS
GateProcessSupportNull_GETREFCOUNT_FAILED
const GateProcessSupportNull.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateProcessSupportNull.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateProcessSupportNull_Q_BLOCKING
const GateProcessSupportNull.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateProcessSupportNull.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateProcessSupportNull_Q_PREEMPTING
metaonly config GateProcessSupportNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateProcessSupportNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateProcessSupportNull.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateProcessSupportNull.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateProcessSupportNull.Params;
// Instance config-params object
    params.key = Int -1;
    // globally unique key for SysV-style semaphore
config GateProcessSupportNull.key // instance
index URL

globally unique key for SysV-style semaphore

XDCscript usage meta-domain
var params = new GateProcessSupportNull.Params;
...
params.key = Int -1;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateProcessSupportNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateProcessSupportNull.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new GateProcess object which is initialized to count. All gates created with the same key reference the same underlying synchronization object and work between processes. The underlying synchronization object should be automatically deleted when all references to it have been deleted, and the reference count should An implementation for a platform on which this is technically impossible (e.g. an operating system that does not support multiple processes) may provide a 'toy' implemenation with behavior matching that of IGateProcessSupport.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.GateThread
index URL

Provides protection of critical sections across threads

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module provides services through its proxy IGateThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/GateThread.xdc
#include <xdc/runtime/knl/GateThread.h>
Functions
Void | GateThread_construct// Initialize a new instance object inside the provided structure(GateThread_Struct *structP, const GateThread_Params *params, Error_Block *eb);
GateThread_Handle | GateThread_create// Allocate and initialize a new instance object and return its handle(const GateThread_Params *params, Error_Block *eb);
Void | GateThread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateThread_Handle *handleP);
Void | GateThread_destruct// Finalize the instance object inside the provided structure(GateThread_Struct *structP);
Void | GateThread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateThread_Params *params);
Functions common to all IGateProvider modules
IArg | GateThread_enter// Enter this gate(GateThread_Handle handle);
Void | GateThread_leave// Leave this gate(GateThread_Handle handle, IArg key);
Bool | GateThread_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
 | GateThread_handle// Convert this instance structure pointer into an instance handle, GateThread_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateThread_Handle_label// The label associated with this instance object, GateThread_Handle_name// The name of this instance object, GateThread_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateThread_Object_count// The number of statically-created instance objects, GateThread_Object_first// The handle of the first dynamically-created instance object, or NULL, GateThread_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateThread_Object_heap// The heap used to allocate dynamically-created instance objects, GateThread_Object_next// The handle of the next dynamically-created instance object, or NULL, GateThread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | GateThread_Module_getMask// Returns the diagnostics mask for this module, GateThread_Module_hasMask// Test whether this module has a diagnostics mask, GateThread_Module_heap// The heap from which this module allocates memory, GateThread_Module_id// Get this module's unique id, GateThread_Module_setMask// Set the diagnostics mask for this module, GateThread_Module_startupDone// Test if this module has completed startup
Defines
#define | GateThread_Q_BLOCKING// Blocking quality (Int)1
#define | GateThread_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateThread_Object * | GateThread_Handle// Client reference to an instance object;
typedef struct | GateThread_Object// Opaque internal representation of an instance object GateThread_Object;
typedef struct | GateThread_Params// Instance config-params structure ...
typedef struct | GateThread_Struct// Opaque client structure large enough to hold an instance object GateThread_Struct;
DETAILS
This module provides services through its proxy IGateThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var GateThread = xdc.useModule('xdc.runtime.knl.GateThread');
  GateThread.Proxy =
      xdc.useModule('ti.sysbios.xdcruntime.GateThreadSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
const GateThread_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateThread_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateThread_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateThread_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateThread_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateThread_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateThread_Module_id();
// Get this module's unique id
Bool GateThread_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateThread_Module_heap();
// The heap from which this module allocates memory
Bool GateThread_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateThread_Module_getMask();
// Returns the diagnostics mask for this module
Void GateThread_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateThread_Object GateThread_Object;
// Opaque internal representation of an instance object
typedef GateThread_Object *GateThread_Handle;
// Client reference to an instance object
typedef struct GateThread_Struct GateThread_Struct;
// Opaque client structure large enough to hold an instance object
GateThread_Handle GateThread_handle(GateThread_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateThread_Struct *GateThread_struct(GateThread_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateThread_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateThread_Params;
Void GateThread_Params_init(GateThread_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateThread_Handle GateThread_create(const GateThread_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateThread_construct(GateThread_Struct *structP, const GateThread_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateThread_delete(GateThread_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateThread_destruct(GateThread_Struct *structP);
// Finalize the instance object inside the provided structure
GateThread_enter() // instance
index URL

Enter this gate

C synopsis target-domain
IArg GateThread_enter(GateThread_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateThread instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
GateThread_leave() // instance
index URL

Leave this gate

C synopsis target-domain
Void GateThread_leave(GateThread_Handle handle, IArg key);
ARGUMENTS
handle — handle of a previously-created GateThread instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
Instance Convertors
index URL

C synopsis target-domain
IGateProvider_Handle GateThread_Handle_upCast(GateThread_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateThread_Handle GateThread_Handle_downCast(IGateProvider_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateThread_Object_count();
// The number of statically-created instance objects
GateThread_Handle GateThread_Object_get(GateThread_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateThread_Handle GateThread_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateThread_Handle GateThread_Object_next(GateThread_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateThread_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateThread_Handle_label(GateThread_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateThread_Handle_name(GateThread_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/GateThread.xdc
var GateThread = xdc.useModule('xdc.runtime.knl.GateThread');
local proxy modules
     GateThread.Proxy// Proxy that needs to be bound to an OS specific delegate = IGateThreadSupport.Module null
         GateThread.Proxy.delegate$ = IGateThreadSupport.Module null
         GateThread.Proxy.abstractInstances$ = false
module-wide constants & types
    const GateThread.Q_BLOCKING// Blocking quality = 1;
    const GateThread.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateThread.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateThread.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateThread.Params// Instance config-params object;
per-instance creation
    var inst = GateThread.create// Create an instance-object(params);
proxy GateThread.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
GateThread.Proxy = IGateThreadSupport.Module null
// some delegate module inheriting the IGateThreadSupport interface
    GateThread.Proxy.delegate$ = IGateThreadSupport.Module null
    // explicit access to the currently bound delegate module
    GateThread.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
const GateThread.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateThread.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateThread_Q_BLOCKING
const GateThread.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateThread.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateThread_Q_PREEMPTING
metaonly config GateThread.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateThread.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateThread.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateThread.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateThread.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateThread.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateThread.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.GateThreadSupportNull
index URL

Empty IGateProcessSupport implementation

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/knl/GateThreadSupportNull.xdc
#include <xdc/runtime/knl/GateThreadSupportNull.h>
Functions
Void
GateThreadSupportNull_construct// Initialize a new instance object inside the provided structure(GateThreadSupportNull_Struct *structP, const GateThreadSupportNull_Params *params);
GateThreadSupportNull_Handle
GateThreadSupportNull_create// Allocate and initialize a new instance object and return its handle(const GateThreadSupportNull_Params *params, Error_Block *eb);
Void
GateThreadSupportNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(GateThreadSupportNull_Handle *handleP);
Void
GateThreadSupportNull_destruct// Finalize the instance object inside the provided structure(GateThreadSupportNull_Struct *structP);
Void
GateThreadSupportNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(GateThreadSupportNull_Params *params);
Functions common to all IGateProvider modules
IArg
GateThreadSupportNull_enter// Enter this gate(GateThreadSupportNull_Handle handle);
Void
GateThreadSupportNull_leave// Leave this gate(GateThreadSupportNull_Handle handle, IArg key);
Bool
GateThreadSupportNull_query// Runtime test for a particular gate quality(Int qual);
Functions common to all target instances
GateThreadSupportNull_handle// Convert this instance structure pointer into an instance handle, GateThreadSupportNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, GateThreadSupportNull_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, GateThreadSupportNull_Handle_label// The label associated with this instance object, GateThreadSupportNull_Handle_name// The name of this instance object, GateThreadSupportNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, GateThreadSupportNull_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, GateThreadSupportNull_Object_count// The number of statically-created instance objects, GateThreadSupportNull_Object_first// The handle of the first dynamically-created instance object, or NULL, GateThreadSupportNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), GateThreadSupportNull_Object_heap// The heap used to allocate dynamically-created instance objects, GateThreadSupportNull_Object_next// The handle of the next dynamically-created instance object, or NULL, GateThreadSupportNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
GateThreadSupportNull_Module_getMask// Returns the diagnostics mask for this module, GateThreadSupportNull_Module_hasMask// Test whether this module has a diagnostics mask, GateThreadSupportNull_Module_heap// The heap from which this module allocates memory, GateThreadSupportNull_Module_id// Get this module's unique id, GateThreadSupportNull_Module_setMask// Set the diagnostics mask for this module, GateThreadSupportNull_Module_startupDone// Test if this module has completed startup
Defines
#define
GateThreadSupportNull_Q_BLOCKING// Blocking quality (Int)1
#define
GateThreadSupportNull_Q_PREEMPTING// Preempting quality (Int)2
Typedefs
typedef GateThreadSupportNull_Object *
GateThreadSupportNull_Handle// Client reference to an instance object;
typedef struct
GateThreadSupportNull_Object// Opaque internal representation of an instance object GateThreadSupportNull_Object;
typedef struct
GateThreadSupportNull_Params// Instance config-params structure ...
typedef struct
GateThreadSupportNull_Struct// Opaque client structure large enough to hold an instance object GateThreadSupportNull_Struct;
const GateThreadSupportNull_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define GateThreadSupportNull_Q_BLOCKING (Int)1
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const GateThreadSupportNull_Q_PREEMPTING
index URL

Preempting quality

C synopsis target-domain
#define GateThreadSupportNull_Q_PREEMPTING (Int)2
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
GateThreadSupportNull_query() // module-wide
index URL

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateThreadSupportNull_query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId GateThreadSupportNull_Module_id();
// Get this module's unique id
Bool GateThreadSupportNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle GateThreadSupportNull_Module_heap();
// The heap from which this module allocates memory
Bool GateThreadSupportNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 GateThreadSupportNull_Module_getMask();
// Returns the diagnostics mask for this module
Void GateThreadSupportNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct GateThreadSupportNull_Object GateThreadSupportNull_Object;
// Opaque internal representation of an instance object
typedef GateThreadSupportNull_Object *GateThreadSupportNull_Handle;
// Client reference to an instance object
typedef struct GateThreadSupportNull_Struct GateThreadSupportNull_Struct;
// Opaque client structure large enough to hold an instance object
GateThreadSupportNull_Handle GateThreadSupportNull_handle(GateThreadSupportNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
GateThreadSupportNull_Struct *GateThreadSupportNull_struct(GateThreadSupportNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct GateThreadSupportNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} GateThreadSupportNull_Params;
Void GateThreadSupportNull_Params_init(GateThreadSupportNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
GateThreadSupportNull_Handle GateThreadSupportNull_create(const GateThreadSupportNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void GateThreadSupportNull_construct(GateThreadSupportNull_Struct *structP, const GateThreadSupportNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void GateThreadSupportNull_delete(GateThreadSupportNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void GateThreadSupportNull_destruct(GateThreadSupportNull_Struct *structP);
// Finalize the instance object inside the provided structure
GateThreadSupportNull_enter() // instance
index URL

Enter this gate

C synopsis target-domain
IArg GateThreadSupportNull_enter(GateThreadSupportNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created GateThreadSupportNull instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
GateThreadSupportNull_leave() // instance
index URL

Leave this gate

C synopsis target-domain
Void GateThreadSupportNull_leave(GateThreadSupportNull_Handle handle, IArg key);
ARGUMENTS
handle — handle of a previously-created GateThreadSupportNull instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
Instance Convertors
index URL

C synopsis target-domain
IGateThreadSupport_Handle GateThreadSupportNull_Handle_upCast(GateThreadSupportNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
GateThreadSupportNull_Handle GateThreadSupportNull_Handle_downCast(IGateThreadSupport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
IGateProvider_Handle GateThreadSupportNull_Handle_upCast2(GateThreadSupportNull_Handle handle);
// unconditionally move 2 levels up the inheritance hierarchy
GateThreadSupportNull_Handle GateThreadSupportNull_Handle_downCast2(IGateProvider_Handle handle);
// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int GateThreadSupportNull_Object_count();
// The number of statically-created instance objects
GateThreadSupportNull_Handle GateThreadSupportNull_Object_get(GateThreadSupportNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
GateThreadSupportNull_Handle GateThreadSupportNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
GateThreadSupportNull_Handle GateThreadSupportNull_Object_next(GateThreadSupportNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle GateThreadSupportNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *GateThreadSupportNull_Handle_label(GateThreadSupportNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String GateThreadSupportNull_Handle_name(GateThreadSupportNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/GateThreadSupportNull.xdc
var GateThreadSupportNull = xdc.useModule('xdc.runtime.knl.GateThreadSupportNull');
module-wide constants & types
    const GateThreadSupportNull.Q_BLOCKING// Blocking quality = 1;
    const GateThreadSupportNull.Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
     GateThreadSupportNull.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
     GateThreadSupportNull.queryMeta// Configuration time test for a particular gate quality(Int qual) returns Bool
per-instance config parameters
    var params = new GateThreadSupportNull.Params// Instance config-params object;
per-instance creation
    var inst = GateThreadSupportNull.create// Create an instance-object(params);
const GateThreadSupportNull.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const GateThreadSupportNull.Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
GateThreadSupportNull_Q_BLOCKING
const GateThreadSupportNull.Q_PREEMPTING
index URL

Preempting quality

XDCscript usage meta-domain
const GateThreadSupportNull.Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
C SYNOPSIS
GateThreadSupportNull_Q_PREEMPTING
metaonly config GateThreadSupportNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
GateThreadSupportNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
metaonly GateThreadSupportNull.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateThreadSupportNull.queryMeta(Int qual) returns Bool
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new GateThreadSupportNull.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new GateThreadSupportNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = GateThreadSupportNull.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:38 GMT


interface xdc.runtime.knl.ICacheSupport
index URL

Interface for OS specific back-end

The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.Cache module.
XDCspec summary sourced in xdc/runtime/knl/ICacheSupport.xdc
interface ICacheSupport { ...
// inherits xdc.runtime.IModule
XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
package xdc.runtime.knl;
interface ICacheSupport {
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bool inv// Invalidates range of memory(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    Bool wait// Wait for a previous cache operation to complete(Error.Block *eb);
    Bool wb// Writes a range of memory from all cache(s)(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    Bool wbInv// Writes back and invalidates range fo memory(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
}
metaonly config ICacheSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
ICacheSupport.inv() // module-wide
index URL

Invalidates range of memory

XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
Bool inv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Invalidate the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines in range are invalidated for all the 'type' caches.
RETURNS
true for success; false for error.
ICacheSupport.wait() // module-wide
index URL

Wait for a previous cache operation to complete

XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
Bool wait(Error.Block *eb);
DETAILS
Wait for the cache wb/wbInv/inv operation to complete. A cache operation is not truly complete until it has worked its way through all buffering and all memory writes have landed in the source memory.
RETURNS
true for success; false for error.
ICacheSupport.wb() // module-wide
index URL

Writes a range of memory from all cache(s)

XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
Bool wb(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are left valid in the 'type' caches and the data within the range will be written to the source memory.
RETURNS
true for success; false for error.
ICacheSupport.wbInv() // module-wide
index URL

Writes back and invalidates range fo memory

XDCspec declarations sourced in xdc/runtime/knl/ICacheSupport.xdc
Bool wbInv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
ARGUMENTS
blockPtr — start address of range to be invalidated
byteCnt — number of bytes to be invalidated
wait — wait until the operation is completed
eb — error block
DETAILS
Writes and invalidates the range of memory within the specified starting address and byte count. The range of addresses operated on gets quantized to whole cache lines in each cache. All lines within the range are written to the source memory and then invalidated for all 'type' caches.
RETURNS
true for success; false for error.
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.IGateProcessSupport
index URL

Interface for OS specific back-end

  • C synopsis
  • Individual elements
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.GateProcess module. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/IGateProcessSupport.xdc
interface IGateProcessSupport { ...
// inherits xdc.runtime.knl.IGateThreadSupport
    // inherits xdc.runtime.IGateProvider
        // inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
package xdc.runtime.knl;
interface IGateProcessSupport inherits IGateThreadSupport {
module-wide constants & types
    const Int GETREFCOUNT_FAILED// Status returned by getReferenceCount when there is an error = -1;
    const Int Q_BLOCKING// Blocking quality = 1;
    const Int Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bool query// Runtime test for a particular gate quality(Int qual);
    metaonly Bool queryMeta// Configuration time test for a particular gate quality(Int qual);
instance:
per-instance config parameters
    config Int key// globally unique key for SysV-style semaphore = -1;
per-instance creation
     create// Create an instance-object();
per-instance functions
    IArg enter// Enter this gate();
    Int getReferenceCount// Get the number of processes with references to this Gate(Error.Block *err);
    Void leave// Leave this gate(IArg key);
}
DETAILS
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.GateProcess module.
The implementation of IGateThreadSupport should try to implement a gate that supports priority inversion.
const IGateProcessSupport.GETREFCOUNT_FAILED
index URL

Status returned by getReferenceCount when there is an error

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
const Int GETREFCOUNT_FAILED = -1;
const IGateProcessSupport.Q_BLOCKING
index URL

Blocking quality

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
const Int Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const IGateProcessSupport.Q_PREEMPTING
index URL

Preempting quality

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
const Int Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
metaonly config IGateProcessSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
IGateProcessSupport.query() // module-wide
index URL

Runtime test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
Bool query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
metaonly IGateProcessSupport.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
metaonly Bool queryMeta(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
config IGateProcessSupport.key // instance
index URL

globally unique key for SysV-style semaphore

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
config Int key = -1;
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
create();
// Create an instance-object
DETAILS
This function creates a new GateProcess object which is initialized to count. All gates created with the same key reference the same underlying synchronization object and work between processes. The underlying synchronization object should be automatically deleted when all references to it have been deleted, and the reference count should An implementation for a platform on which this is technically impossible (e.g. an operating system that does not support multiple processes) may provide a 'toy' implemenation with behavior matching that of IGateProcessSupport.
IGateProcessSupport.enter() // instance
index URL

Enter this gate

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
IArg enter();
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
IGateProcessSupport.getReferenceCount() // instance
index URL

Get the number of processes with references to this Gate

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
Int getReferenceCount(Error.Block *err);
ARGUMENTS
err — Pointer to Error.Block
RETURNS
Returns the number of processes that possess a reference to this gate, or GETREFCOUNT_FAILED if an error occured. A 'toy' implementation should always return 0.
IGateProcessSupport.leave() // instance
index URL

Leave this gate

XDCspec declarations sourced in xdc/runtime/knl/IGateProcessSupport.xdc
Void leave(IArg key);
ARGUMENTS
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.IGateThreadSupport
index URL

Interface for OS specific back-end

  • C synopsis
  • Individual elements
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.GateThread module. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/IGateThreadSupport.xdc
interface IGateThreadSupport { ...
// inherits xdc.runtime.IGateProvider
    // inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
package xdc.runtime.knl;
interface IGateThreadSupport inherits IGateProvider {
module-wide constants & types
    const Int Q_BLOCKING// Blocking quality = 1;
    const Int Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Bool query// Runtime test for a particular gate quality(Int qual);
    metaonly Bool queryMeta// Configuration time test for a particular gate quality(Int qual);
instance:
per-instance creation
     create// Create an instance-object();
per-instance functions
    IArg enter// Enter this gate();
    Void leave// Leave this gate(IArg key);
}
DETAILS
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.GateThread module.
The implementation of IGateThreadSupport should try to implement a gate that supports priority inversion.
See xdc.runtime.knl for more details.
const IGateThreadSupport.Q_BLOCKING
index URL

Blocking quality

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
const Int Q_BLOCKING = 1;
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
const IGateThreadSupport.Q_PREEMPTING
index URL

Preempting quality

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
const Int Q_PREEMPTING = 2;
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
metaonly config IGateThreadSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
IGateThreadSupport.query() // module-wide
index URL

Runtime test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
Bool query(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
metaonly IGateThreadSupport.queryMeta() // module-wide
index URL

Configuration time test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
metaonly Bool queryMeta(Int qual);
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
create();
// Create an instance-object
IGateThreadSupport.enter() // instance
index URL

Enter this gate

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
IArg enter();
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
IGateThreadSupport.leave() // instance
index URL

Leave this gate

XDCspec declarations sourced in xdc/runtime/knl/IGateThreadSupport.xdc
Void leave(IArg key);
ARGUMENTS
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.ISemaphore
index URL

Interface implemented by all front-end semaphore providers

  • C synopsis
  • Individual elements
SemThread and SemProcess. [EXPERIMENTAL] Semaphores can be used for synchronization and mutual exclusion. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/ISemaphore.xdc
interface ISemaphore { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
package xdc.runtime.knl;
interface ISemaphore {
module-wide constants & types
    const UInt FOREVER// Used as the timeout value to specify wait forever = ~(0);
    enum Mode// Types of semaphores {
         Mode_COUNTING// Counting semaphore,
         Mode_BINARY// Binary Semaphore
    };
    enum PendStatus// Error codes returned by Semaphore_pend {
         PendStatus_ERROR,
         PendStatus_TIMEOUT,
         PendStatus_SUCCESS
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
instance:
per-instance config parameters
    config ISemaphore.Mode mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode_COUNTING;
per-instance functions
    Int pend// Wait for the semaphore to become available(UInt timeout, Error.Block *eb);
    Bool post// Increment the semaphore count(Error.Block *eb);
}
DETAILS
SemThread and SemProcess. [EXPERIMENTAL] Semaphores can be used for synchronization and mutual exclusion.
pend() is used to wait for a semaphore. The timeout parameter allows the caller to wait until a timeout, wait indefinitely, or not wait at all. The return value indicates whether or not the wait was successful.
post() is used to signal a semaphore. If no thread is waiting on the semaphore, then post() increments the semaphore count (for binary semaphores, the count is always 0 or 1).
const ISemaphore.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
const UInt FOREVER = ~(0);
enum ISemaphore.Mode
index URL

Types of semaphores

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
enum Mode {
    Mode_COUNTING,
    // Counting semaphore
    Mode_BINARY
    // Binary Semaphore
};
enum ISemaphore.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
enum PendStatus {
    PendStatus_ERROR,
    PendStatus_TIMEOUT,
    PendStatus_SUCCESS
};
metaonly config ISemaphore.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
config ISemaphore.mode // instance
index URL

Semaphore mode. Default is COUNTING

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
config ISemaphore.Mode mode = ISemaphore.Mode_COUNTING;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
ISemaphore.pend() // instance
index URL

Wait for the semaphore to become available

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
Int pend(UInt timeout, Error.Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — error block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
refer to description above
ISemaphore.post() // instance
index URL

Increment the semaphore count

XDCspec declarations sourced in xdc/runtime/knl/ISemaphore.xdc
Bool post(Error.Block *eb);
ARGUMENTS
eb — error block
RETURNS
true for success, false for error in error block
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.ISemProcessSupport
index URL

Interface for OS specific back-end

  • C synopsis
  • Individual elements
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules however require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.SemProcess module. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/ISemProcessSupport.xdc
interface ISemProcessSupport { ...
// inherits xdc.runtime.knl.ISemaphore
    // inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
package xdc.runtime.knl;
interface ISemProcessSupport inherits ISemaphore {
module-wide constants & types
    const UInt FOREVER// Used as the timeout value to specify wait forever = ~(0);
    enum Mode// Types of semaphores {
         Mode_COUNTING// Counting semaphore,
         Mode_BINARY// Binary Semaphore
    };
    enum PendStatus// Error codes returned by Semaphore_pend {
         PendStatus_ERROR,
         PendStatus_TIMEOUT,
         PendStatus_SUCCESS
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
instance:
per-instance config parameters
    config ISemaphore.Mode mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode_COUNTING;
per-instance creation
     create// Create an instance-object(Int count, Int key);
per-instance functions
    Int pend// Wait for the semaphore to become available(UInt timeout, Error.Block *eb);
    Bool post// Increment the semaphore count(Error.Block *eb);
}
DETAILS
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules however require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.SemProcess module.
create() takes a 32-bit integer key parameter to be used for identifying the semaphore to create across processes. For example, for Linux System V semaphores, the key is necessary so that different processes can access the same semaphore.
const ISemProcessSupport.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
const UInt FOREVER = ~(0);
enum ISemProcessSupport.Mode
index URL

Types of semaphores

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
enum Mode {
    Mode_COUNTING,
    // Counting semaphore
    Mode_BINARY
    // Binary Semaphore
};
enum ISemProcessSupport.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
enum PendStatus {
    PendStatus_ERROR,
    PendStatus_TIMEOUT,
    PendStatus_SUCCESS
};
metaonly config ISemProcessSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
config ISemProcessSupport.mode // instance
index URL

Semaphore mode. Default is COUNTING

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
config ISemaphore.Mode mode = ISemaphore.Mode_COUNTING;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
create(Int count, Int key);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
key — globally unique key
DETAILS
This function creates a new SemProcess object which is initialized to count. All semaphores created with the same key reference the same underlying synchronization object and work between processes. The underlying synchronization object should be automatically deleted when all references to it have been deleted, and the reference count should be maintained consistently across process forks or similar operations. An implementation for a platform on which this is technically impossible (e.g. an operating system that does not support multiple processes) may provide a 'toy' implementation with behavior matching that of ISemProcessSupport.
ISemProcessSupport.pend() // instance
index URL

Wait for the semaphore to become available

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
Int pend(UInt timeout, Error.Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — error block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
refer to description above
ISemProcessSupport.post() // instance
index URL

Increment the semaphore count

XDCspec declarations sourced in xdc/runtime/knl/ISemProcessSupport.xdc
Bool post(Error.Block *eb);
ARGUMENTS
eb — error block
RETURNS
true for success, false for error in error block
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.ISemThreadSupport
index URL

Interface for OS specific back-end

  • C synopsis
  • Individual elements
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.SemThread module. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/ISemThreadSupport.xdc
interface ISemThreadSupport { ...
// inherits xdc.runtime.knl.ISemaphore
    // inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
package xdc.runtime.knl;
interface ISemThreadSupport inherits ISemaphore {
module-wide constants & types
    const UInt FOREVER// Used as the timeout value to specify wait forever = ~(0);
    enum Mode// Types of semaphores {
         Mode_COUNTING// Counting semaphore,
         Mode_BINARY// Binary Semaphore
    };
    enum PendStatus// Error codes returned by Semaphore_pend {
         PendStatus_ERROR,
         PendStatus_TIMEOUT,
         PendStatus_SUCCESS
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
instance:
per-instance config parameters
    config ISemaphore.Mode mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode_COUNTING;
per-instance creation
     create// Create an instance-object(Int count);
per-instance functions
    Int pend// Wait for the semaphore to become available(UInt timeout, Error.Block *eb);
    Bool post// Increment the semaphore count(Error.Block *eb);
}
DETAILS
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.SemThread module.
This interface adds the create() function.
const ISemThreadSupport.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
const UInt FOREVER = ~(0);
enum ISemThreadSupport.Mode
index URL

Types of semaphores

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
enum Mode {
    Mode_COUNTING,
    // Counting semaphore
    Mode_BINARY
    // Binary Semaphore
};
enum ISemThreadSupport.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
enum PendStatus {
    PendStatus_ERROR,
    PendStatus_TIMEOUT,
    PendStatus_SUCCESS
};
metaonly config ISemThreadSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
config ISemThreadSupport.mode // instance
index URL

Semaphore mode. Default is COUNTING

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
config ISemaphore.Mode mode = ISemaphore.Mode_COUNTING;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
create(Int count);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
DETAILS
This function creates a new Semaphore object which is initialized to count.
ISemThreadSupport.pend() // instance
index URL

Wait for the semaphore to become available

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
Int pend(UInt timeout, Error.Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — error block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
refer to description above
ISemThreadSupport.post() // instance
index URL

Increment the semaphore count

XDCspec declarations sourced in xdc/runtime/knl/ISemThreadSupport.xdc
Bool post(Error.Block *eb);
ARGUMENTS
eb — error block
RETURNS
true for success, false for error in error block
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.ISync
index URL

OS independent synchronization

  • C synopsis
  • Individual elements
This interface allows clients to select method of synchronization in an OS independent way. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/ISync.xdc
interface ISync { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
package xdc.runtime.knl;
interface ISync {
module-wide constants & types
    const UInt NO_WAIT// Used to specify no waiting = 0;
    const Int Q_BLOCKING// Blocking quality = 1;
    const UInt WAIT_FOREVER// Used to wait forever = ~(0);
    enum WaitStatus// Error codes returned by ISync_wait {
         WaitStatus_ERROR,
         WaitStatus_TIMEOUT,
         WaitStatus_SUCCESS
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
instance:
per-instance creation
     create// Create an instance-object();
per-instance functions
    Bool query// Query for a particular quality(Int qual);
    Void signal// Called at completion of an activity();
    Int wait// Called to wait/poll for completion of an activity(UInt timeout, Error.Block *eb);
}
DETAILS
This interface allows clients to select method of synchronization in an OS independent way.
Modules that require the user to pick a synchronization method, will request a Handle. Clients of such modules can pick a blocking ISync implementation or a non-blocking implementation.
This interface specifies two main functions signal and wait. These two functions are always used in pairs in modules that use ISync instances. The signal() function is used to signal completion of an activity. The wait() function will allow the module to block or poll for completion of the same activity.
ISync mandates that the sync mechanism be binary and not support counters. Although the wait() function seems meaningless in the case of non-blocking sync, it allows modules to be written generically and support all ISync implementations. For non-blocking ISync the wait() function will return WaitStatus_TIMEOUT to denote timeout.
const ISync.NO_WAIT
index URL

Used to specify no waiting

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
const UInt NO_WAIT = 0;
const ISync.Q_BLOCKING
index URL

Blocking quality

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
const Int Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const ISync.WAIT_FOREVER
index URL

Used to wait forever

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
const UInt WAIT_FOREVER = ~(0);
enum ISync.WaitStatus
index URL

Error codes returned by ISync_wait

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
enum WaitStatus {
    WaitStatus_ERROR,
    WaitStatus_TIMEOUT,
    WaitStatus_SUCCESS
};
metaonly config ISync.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
create();
// Create an instance-object
ISync.query() // instance
index URL

Query for a particular quality

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
Bool query(Int qual);
ARGUMENTS
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
ISync.signal() // instance
index URL

Called at completion of an activity

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
Void signal();
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
ISync.wait() // instance
index URL

Called to wait/poll for completion of an activity

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc
Int wait(UInt timeout, Error.Block *eb);
ARGUMENTS
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
generated on Fri, 17 Jun 2011 00:24:37 GMT


interface xdc.runtime.knl.IThreadSupport
index URL

Interface for OS specific back-end

  • C synopsis
  • Individual elements
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.Thread module. [ more ... ]
XDCspec summary sourced in xdc/runtime/knl/IThreadSupport.xdc
interface IThreadSupport { ...
// inherits xdc.runtime.IModule
instance: ...
XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
package xdc.runtime.knl;
interface IThreadSupport {
module-wide constants & types
    const Int GETPRI_FAILED// The error status for getPriority when an error is captured in the Error.Block = -2;
    const Int INVALID_OS_PRIORITY// Invalid OS priority value = 0;
    enum CompStatus// Status returned by compareOsPriorities when an error occurs {
         CompStatus_ERROR,
         CompStatus_LOWER,
         CompStatus_EQUAL,
         CompStatus_HIGHER
    };
    enum Priority// Thread priorities which are mapped to OS specific value by Proxy {
         Priority_INVALID,
         Priority_LOWEST,
         Priority_BELOW_NORMAL,
         Priority_NORMAL,
         Priority_ABOVE_NORMAL,
         Priority_HIGHEST
    };
    typedef Void (*RunFxn// typedef for function that gets called when the Thread runs)(IArg);
    struct Stat// Struct to hold thread statistics from stat {
        SizeT stackSize;
        SizeT stackUsed;
    };
module-wide config parameters
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Int compareOsPriorities// Compare two priority values and find out which one represents a higher priority(Int p1, Int p2, Error.Block *eb);
     IThreadSupport.Handle self// Acquire the currently executing thread's handle(Error.Block *eb);
    Bool sleep// Sleep for certain number of microseconds(UInt timeout, Error.Block *eb);
    Bool start// Start threads running(Error.Block *eb);
    Bool yield// Yield the currently scheduled thread(Error.Block *eb);
instance:
per-instance config parameters
    config IArg arg// Thread function argument. Default is NULL = null;
    config Int osPriority// OS specific thread priority = IThreadSupport.INVALID_OS_PRIORITY;
    config IThreadSupport.Priority priority// Thread priority = IThreadSupport.Priority_NORMAL;
    config SizeT stackSize// Thread stack size. If left at zero, OS default is used = 0;
    config Ptr tls// User-specified thread local storage data = null;
per-instance creation
     create// Create an instance-object(IThreadSupport.RunFxn fxn);
per-instance functions
    Ptr getOsHandle// Get the OS thread handle();
    Int getOsPriority// Obtain a thread's os specific priority(Error.Block *eb);
     IThreadSupport.Priority getPriority// Obtain a thread's priority(Error.Block *eb);
    Ptr getTls// Obtain a thread's local storage pointer();
    Bool join// Join on a Thread(Error.Block *eb);
    Bool setOsPriority// Set a thread's priority(Int newPri, Error.Block *eb);
    Bool setPriority// Set a thread's priority(IThreadSupport.Priority newPri, Error.Block *eb);
    Void setTls// Set a thread's local storage pointer(Ptr tls);
    Bool stat// Obtain a thread's stats(IThreadSupport.Stat *buf, Error.Block *eb);
}
DETAILS
The xdc.runtime.knl package contains modules that provide typical OS services. These xdc.runtime.knl modules require proxies to be bound to an OS specific delegate. This specifies the interface to be implemented by the OS specific delegate for xdc.runtime.knl.Thread module.
Refer to xdc.runtime.knl.Thread for more details on the APIs.
const IThreadSupport.GETPRI_FAILED
index URL

The error status for getPriority when an error is captured in the Error.Block

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
const Int GETPRI_FAILED = -2;
const IThreadSupport.INVALID_OS_PRIORITY
index URL

Invalid OS priority value

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
const Int INVALID_OS_PRIORITY = 0;
enum IThreadSupport.CompStatus
index URL

Status returned by compareOsPriorities when an error occurs

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
enum CompStatus {
    CompStatus_ERROR,
    CompStatus_LOWER,
    CompStatus_EQUAL,
    CompStatus_HIGHER
};
enum IThreadSupport.Priority
index URL

Thread priorities which are mapped to OS specific value by Proxy

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
enum Priority {
    Priority_INVALID,
    Priority_LOWEST,
    Priority_BELOW_NORMAL,
    Priority_NORMAL,
    Priority_ABOVE_NORMAL,
    Priority_HIGHEST
};
typedef IThreadSupport.RunFxn
index URL

typedef for function that gets called when the Thread runs

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
typedef Void (*RunFxn)(IArg);
struct IThreadSupport.Stat
index URL

Struct to hold thread statistics from stat

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
struct Stat {
    SizeT stackSize;
    SizeT stackUsed;
};
metaonly config IThreadSupport.common$ // module-wide
index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
metaonly config Types.Common$ common$;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
IThreadSupport.compareOsPriorities() // module-wide
index URL

Compare two priority values and find out which one represents a higher priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Int compareOsPriorities(Int p1, Int p2, Error.Block *eb);
ARGUMENTS
p1 — priority one
p2 — priority two
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.compareOsPriorities for more details.
  • CompStatus_ERROR if an error occured
  • CompStatus_LOWER if p1 is lower than p2
  • CompStatus_EQUAL if p1=p2
  • CompStatus_HIGHER if p1 is higher than p2 details.
RETURNS
Refer to description above
IThreadSupport.self() // module-wide
index URL

Acquire the currently executing thread's handle

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
IThreadSupport.Handle self(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.self for more details.
RETURNS
Handle in case of success; null for error;
IThreadSupport.sleep() // module-wide
index URL

Sleep for certain number of microseconds

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool sleep(UInt timeout, Error.Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.sleep for more details.
RETURNS
true for success; false for failure
IThreadSupport.start() // module-wide
index URL

Start threads running

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool start(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.start for more details.
RETURNS
true for success; false for failure
IThreadSupport.yield() // module-wide
index URL

Yield the currently scheduled thread

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool yield(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.yield for more details.
RETURNS
true for success; false for failure
config IThreadSupport.arg // instance
index URL

Thread function argument. Default is NULL

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
config IArg arg = null;
config IThreadSupport.osPriority // instance
index URL

OS specific thread priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
config Int osPriority = IThreadSupport.INVALID_OS_PRIORITY;
DETAILS
Used to specify an OS specific value for priority. If set this value takes precedence over priority.
config IThreadSupport.priority // instance
index URL

Thread priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
config IThreadSupport.Priority priority = IThreadSupport.Priority_NORMAL;
DETAILS
Thread defines several constants which allows applications to select a priority in an OS independent way. Priority_LOWEST, Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and Priority_HIGHEST. These values get mapped to OS specific priorities by the OS specific delegate.
config IThreadSupport.stackSize // instance
index URL

Thread stack size. If left at zero, OS default is used

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
config SizeT stackSize = 0;
config IThreadSupport.tls // instance
index URL

User-specified thread local storage data

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
config Ptr tls = null;
Instance Creation
index URL

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
create(IThreadSupport.RunFxn fxn);
// Create an instance-object
ARGUMENTS
fxn — function for new thread to begin execution
DETAILS
This function spawns a new thread calling the function fxn.
IThreadSupport.getOsHandle() // instance
index URL

Get the OS thread handle

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Ptr getOsHandle();
RETURNS
null in case of error
IThreadSupport.getOsPriority() // instance
index URL

Obtain a thread's os specific priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Int getOsPriority(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, the value returned is the base priority of the thread.
Refer to xdc.runtime.knl.Thread.getOsPriority for more details.
RETURNS
thread priority in case of success; GETPRI_FAILED in case of error;
IThreadSupport.getPriority() // instance
index URL

Obtain a thread's priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
IThreadSupport.Priority getPriority(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.getPriority for more details.
RETURNS
thread priority in case of success; Priority_INVALID in case of error;
IThreadSupport.getTls() // instance
index URL

Obtain a thread's local storage pointer

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Ptr getTls();
RETURNS
null in case of error
IThreadSupport.join() // instance
index URL

Join on a Thread

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool join(Error.Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.join for more details.
RETURNS
true for success; false for failure
IThreadSupport.setOsPriority() // instance
index URL

Set a thread's priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool setOsPriority(Int newPri, Error.Block *eb);
ARGUMENTS
newPri — new thread priority
eb — Pointer to Error.Block
DETAILS
This API sets the base priority of the thread on OSes that support dynamic priority boosting
Refer to xdc.runtime.knl.Thread.setOsPriority for more details.
RETURNS
true for success; false for failure
IThreadSupport.setPriority() // instance
index URL

Set a thread's priority

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool setPriority(IThreadSupport.Priority newPri, Error.Block *eb);
ARGUMENTS
newPri — new thread priority
eb — Pointer to Error.Block
DETAILS
Refer to xdc.runtime.knl.Thread.setPriority for more details.
RETURNS
true for success; false for failure
IThreadSupport.setTls() // instance
index URL

Set a thread's local storage pointer

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Void setTls(Ptr tls);
ARGUMENTS
tls — thread tls
IThreadSupport.stat() // instance
index URL

Obtain a thread's stats

XDCspec declarations sourced in xdc/runtime/knl/IThreadSupport.xdc
Bool stat(IThreadSupport.Stat *buf, Error.Block *eb);
ARGUMENTS
buf — Pointer to Stat
eb — Pointer to Error.Block
RETURNS
true for success; false for failure
generated on Fri, 17 Jun 2011 00:24:37 GMT


module xdc.runtime.knl.Semaphore
index URL

Provides semaphore services when an ISemaphore.Handle is available

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
An application can isolate itself from ISemaphore implementations by using this module. The application must first obtain an ISemaphore.Handle. It make get such a handle by directly calling SemThread.create or SemProcess.create. Then the application can use the generic APIs provided by this module.
C synopsis target-domain sourced in xdc/runtime/knl/Semaphore.xdc
#include <xdc/runtime/knl/Semaphore.h>
Functions
Int | Semaphore_pend// Wait for the semaphore to have a nonzero count, then decrement it(ISemaphore_Handle sem, UInt timeout, Error_Block *eb);
Bool | Semaphore_post// Increment the semaphore count(ISemaphore_Handle sem, Error_Block *eb);
Functions common to all target modules
 | Semaphore_Module_getMask// Returns the diagnostics mask for this module, Semaphore_Module_hasMask// Test whether this module has a diagnostics mask, Semaphore_Module_heap// The heap from which this module allocates memory, Semaphore_Module_id// Get this module's unique id, Semaphore_Module_setMask// Set the diagnostics mask for this module, Semaphore_Module_startupDone// Test if this module has completed startup
Defines
#define | Semaphore_FOREVER// Used as the timeout value to specify wait forever (UInt)ISemaphore.FOREVER
Typedefs
typedef enum | Semaphore_PendStatus// Error codes returned by Semaphore_pend ...
const Semaphore_FOREVER
index URL

Used as the timeout value to specify wait forever

C synopsis target-domain
#define Semaphore_FOREVER (UInt)ISemaphore.FOREVER
enum Semaphore_PendStatus
index URL

Error codes returned by Semaphore_pend

C synopsis target-domain
typedef enum Semaphore_PendStatus {
    Semaphore_PendStatus_ERROR,
    Semaphore_PendStatus_TIMEOUT,
    Semaphore_PendStatus_SUCCESS
} Semaphore_PendStatus;
Semaphore_pend() // module-wide
index URL

Wait for the semaphore to have a nonzero count, then decrement it

C synopsis target-domain
Int Semaphore_pend(ISemaphore_Handle sem, UInt timeout, Error_Block *eb);
ARGUMENTS
sem — ISemaphore.Handle to be used
timeout — timeout in microseconds
eb — Pointer to Error.Block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
status returned. (refer to above description)
Semaphore_post() // module-wide
index URL

Increment the semaphore count

C synopsis target-domain
Bool Semaphore_post(ISemaphore_Handle sem, Error_Block *eb);
ARGUMENTS
sem — ISemaphore.Handle to be used
eb — Pointer to Error.Block
RETURNS
true for success, false for error in Error block.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Semaphore_Module_id();
// Get this module's unique id
Bool Semaphore_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Semaphore_Module_heap();
// The heap from which this module allocates memory
Bool Semaphore_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Semaphore_Module_getMask();
// Returns the diagnostics mask for this module
Void Semaphore_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/knl/Semaphore.xdc
var Semaphore = xdc.useModule('xdc.runtime.knl.Semaphore');
local proxy modules
     Semaphore.Proxy// Proxy used for optimization = ISemaphore.Module null
         Semaphore.Proxy.delegate$ = ISemaphore.Module null
         Semaphore.Proxy.abstractInstances$ = false
module-wide constants & types
    const Semaphore.FOREVER// Used as the timeout value to specify wait forever = ISemaphore.FOREVER;
    values of type Semaphore.PendStatus// Error codes returned by Semaphore_pend
        const Semaphore.PendStatus_ERROR;
        const Semaphore.PendStatus_TIMEOUT;
        const Semaphore.PendStatus_SUCCESS;
module-wide config parameters
     Semaphore.common$// Common module configuration parameters = Types.Common$ undefined;
proxy Semaphore.Proxy
index URL

Proxy used for optimization

XDCscript usage meta-domain
Semaphore.Proxy = ISemaphore.Module null
// some delegate module inheriting the ISemaphore interface
    Semaphore.Proxy.delegate$ = ISemaphore.Module null
    // explicit access to the currently bound delegate module
    Semaphore.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
DETAILS
If ALL ISemaphore.Handles were created using the same module (e.g SemProcess) then setting this Proxy to SemProcess and setting Semaphore.Proxy.abstractInstances$ = false, Semaphore APIs can have better performance.
const Semaphore.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCscript usage meta-domain
const Semaphore.FOREVER = ISemaphore.FOREVER;
C SYNOPSIS
Semaphore_FOREVER
enum Semaphore.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCscript usage meta-domain
values of type Semaphore.PendStatus
    const Semaphore.PendStatus_ERROR;
    const Semaphore.PendStatus_TIMEOUT;
    const Semaphore.PendStatus_SUCCESS;
C SYNOPSIS
Semaphore_PendStatus
metaonly config Semaphore.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Semaphore.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.SemProcess
index URL

SemProcess Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages multi-process semaphores through its proxy ISemProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/SemProcess.xdc
#include <xdc/runtime/knl/SemProcess.h>
Functions
Void | SemProcess_construct// Initialize a new instance object inside the provided structure(SemProcess_Struct *structP, Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
SemProcess_Handle | SemProcess_create// Allocate and initialize a new instance object and return its handle(Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
Void | SemProcess_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SemProcess_Handle *handleP);
Void | SemProcess_destruct// Finalize the instance object inside the provided structure(SemProcess_Struct *structP);
Void | SemProcess_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SemProcess_Params *params);
Functions common to all ISemaphore modules
Int | SemProcess_pend// Wait for the semaphore to become available(SemProcess_Handle handle, UInt timeout, Error_Block *eb);
Bool | SemProcess_post// Increment the semaphore count(SemProcess_Handle handle, Error_Block *eb);
Functions common to all target instances
 | SemProcess_handle// Convert this instance structure pointer into an instance handle, SemProcess_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SemProcess_Handle_label// The label associated with this instance object, SemProcess_Handle_name// The name of this instance object, SemProcess_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SemProcess_Object_count// The number of statically-created instance objects, SemProcess_Object_first// The handle of the first dynamically-created instance object, or NULL, SemProcess_Object_get// The handle of the i-th statically-created instance object (array == NULL), SemProcess_Object_heap// The heap used to allocate dynamically-created instance objects, SemProcess_Object_next// The handle of the next dynamically-created instance object, or NULL, SemProcess_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SemProcess_Module_getMask// Returns the diagnostics mask for this module, SemProcess_Module_hasMask// Test whether this module has a diagnostics mask, SemProcess_Module_heap// The heap from which this module allocates memory, SemProcess_Module_id// Get this module's unique id, SemProcess_Module_setMask// Set the diagnostics mask for this module, SemProcess_Module_startupDone// Test if this module has completed startup
Defines
#define | SemProcess_FOREVER// Used as the timeout value to specify wait forever (UInt)~(0)
Typedefs
typedef SemProcess_Object * | SemProcess_Handle// Client reference to an instance object;
typedef enum | SemProcess_Mode// Types of semaphores ...
typedef struct | SemProcess_Object// Opaque internal representation of an instance object SemProcess_Object;
typedef struct | SemProcess_Params// Instance config-params structure ...
typedef enum | SemProcess_PendStatus// Error codes returned by Semaphore_pend ...
typedef struct | SemProcess_Struct// Opaque client structure large enough to hold an instance object SemProcess_Struct;
DETAILS
This module manages multi-process semaphores through its proxy ISemProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var SemProcess = xdc.useModule('xdc.runtime.knl.SemProcess');
  SemProcess.Proxy = xdc.useModule('ti.sysbios.xdcruntime.SemProcessSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
const SemProcess_FOREVER
index URL

Used as the timeout value to specify wait forever

C synopsis target-domain
#define SemProcess_FOREVER (UInt)~(0)
enum SemProcess_Mode
index URL

Types of semaphores

C synopsis target-domain
typedef enum SemProcess_Mode {
    SemProcess_Mode_COUNTING,
    // Counting semaphore
    SemProcess_Mode_BINARY
    // Binary Semaphore
} SemProcess_Mode;
enum SemProcess_PendStatus
index URL

Error codes returned by Semaphore_pend

C synopsis target-domain
typedef enum SemProcess_PendStatus {
    SemProcess_PendStatus_ERROR,
    SemProcess_PendStatus_TIMEOUT,
    SemProcess_PendStatus_SUCCESS
} SemProcess_PendStatus;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SemProcess_Module_id();
// Get this module's unique id
Bool SemProcess_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SemProcess_Module_heap();
// The heap from which this module allocates memory
Bool SemProcess_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SemProcess_Module_getMask();
// Returns the diagnostics mask for this module
Void SemProcess_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SemProcess_Object SemProcess_Object;
// Opaque internal representation of an instance object
typedef SemProcess_Object *SemProcess_Handle;
// Client reference to an instance object
typedef struct SemProcess_Struct SemProcess_Struct;
// Opaque client structure large enough to hold an instance object
SemProcess_Handle SemProcess_handle(SemProcess_Struct *structP);
// Convert this instance structure pointer into an instance handle
SemProcess_Struct *SemProcess_struct(SemProcess_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SemProcess_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     ISemaphore_Mode mode;
    // Semaphore mode. Default is COUNTING
} SemProcess_Params;
Void SemProcess_Params_init(SemProcess_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SemProcess_mode // instance
index URL

Semaphore mode. Default is COUNTING

C synopsis target-domain
struct SemProcess_Params {
     ...
     ISemaphore_Mode mode;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
Instance Creation
index URL

C synopsis target-domain
SemProcess_Handle SemProcess_create(Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SemProcess_construct(SemProcess_Struct *structP, Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
count — initial semaphore count
key — globally unique key for SysV-style semaphore
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new SemProcess object which is initialized to count. All semaphores created with the same key reference the same underlying synchronization object and work between processes.
Instance Deletion
index URL

C synopsis target-domain
Void SemProcess_delete(SemProcess_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SemProcess_destruct(SemProcess_Struct *structP);
// Finalize the instance object inside the provided structure
SemProcess_pend() // instance
index URL

Wait for the semaphore to become available

C synopsis target-domain
Int SemProcess_pend(SemProcess_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SemProcess instance object
timeout — timeout in microseconds
eb — error block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
refer to description above
SemProcess_post() // instance
index URL

Increment the semaphore count

C synopsis target-domain
Bool SemProcess_post(SemProcess_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SemProcess instance object
eb — error block
RETURNS
true for success, false for error in error block
Instance Convertors
index URL

C synopsis target-domain
ISemaphore_Handle SemProcess_Handle_upCast(SemProcess_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SemProcess_Handle SemProcess_Handle_downCast(ISemaphore_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SemProcess_Object_count();
// The number of statically-created instance objects
SemProcess_Handle SemProcess_Object_get(SemProcess_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SemProcess_Handle SemProcess_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SemProcess_Handle SemProcess_Object_next(SemProcess_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SemProcess_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SemProcess_Handle_label(SemProcess_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SemProcess_Handle_name(SemProcess_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/SemProcess.xdc
var SemProcess = xdc.useModule('xdc.runtime.knl.SemProcess');
local proxy modules
     SemProcess.Proxy// Proxy that needs to be bound to an OS specific delegate = ISemProcessSupport.Module null
         SemProcess.Proxy.delegate$ = ISemProcessSupport.Module null
         SemProcess.Proxy.abstractInstances$ = false
module-wide constants & types
    const SemProcess.FOREVER// Used as the timeout value to specify wait forever = ~(0);
    values of type SemProcess.Mode// Types of semaphores
        const SemProcess.Mode_COUNTING// Counting semaphore;
        const SemProcess.Mode_BINARY// Binary Semaphore;
    values of type SemProcess.PendStatus// Error codes returned by Semaphore_pend
        const SemProcess.PendStatus_ERROR;
        const SemProcess.PendStatus_TIMEOUT;
        const SemProcess.PendStatus_SUCCESS;
module-wide config parameters
     SemProcess.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SemProcess.Params// Instance config-params object;
        params.mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode ISemaphore.Mode_COUNTING;
per-instance creation
    var inst = SemProcess.create// Create an instance-object(Int count, UInt32 key, params);
proxy SemProcess.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
SemProcess.Proxy = ISemProcessSupport.Module null
// some delegate module inheriting the ISemProcessSupport interface
    SemProcess.Proxy.delegate$ = ISemProcessSupport.Module null
    // explicit access to the currently bound delegate module
    SemProcess.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
const SemProcess.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCscript usage meta-domain
const SemProcess.FOREVER = ~(0);
C SYNOPSIS
SemProcess_FOREVER
enum SemProcess.Mode
index URL

Types of semaphores

XDCscript usage meta-domain
values of type SemProcess.Mode
    const SemProcess.Mode_COUNTING;
    // Counting semaphore
    const SemProcess.Mode_BINARY;
    // Binary Semaphore
C SYNOPSIS
SemProcess_Mode
enum SemProcess.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCscript usage meta-domain
values of type SemProcess.PendStatus
    const SemProcess.PendStatus_ERROR;
    const SemProcess.PendStatus_TIMEOUT;
    const SemProcess.PendStatus_SUCCESS;
C SYNOPSIS
SemProcess_PendStatus
metaonly config SemProcess.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SemProcess.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SemProcess.Params;
// Instance config-params object
    params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
    // Semaphore mode. Default is COUNTING
config SemProcess.mode // instance
index URL

Semaphore mode. Default is COUNTING

XDCscript usage meta-domain
var params = new SemProcess.Params;
...
params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SemProcess.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SemProcess.create(Int count, UInt32 key, params);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
key — globally unique key for SysV-style semaphore
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new SemProcess object which is initialized to count. All semaphores created with the same key reference the same underlying synchronization object and work between processes.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.SemThread
index URL

SemThread Manager

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages semaphores through its proxy ISemThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/SemThread.xdc
#include <xdc/runtime/knl/SemThread.h>
Functions
Void | SemThread_construct// Initialize a new instance object inside the provided structure(SemThread_Struct *structP, Int count, const SemThread_Params *params, Error_Block *eb);
SemThread_Handle | SemThread_create// Allocate and initialize a new instance object and return its handle(Int count, const SemThread_Params *params, Error_Block *eb);
Void | SemThread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SemThread_Handle *handleP);
Void | SemThread_destruct// Finalize the instance object inside the provided structure(SemThread_Struct *structP);
Void | SemThread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SemThread_Params *params);
Functions common to all ISemaphore modules
Int | SemThread_pend// Wait for the semaphore to become available(SemThread_Handle handle, UInt timeout, Error_Block *eb);
Bool | SemThread_post// Increment the semaphore count(SemThread_Handle handle, Error_Block *eb);
Functions common to all target instances
 | SemThread_handle// Convert this instance structure pointer into an instance handle, SemThread_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SemThread_Handle_label// The label associated with this instance object, SemThread_Handle_name// The name of this instance object, SemThread_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SemThread_Object_count// The number of statically-created instance objects, SemThread_Object_first// The handle of the first dynamically-created instance object, or NULL, SemThread_Object_get// The handle of the i-th statically-created instance object (array == NULL), SemThread_Object_heap// The heap used to allocate dynamically-created instance objects, SemThread_Object_next// The handle of the next dynamically-created instance object, or NULL, SemThread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SemThread_Module_getMask// Returns the diagnostics mask for this module, SemThread_Module_hasMask// Test whether this module has a diagnostics mask, SemThread_Module_heap// The heap from which this module allocates memory, SemThread_Module_id// Get this module's unique id, SemThread_Module_setMask// Set the diagnostics mask for this module, SemThread_Module_startupDone// Test if this module has completed startup
Defines
#define | SemThread_FOREVER// Used as the timeout value to specify wait forever (UInt)~(0)
Typedefs
typedef SemThread_Object * | SemThread_Handle// Client reference to an instance object;
typedef enum | SemThread_Mode// Types of semaphores ...
typedef struct | SemThread_Object// Opaque internal representation of an instance object SemThread_Object;
typedef struct | SemThread_Params// Instance config-params structure ...
typedef enum | SemThread_PendStatus// Error codes returned by Semaphore_pend ...
typedef struct | SemThread_Struct// Opaque client structure large enough to hold an instance object SemThread_Struct;
DETAILS
This module manages semaphores through its proxy ISemThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var SemThread = xdc.useModule('xdc.runtime.knl.SemThread');
  SemThread.Proxy = xdc.useModule('ti.sysbios.xdcruntime.SemThreadSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
const SemThread_FOREVER
index URL

Used as the timeout value to specify wait forever

C synopsis target-domain
#define SemThread_FOREVER (UInt)~(0)
enum SemThread_Mode
index URL

Types of semaphores

C synopsis target-domain
typedef enum SemThread_Mode {
    SemThread_Mode_COUNTING,
    // Counting semaphore
    SemThread_Mode_BINARY
    // Binary Semaphore
} SemThread_Mode;
enum SemThread_PendStatus
index URL

Error codes returned by Semaphore_pend

C synopsis target-domain
typedef enum SemThread_PendStatus {
    SemThread_PendStatus_ERROR,
    SemThread_PendStatus_TIMEOUT,
    SemThread_PendStatus_SUCCESS
} SemThread_PendStatus;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SemThread_Module_id();
// Get this module's unique id
Bool SemThread_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SemThread_Module_heap();
// The heap from which this module allocates memory
Bool SemThread_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SemThread_Module_getMask();
// Returns the diagnostics mask for this module
Void SemThread_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SemThread_Object SemThread_Object;
// Opaque internal representation of an instance object
typedef SemThread_Object *SemThread_Handle;
// Client reference to an instance object
typedef struct SemThread_Struct SemThread_Struct;
// Opaque client structure large enough to hold an instance object
SemThread_Handle SemThread_handle(SemThread_Struct *structP);
// Convert this instance structure pointer into an instance handle
SemThread_Struct *SemThread_struct(SemThread_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SemThread_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
     ISemaphore_Mode mode;
    // Semaphore mode. Default is COUNTING
} SemThread_Params;
Void SemThread_Params_init(SemThread_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SemThread_mode // instance
index URL

Semaphore mode. Default is COUNTING

C synopsis target-domain
struct SemThread_Params {
     ...
     ISemaphore_Mode mode;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
Instance Creation
index URL

C synopsis target-domain
SemThread_Handle SemThread_create(Int count, const SemThread_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SemThread_construct(SemThread_Struct *structP, Int count, const SemThread_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
count — initial semaphore count
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new SemThread object which is initialized to count.
Instance Deletion
index URL

C synopsis target-domain
Void SemThread_delete(SemThread_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SemThread_destruct(SemThread_Struct *structP);
// Finalize the instance object inside the provided structure
SemThread_pend() // instance
index URL

Wait for the semaphore to become available

C synopsis target-domain
Int SemThread_pend(SemThread_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SemThread instance object
timeout — timeout in microseconds
eb — error block
DETAILS
  • PendStatus_ERROR if an error occured.
  • PendStatus_TIMEOUT denotes timeout.
  • PendStatus_SUCCESS semaphore was decremented. details.
RETURNS
refer to description above
SemThread_post() // instance
index URL

Increment the semaphore count

C synopsis target-domain
Bool SemThread_post(SemThread_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SemThread instance object
eb — error block
RETURNS
true for success, false for error in error block
Instance Convertors
index URL

C synopsis target-domain
ISemaphore_Handle SemThread_Handle_upCast(SemThread_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SemThread_Handle SemThread_Handle_downCast(ISemaphore_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SemThread_Object_count();
// The number of statically-created instance objects
SemThread_Handle SemThread_Object_get(SemThread_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SemThread_Handle SemThread_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SemThread_Handle SemThread_Object_next(SemThread_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SemThread_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SemThread_Handle_label(SemThread_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SemThread_Handle_name(SemThread_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/SemThread.xdc
var SemThread = xdc.useModule('xdc.runtime.knl.SemThread');
local proxy modules
     SemThread.Proxy// Proxy that needs to be bound to an OS specific delegate = ISemThreadSupport.Module null
         SemThread.Proxy.delegate$ = ISemThreadSupport.Module null
         SemThread.Proxy.abstractInstances$ = false
module-wide constants & types
    const SemThread.FOREVER// Used as the timeout value to specify wait forever = ~(0);
    values of type SemThread.Mode// Types of semaphores
        const SemThread.Mode_COUNTING// Counting semaphore;
        const SemThread.Mode_BINARY// Binary Semaphore;
    values of type SemThread.PendStatus// Error codes returned by Semaphore_pend
        const SemThread.PendStatus_ERROR;
        const SemThread.PendStatus_TIMEOUT;
        const SemThread.PendStatus_SUCCESS;
module-wide config parameters
     SemThread.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SemThread.Params// Instance config-params object;
        params.mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode ISemaphore.Mode_COUNTING;
per-instance creation
    var inst = SemThread.create// Create an instance-object(Int count, params);
proxy SemThread.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
SemThread.Proxy = ISemThreadSupport.Module null
// some delegate module inheriting the ISemThreadSupport interface
    SemThread.Proxy.delegate$ = ISemThreadSupport.Module null
    // explicit access to the currently bound delegate module
    SemThread.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
const SemThread.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCscript usage meta-domain
const SemThread.FOREVER = ~(0);
C SYNOPSIS
SemThread_FOREVER
enum SemThread.Mode
index URL

Types of semaphores

XDCscript usage meta-domain
values of type SemThread.Mode
    const SemThread.Mode_COUNTING;
    // Counting semaphore
    const SemThread.Mode_BINARY;
    // Binary Semaphore
C SYNOPSIS
SemThread_Mode
enum SemThread.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCscript usage meta-domain
values of type SemThread.PendStatus
    const SemThread.PendStatus_ERROR;
    const SemThread.PendStatus_TIMEOUT;
    const SemThread.PendStatus_SUCCESS;
C SYNOPSIS
SemThread_PendStatus
metaonly config SemThread.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SemThread.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SemThread.Params;
// Instance config-params object
    params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
    // Semaphore mode. Default is COUNTING
config SemThread.mode // instance
index URL

Semaphore mode. Default is COUNTING

XDCscript usage meta-domain
var params = new SemThread.Params;
...
params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SemThread.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SemThread.create(Int count, params);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function creates a new SemThread object which is initialized to count.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.Sync
index URL

Provides synchronization APIs when an ISync.Handle is available

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
The application must first obtain an ISync.Handle. It can get such a handle by directly calling SyncGeneric.create or SyncSemThread.create. Then the application can use the generic APIs provided by this module.
C synopsis target-domain sourced in xdc/runtime/knl/Sync.xdc
#include <xdc/runtime/knl/Sync.h>
Functions
Bool | Sync_query// Query for a particular quality(ISync_Handle sync, Int qual);
Void | Sync_signal// Called at completion of an activity(ISync_Handle sync);
Int | Sync_wait// Called to wait/poll for completion of an activity(ISync_Handle sync, UInt timeout, Error_Block *eb);
Functions common to all target modules
 | Sync_Module_getMask// Returns the diagnostics mask for this module, Sync_Module_hasMask// Test whether this module has a diagnostics mask, Sync_Module_heap// The heap from which this module allocates memory, Sync_Module_id// Get this module's unique id, Sync_Module_setMask// Set the diagnostics mask for this module, Sync_Module_startupDone// Test if this module has completed startup
Defines
#define | Sync_NO_WAIT// Used to specify no waiting (UInt)ISync.NO_WAIT
#define | Sync_WAIT_FOREVER// Used to wait forever (UInt)ISync.WAIT_FOREVER
Typedefs
typedef enum | Sync_WaitStatus// Error codes returned by Sync_wait ...
const Sync_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define Sync_NO_WAIT (UInt)ISync.NO_WAIT
const Sync_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define Sync_WAIT_FOREVER (UInt)ISync.WAIT_FOREVER
enum Sync_WaitStatus
index URL

Error codes returned by Sync_wait

C synopsis target-domain
typedef enum Sync_WaitStatus {
    Sync_WaitStatus_ERROR,
    Sync_WaitStatus_TIMEOUT,
    Sync_WaitStatus_SUCCESS
} Sync_WaitStatus;
Sync_query() // module-wide
index URL

Query for a particular quality

C synopsis target-domain
Bool Sync_query(ISync_Handle sync, Int qual);
ARGUMENTS
sync — sync handle
qual — quality
DETAILS
FALSE is returned if quality not supported.
RETURNS
TRUE or FALSE.
Sync_signal() // module-wide
index URL

Called at completion of an activity

C synopsis target-domain
Void Sync_signal(ISync_Handle sync);
ARGUMENTS
sync — sync handle
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
Sync_wait() // module-wide
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int Sync_wait(ISync_Handle sync, UInt timeout, Error_Block *eb);
ARGUMENTS
sync — sync handle
timeout — timeout in microseconds
DETAILS
This function can block and typically waits for a semaphore to become available.
Non-blocking implementations should return WaitStatus_TIMEOUT.
RETURNS
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Sync_Module_id();
// Get this module's unique id
Bool Sync_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Sync_Module_heap();
// The heap from which this module allocates memory
Bool Sync_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Sync_Module_getMask();
// Returns the diagnostics mask for this module
Void Sync_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
XDCscript usage meta-domain sourced in xdc/runtime/knl/Sync.xdc
var Sync = xdc.useModule('xdc.runtime.knl.Sync');
local proxy modules
     Sync.Proxy// Platform-specific implementation = ISync.Module null
         Sync.Proxy.delegate$ = ISync.Module null
         Sync.Proxy.abstractInstances$ = false
module-wide constants & types
    const Sync.NO_WAIT// Used to specify no waiting = ISync.NO_WAIT;
    const Sync.WAIT_FOREVER// Used to wait forever = ISync.WAIT_FOREVER;
    values of type Sync.WaitStatus// Error codes returned by Sync_wait
        const Sync.WaitStatus_ERROR;
        const Sync.WaitStatus_TIMEOUT;
        const Sync.WaitStatus_SUCCESS;
module-wide config parameters
     Sync.common$// Common module configuration parameters = Types.Common$ undefined;
proxy Sync.Proxy
index URL

Platform-specific implementation

XDCscript usage meta-domain
Sync.Proxy = ISync.Module null
// some delegate module inheriting the ISync interface
    Sync.Proxy.delegate$ = ISync.Module null
    // explicit access to the currently bound delegate module
    Sync.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
DETAILS
If ALL ISync.Handles were created using the same module (e.g SyncSemProcess), then setting Proxy to SyncSemProcess and Sync.Proxy.abstractInstances$ to false will improve the performance of the Sync APIs.
const Sync.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const Sync.NO_WAIT = ISync.NO_WAIT;
C SYNOPSIS
Sync_NO_WAIT
const Sync.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const Sync.WAIT_FOREVER = ISync.WAIT_FOREVER;
C SYNOPSIS
Sync_WAIT_FOREVER
enum Sync.WaitStatus
index URL

Error codes returned by Sync_wait

XDCscript usage meta-domain
values of type Sync.WaitStatus
    const Sync.WaitStatus_ERROR;
    const Sync.WaitStatus_TIMEOUT;
    const Sync.WaitStatus_SUCCESS;
C SYNOPSIS
Sync_WaitStatus
metaonly config Sync.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Sync.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Fri, 17 Jun 2011 00:24:38 GMT


module xdc.runtime.knl.SyncGeneric
index URL

Generic ISync implementation

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module allows users to plug in their own functions for signal, wait and query.
C synopsis target-domain sourced in xdc/runtime/knl/SyncGeneric.xdc
#include <xdc/runtime/knl/SyncGeneric.h>
Functions
Void | SyncGeneric_construct// Initialize a new instance object inside the provided structure(SyncGeneric_Struct *structP, const SyncGeneric_Params *params);
SyncGeneric_Handle | SyncGeneric_create// Allocate and initialize a new instance object and return its handle(const SyncGeneric_Params *params, Error_Block *eb);
Void | SyncGeneric_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncGeneric_Handle *handleP);
Void | SyncGeneric_destruct// Finalize the instance object inside the provided structure(SyncGeneric_Struct *structP);
Void | SyncGeneric_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncGeneric_Params *params);
Functions common to all ISync modules
Bool | SyncGeneric_query// Query for a particular quality(SyncGeneric_Handle handle, Int qual);
Void | SyncGeneric_signal// Called at completion of an activity(SyncGeneric_Handle handle);
Int | SyncGeneric_wait// Called to wait/poll for completion of an activity(SyncGeneric_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncGeneric_handle// Convert this instance structure pointer into an instance handle, SyncGeneric_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncGeneric_Handle_label// The label associated with this instance object, SyncGeneric_Handle_name// The name of this instance object, SyncGeneric_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncGeneric_Object_count// The number of statically-created instance objects, SyncGeneric_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncGeneric_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncGeneric_Object_heap// The heap used to allocate dynamically-created instance objects, SyncGeneric_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncGeneric_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncGeneric_Module_getMask// Returns the diagnostics mask for this module, SyncGeneric_Module_hasMask// Test whether this module has a diagnostics mask, SyncGeneric_Module_heap// The heap from which this module allocates memory, SyncGeneric_Module_id// Get this module's unique id, SyncGeneric_Module_setMask// Set the diagnostics mask for this module, SyncGeneric_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncGeneric_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncGeneric_Q_BLOCKING// Blocking quality (Int)1
#define | SyncGeneric_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncGeneric_Object * | SyncGeneric_Handle// Client reference to an instance object;
typedef struct | SyncGeneric_Object// Opaque internal representation of an instance object SyncGeneric_Object;
typedef struct | SyncGeneric_Params// Instance config-params structure ...
typedef Bool | (*SyncGeneric_QueryFunc// typedef for user specified wait function)(Int);
typedef Void | (*SyncGeneric_SignalFunc// typedef for user specified signal function)(UArg);
typedef struct | SyncGeneric_Struct// Opaque client structure large enough to hold an instance object SyncGeneric_Struct;
typedef Bool | (*SyncGeneric_WaitFunc// typedef for user specified wait function)(UArg,UInt);
typedef enum | SyncGeneric_WaitStatus// Error codes returned by ISync_wait ...
const SyncGeneric_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncGeneric_NO_WAIT (UInt)0
const SyncGeneric_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncGeneric_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncGeneric_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncGeneric_WAIT_FOREVER (UInt)~(0)
enum SyncGeneric_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncGeneric_WaitStatus {
    SyncGeneric_WaitStatus_ERROR,
    SyncGeneric_WaitStatus_TIMEOUT,
    SyncGeneric_WaitStatus_SUCCESS
} SyncGeneric_WaitStatus;
typedef SyncGeneric_QueryFunc
index URL

typedef for user specified wait function

C synopsis target-domain
typedef Bool (*SyncGeneric_QueryFunc)(Int);
typedef SyncGeneric_SignalFunc
index URL

typedef for user specified signal function

C synopsis target-domain
typedef Void (*SyncGeneric_SignalFunc)(UArg);
typedef SyncGeneric_WaitFunc
index URL

typedef for user specified wait function

C synopsis target-domain
typedef Bool (*SyncGeneric_WaitFunc)(UArg,UInt);
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncGeneric_Module_id();
// Get this module's unique id
Bool SyncGeneric_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncGeneric_Module_heap();
// The heap from which this module allocates memory
Bool SyncGeneric_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncGeneric_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncGeneric_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncGeneric_Object SyncGeneric_Object;
// Opaque internal representation of an instance object
typedef SyncGeneric_Object *SyncGeneric_Handle;
// Client reference to an instance object
typedef struct SyncGeneric_Struct SyncGeneric_Struct;
// Opaque client structure large enough to hold an instance object
SyncGeneric_Handle SyncGeneric_handle(SyncGeneric_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncGeneric_Struct *SyncGeneric_struct(SyncGeneric_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncGeneric_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    UArg signalArg;
    // user signal function arg
     SyncGeneric_QueryFunc userQuery;
    // user query function
     SyncGeneric_SignalFunc userSignal;
    // user signal function
     SyncGeneric_WaitFunc userWait;
    // user wait function
    UArg waitArg;
    // user wait function arg
} SyncGeneric_Params;
Void SyncGeneric_Params_init(SyncGeneric_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config SyncGeneric_signalArg // instance
index URL

user signal function arg

C synopsis target-domain
struct SyncGeneric_Params {
     ...
    UArg signalArg;
config SyncGeneric_userQuery // instance
index URL

user query function

C synopsis target-domain
struct SyncGeneric_Params {
     ...
     SyncGeneric_QueryFunc userQuery;
config SyncGeneric_userSignal // instance
index URL

user signal function

C synopsis target-domain
struct SyncGeneric_Params {
     ...
     SyncGeneric_SignalFunc userSignal;
config SyncGeneric_userWait // instance
index URL

user wait function

C synopsis target-domain
struct SyncGeneric_Params {
     ...
     SyncGeneric_WaitFunc userWait;
config SyncGeneric_waitArg // instance
index URL

user wait function arg

C synopsis target-domain
struct SyncGeneric_Params {
     ...
    UArg waitArg;
Instance Creation
index URL

C synopsis target-domain
SyncGeneric_Handle SyncGeneric_create(const SyncGeneric_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncGeneric_construct(SyncGeneric_Struct *structP, const SyncGeneric_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncGeneric_delete(SyncGeneric_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncGeneric_destruct(SyncGeneric_Struct *structP);
// Finalize the instance object inside the provided structure
SyncGeneric_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncGeneric_query(SyncGeneric_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncGeneric instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncGeneric_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncGeneric_signal(SyncGeneric_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncGeneric instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncGeneric_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncGeneric_wait(SyncGeneric_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncGeneric instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncGeneric_Handle_upCast(SyncGeneric_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncGeneric_Handle SyncGeneric_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncGeneric_Object_count();
// The number of statically-created instance objects
SyncGeneric_Handle SyncGeneric_Object_get(SyncGeneric_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncGeneric_Handle SyncGeneric_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncGeneric_Handle SyncGeneric_Object_next(SyncGeneric_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncGeneric_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncGeneric_Handle_label(SyncGeneric_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncGeneric_Handle_name(SyncGeneric_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/SyncGeneric.xdc
var SyncGeneric = xdc.useModule('xdc.runtime.knl.SyncGeneric');
module-wide constants & types
    const SyncGeneric.NO_WAIT// Used to specify no waiting = 0;
    const SyncGeneric.Q_BLOCKING// Blocking quality = 1;
    const SyncGeneric.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncGeneric.WaitStatus// Error codes returned by ISync_wait
        const SyncGeneric.WaitStatus_ERROR;
        const SyncGeneric.WaitStatus_TIMEOUT;
        const SyncGeneric.WaitStatus_SUCCESS;
module-wide config parameters
     SyncGeneric.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncGeneric.Params// Instance config-params object;
        params.signalArg// user signal function arg = UArg null;
        params.userQuery// user query function = Bool(*)(Int) null;
        params.userSignal// user signal function = Void(*)(UArg) null;
        params.userWait// user wait function = Bool(*)(UArg,UInt) null;
        params.waitArg// user wait function arg = UArg null;
per-instance creation
    var inst = SyncGeneric.create// Create an instance-object(params);
const SyncGeneric.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncGeneric.NO_WAIT = 0;
C SYNOPSIS
SyncGeneric_NO_WAIT
const SyncGeneric.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncGeneric.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncGeneric_Q_BLOCKING
const SyncGeneric.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncGeneric.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncGeneric_WAIT_FOREVER
enum SyncGeneric.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncGeneric.WaitStatus
    const SyncGeneric.WaitStatus_ERROR;
    const SyncGeneric.WaitStatus_TIMEOUT;
    const SyncGeneric.WaitStatus_SUCCESS;
C SYNOPSIS
SyncGeneric_WaitStatus
metaonly config SyncGeneric.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncGeneric.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
// Instance config-params object
    params.signalArg = UArg null;
    // user signal function arg
    params.userQuery = Bool(*)(Int) null;
    // user query function
    params.userSignal = Void(*)(UArg) null;
    // user signal function
    params.userWait = Bool(*)(UArg,UInt) null;
    // user wait function
    params.waitArg = UArg null;
    // user wait function arg
config SyncGeneric.signalArg // instance
index URL

user signal function arg

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
...
params.signalArg = UArg null;
C SYNOPSIS
null
config SyncGeneric.userQuery // instance
index URL

user query function

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
...
params.userQuery = Bool(*)(Int) null;
C SYNOPSIS
null
config SyncGeneric.userSignal // instance
index URL

user signal function

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
...
params.userSignal = Void(*)(UArg) null;
C SYNOPSIS
null
config SyncGeneric.userWait // instance
index URL

user wait function

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
...
params.userWait = Bool(*)(UArg,UInt) null;
C SYNOPSIS
null
config SyncGeneric.waitArg // instance
index URL

user wait function arg

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
...
params.waitArg = UArg null;
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncGeneric.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncGeneric.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:39 GMT


module xdc.runtime.knl.SyncNull
index URL

Empty ISync implementation used mainly for testing

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
C synopsis target-domain sourced in xdc/runtime/knl/SyncNull.xdc
#include <xdc/runtime/knl/SyncNull.h>
Functions
Void | SyncNull_construct// Initialize a new instance object inside the provided structure(SyncNull_Struct *structP, const SyncNull_Params *params);
SyncNull_Handle | SyncNull_create// Allocate and initialize a new instance object and return its handle(const SyncNull_Params *params, Error_Block *eb);
Void | SyncNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncNull_Handle *handleP);
Void | SyncNull_destruct// Finalize the instance object inside the provided structure(SyncNull_Struct *structP);
Void | SyncNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncNull_Params *params);
Functions common to all ISync modules
Bool | SyncNull_query// Query for a particular quality(SyncNull_Handle handle, Int qual);
Void | SyncNull_signal// Called at completion of an activity(SyncNull_Handle handle);
Int | SyncNull_wait// Called to wait/poll for completion of an activity(SyncNull_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncNull_handle// Convert this instance structure pointer into an instance handle, SyncNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncNull_Handle_label// The label associated with this instance object, SyncNull_Handle_name// The name of this instance object, SyncNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncNull_Object_count// The number of statically-created instance objects, SyncNull_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncNull_Object_heap// The heap used to allocate dynamically-created instance objects, SyncNull_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncNull_Module_getMask// Returns the diagnostics mask for this module, SyncNull_Module_hasMask// Test whether this module has a diagnostics mask, SyncNull_Module_heap// The heap from which this module allocates memory, SyncNull_Module_id// Get this module's unique id, SyncNull_Module_setMask// Set the diagnostics mask for this module, SyncNull_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncNull_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncNull_Q_BLOCKING// Blocking quality (Int)1
#define | SyncNull_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncNull_Object * | SyncNull_Handle// Client reference to an instance object;
typedef struct | SyncNull_Object// Opaque internal representation of an instance object SyncNull_Object;
typedef struct | SyncNull_Params// Instance config-params structure ...
typedef struct | SyncNull_Struct// Opaque client structure large enough to hold an instance object SyncNull_Struct;
typedef enum | SyncNull_WaitStatus// Error codes returned by ISync_wait ...
const SyncNull_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncNull_NO_WAIT (UInt)0
const SyncNull_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncNull_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncNull_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncNull_WAIT_FOREVER (UInt)~(0)
enum SyncNull_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncNull_WaitStatus {
    SyncNull_WaitStatus_ERROR,
    SyncNull_WaitStatus_TIMEOUT,
    SyncNull_WaitStatus_SUCCESS
} SyncNull_WaitStatus;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncNull_Module_id();
// Get this module's unique id
Bool SyncNull_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncNull_Module_heap();
// The heap from which this module allocates memory
Bool SyncNull_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncNull_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncNull_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncNull_Object SyncNull_Object;
// Opaque internal representation of an instance object
typedef SyncNull_Object *SyncNull_Handle;
// Client reference to an instance object
typedef struct SyncNull_Struct SyncNull_Struct;
// Opaque client structure large enough to hold an instance object
SyncNull_Handle SyncNull_handle(SyncNull_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncNull_Struct *SyncNull_struct(SyncNull_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncNull_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} SyncNull_Params;
Void SyncNull_Params_init(SyncNull_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
SyncNull_Handle SyncNull_create(const SyncNull_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncNull_construct(SyncNull_Struct *structP, const SyncNull_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncNull_delete(SyncNull_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncNull_destruct(SyncNull_Struct *structP);
// Finalize the instance object inside the provided structure
SyncNull_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncNull_query(SyncNull_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncNull instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncNull_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncNull_signal(SyncNull_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncNull instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncNull_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncNull_wait(SyncNull_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncNull instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncNull_Handle_upCast(SyncNull_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncNull_Handle SyncNull_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncNull_Object_count();
// The number of statically-created instance objects
SyncNull_Handle SyncNull_Object_get(SyncNull_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncNull_Handle SyncNull_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncNull_Handle SyncNull_Object_next(SyncNull_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncNull_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncNull_Handle_label(SyncNull_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncNull_Handle_name(SyncNull_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/SyncNull.xdc
var SyncNull = xdc.useModule('xdc.runtime.knl.SyncNull');
module-wide constants & types
    const SyncNull.NO_WAIT// Used to specify no waiting = 0;
    const SyncNull.Q_BLOCKING// Blocking quality = 1;
    const SyncNull.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncNull.WaitStatus// Error codes returned by ISync_wait
        const SyncNull.WaitStatus_ERROR;
        const SyncNull.WaitStatus_TIMEOUT;
        const SyncNull.WaitStatus_SUCCESS;
module-wide config parameters
     SyncNull.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncNull.Params// Instance config-params object;
per-instance creation
    var inst = SyncNull.create// Create an instance-object(params);
const SyncNull.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncNull.NO_WAIT = 0;
C SYNOPSIS
SyncNull_NO_WAIT
const SyncNull.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncNull.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncNull_Q_BLOCKING
const SyncNull.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncNull.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncNull_WAIT_FOREVER
enum SyncNull.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncNull.WaitStatus
    const SyncNull.WaitStatus_ERROR;
    const SyncNull.WaitStatus_TIMEOUT;
    const SyncNull.WaitStatus_SUCCESS;
C SYNOPSIS
SyncNull_WaitStatus
metaonly config SyncNull.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncNull.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncNull.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncNull.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncNull.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:39 GMT


module xdc.runtime.knl.SyncSemThread
index URL

A ISync implementation based on a SemThread. [EXPERIMENTAL]

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module implements the ti.sdo.utils.ISync interface using the xdc.runtime.knl.SemThread module.
C synopsis target-domain sourced in xdc/runtime/knl/SyncSemThread.xdc
#include <xdc/runtime/knl/SyncSemThread.h>
Functions
Void | SyncSemThread_construct// Initialize a new instance object inside the provided structure(SyncSemThread_Struct *structP, const SyncSemThread_Params *params, Error_Block *eb);
SyncSemThread_Handle | SyncSemThread_create// Allocate and initialize a new instance object and return its handle(const SyncSemThread_Params *params, Error_Block *eb);
Void | SyncSemThread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncSemThread_Handle *handleP);
Void | SyncSemThread_destruct// Finalize the instance object inside the provided structure(SyncSemThread_Struct *structP);
Void | SyncSemThread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncSemThread_Params *params);
Functions common to all ISync modules
Bool | SyncSemThread_query// Query for a particular quality(SyncSemThread_Handle handle, Int qual);
Void | SyncSemThread_signal// Called at completion of an activity(SyncSemThread_Handle handle);
Int | SyncSemThread_wait// Called to wait/poll for completion of an activity(SyncSemThread_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
 | SyncSemThread_handle// Convert this instance structure pointer into an instance handle, SyncSemThread_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncSemThread_Handle_label// The label associated with this instance object, SyncSemThread_Handle_name// The name of this instance object, SyncSemThread_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncSemThread_Object_count// The number of statically-created instance objects, SyncSemThread_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncSemThread_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncSemThread_Object_heap// The heap used to allocate dynamically-created instance objects, SyncSemThread_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncSemThread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | SyncSemThread_Module_getMask// Returns the diagnostics mask for this module, SyncSemThread_Module_hasMask// Test whether this module has a diagnostics mask, SyncSemThread_Module_heap// The heap from which this module allocates memory, SyncSemThread_Module_id// Get this module's unique id, SyncSemThread_Module_setMask// Set the diagnostics mask for this module, SyncSemThread_Module_startupDone// Test if this module has completed startup
Defines
#define | SyncSemThread_NO_WAIT// Used to specify no waiting (UInt)0
#define | SyncSemThread_Q_BLOCKING// Blocking quality (Int)1
#define | SyncSemThread_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncSemThread_Object * | SyncSemThread_Handle// Client reference to an instance object;
typedef struct | SyncSemThread_Object// Opaque internal representation of an instance object SyncSemThread_Object;
typedef struct | SyncSemThread_Params// Instance config-params structure ...
typedef struct | SyncSemThread_Struct// Opaque client structure large enough to hold an instance object SyncSemThread_Struct;
typedef enum | SyncSemThread_WaitStatus// Error codes returned by ISync_wait ...
const SyncSemThread_NO_WAIT
index URL

Used to specify no waiting

C synopsis target-domain
#define SyncSemThread_NO_WAIT (UInt)0
const SyncSemThread_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define SyncSemThread_Q_BLOCKING (Int)1
DETAILS
Implementations with this "quality" may cause the calling thread to block;
const SyncSemThread_WAIT_FOREVER
index URL

Used to wait forever

C synopsis target-domain
#define SyncSemThread_WAIT_FOREVER (UInt)~(0)
enum SyncSemThread_WaitStatus
index URL

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncSemThread_WaitStatus {
    SyncSemThread_WaitStatus_ERROR,
    SyncSemThread_WaitStatus_TIMEOUT,
    SyncSemThread_WaitStatus_SUCCESS
} SyncSemThread_WaitStatus;
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SyncSemThread_Module_id();
// Get this module's unique id
Bool SyncSemThread_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle SyncSemThread_Module_heap();
// The heap from which this module allocates memory
Bool SyncSemThread_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 SyncSemThread_Module_getMask();
// Returns the diagnostics mask for this module
Void SyncSemThread_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SyncSemThread_Object SyncSemThread_Object;
// Opaque internal representation of an instance object
typedef SyncSemThread_Object *SyncSemThread_Handle;
// Client reference to an instance object
typedef struct SyncSemThread_Struct SyncSemThread_Struct;
// Opaque client structure large enough to hold an instance object
SyncSemThread_Handle SyncSemThread_handle(SyncSemThread_Struct *structP);
// Convert this instance structure pointer into an instance handle
SyncSemThread_Struct *SyncSemThread_struct(SyncSemThread_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SyncSemThread_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
} SyncSemThread_Params;
Void SyncSemThread_Params_init(SyncSemThread_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Instance Creation
index URL

C synopsis target-domain
SyncSemThread_Handle SyncSemThread_create(const SyncSemThread_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void SyncSemThread_construct(SyncSemThread_Struct *structP, const SyncSemThread_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion
index URL

C synopsis target-domain
Void SyncSemThread_delete(SyncSemThread_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void SyncSemThread_destruct(SyncSemThread_Struct *structP);
// Finalize the instance object inside the provided structure
SyncSemThread_query() // instance
index URL

Query for a particular quality

C synopsis target-domain
Bool SyncSemThread_query(SyncSemThread_Handle handle, Int qual);
ARGUMENTS
handle — handle of a previously-created SyncSemThread instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
SyncSemThread_signal() // instance
index URL

Called at completion of an activity

C synopsis target-domain
Void SyncSemThread_signal(SyncSemThread_Handle handle);
ARGUMENTS
handle — handle of a previously-created SyncSemThread instance object
DETAILS
This function is non-blocking. It is also required that the underlying sync be binary in nature.
This function does not take an Error.Block intentionally because it can be called from ISR context.
SyncSemThread_wait() // instance
index URL

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncSemThread_wait(SyncSemThread_Handle handle, UInt timeout, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created SyncSemThread instance object
timeout — Timeout in microseconds
eb — Hist Pointer to Error.Block
RETURNS
Refer to description above
DETAILS
This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.
  • WaitStatus_ERROR if an error occured.
  • WaitStatus_TIMEOUT denotes timeout.
  • WaitStatus_SUCCESS semaphore was decremented.
Instance Convertors
index URL

C synopsis target-domain
ISync_Handle SyncSemThread_Handle_upCast(SyncSemThread_Handle handle);
// unconditionally move one level up the inheritance hierarchy
SyncSemThread_Handle SyncSemThread_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SyncSemThread_Object_count();
// The number of statically-created instance objects
SyncSemThread_Handle SyncSemThread_Object_get(SyncSemThread_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
SyncSemThread_Handle SyncSemThread_Object_first();
// The handle of the first dynamically-created instance object, or NULL
SyncSemThread_Handle SyncSemThread_Object_next(SyncSemThread_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle SyncSemThread_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *SyncSemThread_Handle_label(SyncSemThread_Handle handle, Types_Label *buf);
// The label associated with this instance object
String SyncSemThread_Handle_name(SyncSemThread_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/SyncSemThread.xdc
var SyncSemThread = xdc.useModule('xdc.runtime.knl.SyncSemThread');
module-wide constants & types
    const SyncSemThread.NO_WAIT// Used to specify no waiting = 0;
    const SyncSemThread.Q_BLOCKING// Blocking quality = 1;
    const SyncSemThread.WAIT_FOREVER// Used to wait forever = ~(0);
    values of type SyncSemThread.WaitStatus// Error codes returned by ISync_wait
        const SyncSemThread.WaitStatus_ERROR;
        const SyncSemThread.WaitStatus_TIMEOUT;
        const SyncSemThread.WaitStatus_SUCCESS;
module-wide config parameters
     SyncSemThread.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SyncSemThread.Params// Instance config-params object;
per-instance creation
    var inst = SyncSemThread.create// Create an instance-object(params);
const SyncSemThread.NO_WAIT
index URL

Used to specify no waiting

XDCscript usage meta-domain
const SyncSemThread.NO_WAIT = 0;
C SYNOPSIS
SyncSemThread_NO_WAIT
const SyncSemThread.Q_BLOCKING
index URL

Blocking quality

XDCscript usage meta-domain
const SyncSemThread.Q_BLOCKING = 1;
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
SyncSemThread_Q_BLOCKING
const SyncSemThread.WAIT_FOREVER
index URL

Used to wait forever

XDCscript usage meta-domain
const SyncSemThread.WAIT_FOREVER = ~(0);
C SYNOPSIS
SyncSemThread_WAIT_FOREVER
enum SyncSemThread.WaitStatus
index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncSemThread.WaitStatus
    const SyncSemThread.WaitStatus_ERROR;
    const SyncSemThread.WaitStatus_TIMEOUT;
    const SyncSemThread.WaitStatus_SUCCESS;
C SYNOPSIS
SyncSemThread_WaitStatus
metaonly config SyncSemThread.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SyncSemThread.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new SyncSemThread.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SyncSemThread.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = SyncSemThread.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Fri, 17 Jun 2011 00:24:39 GMT


module xdc.runtime.knl.Thread
index URL

Thread services

  • C synopsis
  • Individual elements
  • XDCscript usage
  • Individual elements
This module manages threads through a proxy which inherits from IThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/Thread.xdc
#include <xdc/runtime/knl/Thread.h>
Functions
Int | Thread_compareOsPriorities// Compare two os specific priority values and find out which one represents a higher priority(Int p1, Int p2, Error_Block *eb);
Void | Thread_construct// Initialize a new instance object inside the provided structure(Thread_Struct *structP, Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
Thread_Handle | Thread_create// Allocate and initialize a new instance object and return its handle(Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
Void | Thread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(Thread_Handle *handleP);
Void | Thread_destruct// Finalize the instance object inside the provided structure(Thread_Struct *structP);
Ptr | Thread_getOsHandle// Get the OS thread handle(Thread_Handle handle);
Int | Thread_getOsPriority// Obtain a thread's OS specific priority(Thread_Handle handle, Error_Block *eb);
Thread_Priority | Thread_getPriority// Obtain a thread's priority(Thread_Handle handle, Error_Block *eb);
Ptr | Thread_getTls// Obtain a thread's local storage(Thread_Handle handle);
Bool | Thread_join// Block calling thread until given thread terminates(Thread_Handle handle, Error_Block *eb);
Void | Thread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(Thread_Params *params);
Thread_Handle | Thread_self// Return the currently executing thread's handle(Error_Block *eb);
Bool | Thread_setOsPriority// Set a thread's priority(Thread_Handle handle, Int newPri, Error_Block *eb);
Bool | Thread_setPriority// Set a thread's priority(Thread_Handle handle, Thread_Priority newPri, Error_Block *eb);
Void | Thread_setTls// Change a thread's local storage(Thread_Handle handle, Ptr tls);
Bool | Thread_sleep// Sleep for given number of microseconds(UInt timeout, Error_Block *eb);
Bool | Thread_start// Start threads running(Error_Block *eb);
Bool | Thread_stat// Get thread statistics(Thread_Handle handle, Thread_Stat *buf, Error_Block *eb);
Bool | Thread_yield// Yield the currently scheduled thread(Error_Block *eb);
Functions common to all target instances
 | Thread_handle// Convert this instance structure pointer into an instance handle, Thread_Handle_label// The label associated with this instance object, Thread_Handle_name// The name of this instance object, Thread_Object_count// The number of statically-created instance objects, Thread_Object_first// The handle of the first dynamically-created instance object, or NULL, Thread_Object_get// The handle of the i-th statically-created instance object (array == NULL), Thread_Object_heap// The heap used to allocate dynamically-created instance objects, Thread_Object_next// The handle of the next dynamically-created instance object, or NULL, Thread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
 | Thread_Module_getMask// Returns the diagnostics mask for this module, Thread_Module_hasMask// Test whether this module has a diagnostics mask, Thread_Module_heap// The heap from which this module allocates memory, Thread_Module_id// Get this module's unique id, Thread_Module_setMask// Set the diagnostics mask for this module, Thread_Module_startupDone// Test if this module has completed startup
Defines
#define | Thread_GETPRI_FAILED// Status returned by getPri when an error occurs (Int)-2
#define | Thread_INVALID_OS_PRIORITY// Invalid OS priority value (Int)0
Typedefs
typedef enum | Thread_CompStatus// Status returned by compareOsPriorities when an error occurs ...
typedef Thread_Object * | Thread_Handle// Client reference to an instance object;
typedef struct | Thread_Object// Opaque internal representation of an instance object Thread_Object;
typedef struct | Thread_Params// Instance config-params structure ...
typedef enum | Thread_Priority// Thread priorities which are mapped to OS specific value by Proxy ...
typedef Void | (*Thread_RunFxn// Typedef for thread function)(IArg);
typedef struct | Thread_Stat// Struct to hold thread statistics from stat ...
typedef struct | Thread_Struct// Opaque client structure large enough to hold an instance object Thread_Struct;
Constants
extern const Assert_Id | Thread_A_zeroTimeout// Assert when timeout passed to sleep is zero;
extern const SizeT | Thread_defaultStackSize// Default thread stack size;
DETAILS
This module manages threads through a proxy which inherits from IThreadSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to a BIOS 6.x specific delegate.
  var Thread = xdc.useModule('xdc.runtime.knl.Thread');
  Thread.Proxy = xdc.useModule('ti.sysbios.xdcruntime.ThreadSupport');
Typically a package containing the delegates has a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule('ti.sysbios.xdcruntime.Settings');
const Thread_GETPRI_FAILED
index URL

Status returned by getPri when an error occurs

C synopsis target-domain
#define Thread_GETPRI_FAILED (Int)-2
const Thread_INVALID_OS_PRIORITY
index URL

Invalid OS priority value

C synopsis target-domain
#define Thread_INVALID_OS_PRIORITY (Int)0
enum Thread_CompStatus
index URL

Status returned by compareOsPriorities when an error occurs

C synopsis target-domain
typedef enum Thread_CompStatus {
    Thread_CompStatus_ERROR,
    Thread_CompStatus_LOWER,
    Thread_CompStatus_EQUAL,
    Thread_CompStatus_HIGHER
} Thread_CompStatus;
enum Thread_Priority
index URL

Thread priorities which are mapped to OS specific value by Proxy

C synopsis target-domain
typedef enum Thread_Priority {
    Thread_Priority_INVALID,
    Thread_Priority_LOWEST,
    Thread_Priority_BELOW_NORMAL,
    Thread_Priority_NORMAL,
    Thread_Priority_ABOVE_NORMAL,
    Thread_Priority_HIGHEST
} Thread_Priority;
typedef Thread_RunFxn
index URL

Typedef for thread function

C synopsis target-domain
typedef Void (*Thread_RunFxn)(IArg);
struct Thread_Stat
index URL

Struct to hold thread statistics from stat

C synopsis target-domain
typedef struct Thread_Stat {
    SizeT stackSize;
    SizeT stackUsed;
} Thread_Stat;
config Thread_A_zeroTimeout // module-wide
index URL

Assert when timeout passed to sleep is zero

C synopsis target-domain
extern const Assert_Id Thread_A_zeroTimeout;
config Thread_defaultStackSize // module-wide
index URL

Default thread stack size

C synopsis target-domain
extern const SizeT Thread_defaultStackSize;
Thread_compareOsPriorities() // module-wide
index URL

Compare two os specific priority values and find out which one represents a higher priority

C synopsis target-domain
Int Thread_compareOsPriorities(Int p1, Int p2, Error_Block *eb);
ARGUMENTS
p1 — priority one
p2 — priority two
eb — Pointer to Error.Block
DETAILS
  • CompStatus_ERROR if an error occured
  • CompStatus_LOWER if p1 is lower than p2
  • CompStatus_EQUAL if p1=p2
  • CompStatus_HIGHER if p1 is higher than p2 details.
RETURNS
refer to description above
Thread_self() // module-wide
index URL

Return the currently executing thread's handle

C synopsis target-domain
Thread_Handle Thread_self(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
RETURNS
Returns a handle to the currently executing thread. If the current thread is the main thread, this function returns NULL. NULL is also returned in case of error.
Thread_sleep() // module-wide
index URL

Sleep for given number of microseconds

C synopsis target-domain
Bool Thread_sleep(UInt timeout, Error_Block *eb);
ARGUMENTS
timeout — timeout in microseconds
eb — Pointer to Error.Block
DETAILS
This function is gauranteed to sleep for at least as long as the timeout value but the actual sleep time may be longer. NOTE: The timeout value cannot be zero.
RETURNS
true for success; false for error
Thread_start() // module-wide
index URL

Start threads running

C synopsis target-domain
Bool Thread_start(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
DETAILS
This function can be used to start all statically created threads, and all threads created dynamically before this function is called. Any thread created after this function is called, starts automatically. (i.e., there is no need to call Thread_start() more than once).
RETURNS
true for success; false for error
Thread_yield() // module-wide
index URL

Yield the currently scheduled thread

C synopsis target-domain
Bool Thread_yield(Error_Block *eb);
ARGUMENTS
eb — Pointer to Error.Block
RETURNS
true for success; false for error
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Thread_Module_id();
// Get this module's unique id
Bool Thread_Module_startupDone();
// Test if this module has completed startup
IHeap_Handle Thread_Module_heap();
// The heap from which this module allocates memory
Bool Thread_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Thread_Module_getMask();
// Returns the diagnostics mask for this module
Void Thread_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct Thread_Object Thread_Object;
// Opaque internal representation of an instance object
typedef Thread_Object *Thread_Handle;
// Client reference to an instance object
typedef struct Thread_Struct Thread_Struct;
// Opaque client structure large enough to hold an instance object
Thread_Handle Thread_handle(Thread_Struct *structP);
// Convert this instance structure pointer into an instance handle
Thread_Struct *Thread_struct(Thread_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct Thread_Params {
// Instance config-params structure
     IInstance_Params *instance;
    // Common per-instance configs
    IArg arg;
    // Thread function argument. Default is 0
    Int osPriority;
    // OS specific thread priority
     Thread_Priority priority;
    // Specify the new thread's priority
    SizeT stackSize;
    // Thread stack size
    Ptr tls;
    // Thread local storage
} Thread_Params;
Void Thread_Params_init(Thread_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
config Thread_arg // instance
index URL

Thread function argument. Default is 0

C synopsis target-domain
struct Thread_Params {
     ...
    IArg arg;
config Thread_osPriority // instance
index URL

OS specific thread priority

C synopsis target-domain
struct Thread_Params {
     ...
    Int osPriority;
DETAILS
Used to specify an OS specific value for priority. If set this value takes precedence over priority.
config Thread_priority // instance
index URL

Specify the new thread's priority

C synopsis target-domain
struct Thread_Params {
     ...
     Thread_Priority priority;
DETAILS
Thread defines several constants which allows applications to select a priority in an OS independent way: Priority_LOWEST, Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and Priority_HIGHEST. These values get mapped to OS specific priorities by the OS specific delegate.
config Thread_stackSize // instance
index URL

Thread stack size

C synopsis target-domain
struct Thread_Params {
     ...
    SizeT stackSize;
DETAILS
The default value of 0 means that defaultStackSize is used.
config Thread_tls // instance
index URL

Thread local storage

C synopsis target-domain
struct Thread_Params {
     ...
    Ptr tls;
DETAILS
User data associated with a thread. Must persist for the life of the thread.
Instance Creation
index URL

C synopsis target-domain
Thread_Handle Thread_create(Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
Void Thread_construct(Thread_Struct *structP, Thread_RunFxn fxn, const Thread_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
fxn — function for new thread to begin execution
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function spawns a new thread calling the function fxn.
Instance Deletion
index URL

C synopsis target-domain
Void Thread_delete(Thread_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
Void Thread_destruct(Thread_Struct *structP);
// Finalize the instance object inside the provided structure
Thread_getOsHandle() // instance
index URL

Get the OS thread handle

C synopsis target-domain
Ptr Thread_getOsHandle(Thread_Handle handle);
ARGUMENTS
handle — handle of a previously-created Thread instance object
RETURNS
OS thread handle
Thread_getOsPriority() // instance
index URL

Obtain a thread's OS specific priority

C synopsis target-domain
Int Thread_getOsPriority(Thread_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
eb — Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, the value returned is the base priority of the thread.
RETURNS
thread priority in case of success; GETPRI_FAILED in case of error;
Thread_getPriority() // instance
index URL

Obtain a thread's priority

C synopsis target-domain
Thread_Priority Thread_getPriority(Thread_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
eb — Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, this function retrieves the base priority of the thread.
RETURNS
thread priority in case of success; PRIORITY_INVALID in case of error;
Thread_getTls() // instance
index URL

Obtain a thread's local storage

C synopsis target-domain
Ptr Thread_getTls(Thread_Handle handle);
ARGUMENTS
handle — handle of a previously-created Thread instance object
RETURNS
null when tls has not been set.
Thread_join() // instance
index URL

Block calling thread until given thread terminates

C synopsis target-domain
Bool Thread_join(Thread_Handle handle, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
eb — Pointer to Error.Block
DETAILS
Use this functions to ensure that a thread has terminated. It is OK to call this function on a thread that has already terminated.
RETURNS
true for success; false for error
Thread_setOsPriority() // instance
index URL

Set a thread's priority

C synopsis target-domain
Bool Thread_setOsPriority(Thread_Handle handle, Int newPri, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
newPri — new thread priority
eb — Pointer to Error.Block
DETAILS
This API sets the base priority of the thread on OSes that support dynamic priority boosting
RETURNS
true for success; false for error
Thread_setPriority() // instance
index URL

Set a thread's priority

C synopsis target-domain
Bool Thread_setPriority(Thread_Handle handle, Thread_Priority newPri, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
newPri — new thread priority
eb — Pointer to Error.Block
DETAILS
For OSes that support dynamic priority boosting, this function changes the base priority of the thread.
RETURNS
true for success; false for error
Thread_setTls() // instance
index URL

Change a thread's local storage

C synopsis target-domain
Void Thread_setTls(Thread_Handle handle, Ptr tls);
ARGUMENTS
handle — handle of a previously-created Thread instance object
tls — tls
Thread_stat() // instance
index URL

Get thread statistics

C synopsis target-domain
Bool Thread_stat(Thread_Handle handle, Thread_Stat *buf, Error_Block *eb);
ARGUMENTS
handle — handle of a previously-created Thread instance object
buf — Pointer to Stat
eb — Pointer to Error.Block
RETURNS
true for success; false for failure
Instance Built-Ins
index URL

C synopsis target-domain
Int Thread_Object_count();
// The number of statically-created instance objects
Thread_Handle Thread_Object_get(Thread_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
Thread_Handle Thread_Object_first();
// The handle of the first dynamically-created instance object, or NULL
Thread_Handle Thread_Object_next(Thread_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
IHeap_Handle Thread_Object_heap();
// The heap used to allocate dynamically-created instance objects
Types_Label *Thread_Handle_label(Thread_Handle handle, Types_Label *buf);
// The label associated with this instance object
String Thread_Handle_name(Thread_Handle handle);
// The name of this instance object
XDCscript usage meta-domain sourced in xdc/runtime/knl/Thread.xdc
var Thread = xdc.useModule('xdc.runtime.knl.Thread');
local proxy modules
     Thread.Proxy// Proxy that needs to be bound to an OS specific delegate = IThreadSupport.Module null
         Thread.Proxy.delegate$ = IThreadSupport.Module null
         Thread.Proxy.abstractInstances$ = false
module-wide constants & types
    const Thread.GETPRI_FAILED// Status returned by getPri when an error occurs = -2;
    const Thread.INVALID_OS_PRIORITY// Invalid OS priority value = 0;
    values of type Thread.CompStatus// Status returned by compareOsPriorities when an error occurs
        const Thread.CompStatus_ERROR;
        const Thread.CompStatus_LOWER;
        const Thread.CompStatus_EQUAL;
        const Thread.CompStatus_HIGHER;
    values of type Thread.Priority// Thread priorities which are mapped to OS specific value by Proxy
        const Thread.Priority_INVALID;
        const Thread.Priority_LOWEST;
        const Thread.Priority_BELOW_NORMAL;
        const Thread.Priority_NORMAL;
        const Thread.Priority_ABOVE_NORMAL;
        const Thread.Priority_HIGHEST;
    var obj = new Thread.Stat// Struct to hold thread statistics from stat;
        obj.stackSize = SizeT ...
        obj.stackUsed = SizeT ...
module-wide config parameters
     Thread.A_zeroTimeout// Assert when timeout passed to sleep is zero = Assert.Desc {
        msg: "A_zeroTimeout: Timeout value annot be zero"
    };
     Thread.defaultStackSize// Default thread stack size = SizeT 0;
     Thread.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new Thread.Params// Instance config-params object;
        params.arg// Thread function argument. Default is 0 = IArg 0;
        params.osPriority// OS specific thread priority = Int Thread.INVALID_OS_PRIORITY;
        params.priority// Specify the new thread's priority = Thread.Priority Thread.Priority_NORMAL;
        params.stackSize// Thread stack size = SizeT 0;
        params.tls// Thread local storage = Ptr null;
per-instance creation
    var inst = Thread.create// Create an instance-object(Void(*)(IArg) fxn, params);
proxy Thread.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
Thread.Proxy = IThreadSupport.Module null
// some delegate module inheriting the IThreadSupport interface
    Thread.Proxy.delegate$ = IThreadSupport.Module null
    // explicit access to the currently bound delegate module
    Thread.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
const Thread.GETPRI_FAILED
index URL

Status returned by getPri when an error occurs

XDCscript usage meta-domain
const Thread.GETPRI_FAILED = -2;
C SYNOPSIS
Thread_GETPRI_FAILED
const Thread.INVALID_OS_PRIORITY
index URL

Invalid OS priority value

XDCscript usage meta-domain
const Thread.INVALID_OS_PRIORITY = 0;
C SYNOPSIS
Thread_INVALID_OS_PRIORITY
enum Thread.CompStatus
index URL

Status returned by compareOsPriorities when an error occurs

XDCscript usage meta-domain
values of type Thread.CompStatus
    const Thread.CompStatus_ERROR;
    const Thread.CompStatus_LOWER;
    const Thread.CompStatus_EQUAL;
    const Thread.CompStatus_HIGHER;
C SYNOPSIS
Thread_CompStatus
enum Thread.Priority
index URL

Thread priorities which are mapped to OS specific value by Proxy

XDCscript usage meta-domain
values of type Thread.Priority
    const Thread.Priority_INVALID;
    const Thread.Priority_LOWEST;
    const Thread.Priority_BELOW_NORMAL;
    const Thread.Priority_NORMAL;
    const Thread.Priority_ABOVE_NORMAL;
    const Thread.Priority_HIGHEST;
C SYNOPSIS
Thread_Priority
struct Thread.Stat
index URL

Struct to hold thread statistics from stat

XDCscript usage meta-domain
var obj = new Thread.Stat;
    obj.stackSize = SizeT ...
    obj.stackUsed = SizeT ...
C SYNOPSIS
Thread_Stat
config Thread.A_zeroTimeout // module-wide
index URL

Assert when timeout passed to sleep is zero

XDCscript usage meta-domain
Thread.A_zeroTimeout = Assert.Desc {
    msg: "A_zeroTimeout: Timeout value annot be zero"
};
C SYNOPSIS
Thread_A_zeroTimeout
config Thread.defaultStackSize // module-wide
index URL

Default thread stack size

XDCscript usage meta-domain
Thread.defaultStackSize = SizeT 0;
C SYNOPSIS
Thread_defaultStackSize
metaonly config Thread.common$ // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Thread.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new Thread.Params;
// Instance config-params object
    params.arg = IArg 0;
    // Thread function argument. Default is 0
    params.osPriority = Int Thread.INVALID_OS_PRIORITY;
    // OS specific thread priority
    params.priority = Thread.Priority Thread.Priority_NORMAL;
    // Specify the new thread's priority
    params.stackSize = SizeT 0;
    // Thread stack size
    params.tls = Ptr null;
    // Thread local storage
config Thread.arg // instance
index URL

Thread function argument. Default is 0

XDCscript usage meta-domain
var params = new Thread.Params;
...
params.arg = IArg 0;
C SYNOPSIS
null
config Thread.osPriority // instance
index URL

OS specific thread priority

XDCscript usage meta-domain
var params = new Thread.Params;
...
params.osPriority = Int Thread.INVALID_OS_PRIORITY;
DETAILS
Used to specify an OS specific value for priority. If set this value takes precedence over priority.
C SYNOPSIS
null
config Thread.priority // instance
index URL

Specify the new thread's priority

XDCscript usage meta-domain
var params = new Thread.Params;
...
params.priority = Thread.Priority Thread.Priority_NORMAL;
DETAILS
Thread defines several constants which allows applications to select a priority in an OS independent way: Priority_LOWEST, Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and Priority_HIGHEST. These values get mapped to OS specific priorities by the OS specific delegate.
C SYNOPSIS
null
config Thread.stackSize // instance
index URL

Thread stack size

XDCscript usage meta-domain
var params = new Thread.Params;
...
params.stackSize = SizeT 0;
DETAILS
The default value of 0 means that defaultStackSize is used.
C SYNOPSIS
null
config Thread.tls // instance
index URL

Thread local storage

XDCscript usage meta-domain
var params = new Thread.Params;
...
params.tls = Ptr null;
DETAILS
User data associated with a thread. Must persist for the life of the thread.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new Thread.Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = Thread.create(Void(*)(IArg) fxn, params);
// Create an instance-object
ARGUMENTS
fxn — function for new thread to begin execution
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
This function spawns a new thread calling the function fxn.
generated on Fri, 17 Jun 2011 00:24:39 GMT


All Packages

package ti.sysbios;
// SYS/BIOS Scalable/Extensible Real-time Kernel
package ti.sysbios.benchmarks;
// BIOS 6 size and timing benchmarks
package ti.sysbios.family;
// Contains family-specific modules for SYS/BIOS
package ti.sysbios.family.arm;
// Contains specifications for the ARM family-specific SYS/BIOS functions
package ti.sysbios.family.arm.a8;
// Contains specifications for the a8 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.a8.intcps;
// Contains specifications for the a8 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.a8.omap3430;
// Contains specifications for the a8 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.a8.sim;
// Contains specifications for the a8 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.a8.ti81xx;
// Contains specifications for the a8 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.arm9;
// Contains specifications for the ARM9 family-specific SYS/BIOS functions
package ti.sysbios.family.arm.da830;
// Contains specifications for the.da830 device-specific SYS/BIOS functions
package ti.sysbios.family.arm.dm6446;
// Contains specifications for the dm6446 device-specific SYS/BIOS functions
package ti.sysbios.family.arm.ducati;
// Contains specifications for the Ducati device-specific SYS/BIOS functions
package ti.sysbios.family.arm.ducati.dm8148;
// Contains dm8148 Hwi helper module
package ti.sysbios.family.arm.ducati.omap4430;
// Contains specifications for the Ducati, on OMAP4430
package ti.sysbios.family.arm.exc;
// Contains the ARM Exception handler used by all non-M3 ARM targets
package ti.sysbios.family.arm.f28m35x;
// Contains specifications for the C28 specific SYS/BIOS functions
package ti.sysbios.family.arm.lm3;
// Contains specifications for the Stellaris LM3S family of device-specific SYS/BIOS functions
package ti.sysbios.family.arm.m3;
// Contains specifications for the m3 family/device-specific SYS/BIOS functions
package ti.sysbios.family.arm.tms570;
// Contains specifications for the tms570 family of device-specific SYS/BIOS functions
package ti.sysbios.family.arp32;
// Contains specifications for the unit tests of the SYS/BIOS kernel
package ti.sysbios.family.c28;
// Contains specifications for the C28 specific SYS/BIOS functions
package ti.sysbios.family.c28.f28m35x;
// Contains specifications for the C28 specific SYS/BIOS functions
package ti.sysbios.family.c62;
// Contains specifications for C6x specific SYS/BIOS functions
package ti.sysbios.family.c64;
// Contains specifications for the C64 specific SYS/BIOS functions
package ti.sysbios.family.c64p;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.dm6437;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.dm6446;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.omap3430;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.primus;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.tci6482;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.tci6488;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c64p.tesla;
// Contains specifications for the c64p.tesla-specific SYS/BIOS functions
package ti.sysbios.family.c64p.ti81xx;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c66;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.family.c66.tci66xx;
//
package ti.sysbios.family.c67p;
// Contains specifications for the C64 specific SYS/BIOS functions
package ti.sysbios.family.msp430;
// Contains specifications for the msp430 family-specific SYS/BIOS functions
package ti.sysbios.family.windows;
// Native Windows SYS/BIOS Support
package ti.sysbios.gates;
// Contains modules that inherit from IGatePovider
package ti.sysbios.hal;
// Contains Hardware Abstraction Layer (HAL) modules for the SYS/BIOS kernel
package ti.sysbios.hal.ammu;
// Contains the AMMU module
package ti.sysbios.hal.unicache;
// Contains the unicache Cache module
package ti.sysbios.heaps;
// Contains modules that inherit from IHeap
package ti.sysbios.interfaces;
// Contains all interface specifications
package ti.sysbios.knl;
// Contains core threading modules for the SYS/BIOS kernel
package ti.sysbios.rta;
// Contains modules that provide support for RTA tools in CCS
package ti.sysbios.syncs;
// Contains modules that implement the ISync interface
package ti.sysbios.timers;
// Contains various timer modules
package ti.sysbios.timers.dmtimer;
// Contains specifications for the DMTimer
package ti.sysbios.timers.gptimer;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.timers.timer64;
// Contains specifications for the C64P specific SYS/BIOS functions
package ti.sysbios.utils;
// Miscellaneous utility modules
package xdc.runtime;
// Basic runtime support for RTSC programs
package xdc.runtime.knl;
// XDC Runtime support for OS-related primitives
generated on Fri, 17 Jun 2011 00:24:47 GMT


module ti.sysbios.BIOS

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== BIOS.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Error;
    42    import xdc.runtime.Types;
    43
    44    /*! ======== BIOS ========
    45     *  SYS/BIOS Master Manager
    46     *
    47     *  This module is responsible for setting up global parameters
    48     *  pertaining to SYS/BIOS and for performing the SYS/BIOS startup
    49     *  sequence.
    50     *
    51     *  SYS/BIOS configures the
    52     *  {@link xdc.runtime.Memory#defaultHeapInstance Memory.defaultHeapInstance}
    53     *  using a {@link ti.sysbios.heaps.HeapMem HeapMem} instance of size
    54     *  {@link #heapSize}.
    55     *
    56     *  The SYS/BIOS startup sequence is logically divided into two phases: those
    57     *  operations that occur prior to the application's "main()" function being
    58     *  called, and those operations that are performed after the application's
    59     *  "main()" function is invoked.
    60     *
    61     *  The "before main()" startup sequence is governed completely by the RTSC
    62     *  runtime package.
    63     *
    64     *  The "after main()" startup sequence is governed by SYS/BIOS and is
    65     *  initiated by an explicit call to the {@link #start BIOS_start()} function
    66     *  at the end of the application's main() function.
    67     *
    68     *  Control points are provided at various places in each of the two startup
    69     *  sequences for user startup operations to be inserted.
    70     *
    71     *  The RTSC runtime startup sequence is as follows:
    72     *
    73     *  @p(nlist)
    74     *  - Immediately after CPU reset, perform target-specific CPU
    75     *  initialization (beginning at c_int00).
    76     *  - Prior to cinit(), run the single user-supplied "reset function"
    77     *  (see {@link xdc.runtime.Startup#resetFxn Startup.resetFxn}).
    78     *  - Run cinit() to initialize C runtime environment.
    79     *  - Run the user-supplied "first functions"
    80     *  (see {@link xdc.runtime.Startup#firstFxns Startup.firstFxns}).
    81     *  - Run all the module initialization functions.
    82     *  - Run pinit().
    83     *  - Run the user-supplied "last functions"
    84     *  (see {@link xdc.runtime.Startup#lastFxns Startup.lastFxns}).
    85     *  - Run main().
    86     *  @p
    87     *
    88     *  The SYS/BIOS startup sequence begins at the end of main() when
    89     *  BIOS_start() is called:
    90     *
    91     *  @p(nlist)
    92     *  - Run the user-supplied "startup functions"
    93     *  (see {@link #startupFxns BIOS.startupFxns}).
    94     *  - Enable Hardware Interrupts.
    95     *  - Enable Software Interrupts. If the system supports Software Interrupts
    96     *  (Swis) (see {@link #swiEnabled BIOS.swiEnabled}), then the SYS/BIOS
    97     *  startup sequence enables Swis at this point.
    98     *  - Timer Startup. If the system supports Timers, then at this point all
    99     *  statically configured timers are initialized per their
   100     *  user-configuration.
   101     *  If a timer was configured to start "automatically", it is started here.
   102     *  - Task Startup. If the system supports Tasks
   103     *  (see {@link #taskEnabled BIOS.taskEnabled}),
   104     *  then task scheduling begins here. If there are no statically or
   105     *  dynamically created Tasks in the system, then execution proceeds
   106     *  directly to the Idle loop.
   107     *  @p
   108     *
   109     *  Below is a configuration script excerpt that installs a user-supplied
   110     *  startup function at every possible control point in the RTSC and
   111     *  SYS/BIOS startup
   112     *  sequence:
   113     *
   114     *  @p(code)
   115     *  // get handle to xdc Startup module
   116     *  var Startup = xdc.useModule('xdc.runtime.Startup');
   117     *
   118     *  // install "reset function"
   119     *  Startup.resetFxn = '&myReset';
   120     *
   121     *  // install a "first function"
   122     *  var len = Startup.firstFxns.length
   123     *  Startup.firstFxns.length++;
   124     *  Startup.firstFxns[len] = '&myFirst';
   125     *
   126     *  // install a "last function"
   127     *  var len = Startup.lastFxns.length
   128     *  Startup.lastFxns.length++;
   129     *  Startup.lastFxns[len] = '&myLast';
   130     *
   131     *  // get handle to SYS/BIOS module
   132     *  var BIOS = xdc.useModule('ti.sysbios.BIOS');
   133     *
   134     *  // install a SYS/BIOS startup function
   135     *  BIOS.addUserStartupFunction('&myBiosStartup');
   136     *  @p
   137     *
   138     *  @p(html)
   139     *  <h3> Calling Context </h3>
   140     *  <table border="1" cellpadding="3">
   141     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   142     *    </colgroup>
   143     *
   144     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   145     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   146     *    <!--                                        -->
   147     *    <tr><td> {@link #getCpuFreq}      </td><td>   Y    </td><td>   Y    </td>
   148     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   149     *    <tr><td> {@link #getThreadType}   </td><td>   Y    </td><td>   Y    </td>
   150     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   151     *    <tr><td> {@link #setCpuFreq}      </td><td>   Y    </td><td>   Y    </td>
   152     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   153     *    <tr><td> {@link #start}      </td><td>   N    </td><td>   N    </td>
   154     *    <td>   N    </td><td>   Y    </td><td>   N    </td></tr>
   155     *    <tr><td colspan="6"> Definitions: <br />
   156     *       <ul>
   157     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   158     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   159     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   160     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   161     *           <ul>
   162     *             <li> In your module startup after this module is started
   163     *                  (e.g. BIOS_Module_startupDone() returns TRUE). </li>
   164     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   165     *             <li> During main().</li>
   166     *             <li> During BIOS.startupFxns.</li>
   167     *           </ul>
   168     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   169     *           <ul>
   170     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   171     *             <li> In your module startup before this module is started
   172     *                  (e.g. BIOS_Module_startupDone() returns FALSE).</li>
   173     *           </ul>
   174     *       </ul>
   175     *    </td></tr>
   176     *
   177     *  </table>
   178     *  @p
   179     */
   180
   181    @CustomHeader   /* to check for codegen compatibility */
   182    @Template("./BIOS.xdt")
   183
   184    module BIOS
   185    {
   186        /*!
   187         *  ======== ThreadType ========
   188         *  Current thread type definitions
   189         *
   190         *  These values are returned by {@link #getThreadType BIOS_getThreadType}.
   191         *
   192         *  @see #getThreadType
   193         */
   194        enum ThreadType {
   195            ThreadType_Hwi,         /*! Current thread is a Hwi */
   196            ThreadType_Swi,         /*! Current thread is a Swi */
   197            ThreadType_Task,        /*! Current thread is a Task */
   198            ThreadType_Main         /*! Current thread is Boot/Main */
   199        };
   200
   201        /*!
   202         *  ======== RtsLockType ========
   203         *  Type of Gate to use in the TI RTS library
   204         *
   205         *  @field(NoLocking) no gate is added to the RTS library.  In this case,
   206         *  the application needs to be careful to always serialize access to the
   207         *  inherently  non-reentrant ANSI C functions (such as `malloc()`,
   208         *  `printf()`, etc.).
   209         *
   210         *  @field(GateHwi) Interrupts are disabled and restored to maintain
   211         *  re-entrancy.  This is a very efficient lock but will also result in
   212         *  unbounded interrupt latency times.  If real-time responce to interrupts
   213         *  is important, you should not use this gate to lock the RTS library.
   214         *
   215         *  @field(GateSwi) Swis are disabled and restored to maintain
   216         *  re-entrancy.
   217         *
   218         *  @field(GateMutex) A single mutex is used to maintain re-entrancy.
   219         *
   220         *  @field(GateMutexPri) A single priority inheriting mutex is used to
   221         *  maintain re-entrancy.
   222         *
   223         *  @see #rtsGateType
   224         */
   225        enum RtsLockType {
   226            NoLocking,
   227            GateHwi,
   228            GateSwi,
   229            GateMutex,
   230            GateMutexPri
   231        };
   232
   233        /*!
   234         *  ======== LibType ========
   235         *  SYS/BIOS library selection options
   236         *
   237         *  This enumeration defines all the SYS/BIOS library types
   238         *  provided by the product.  You can select the library type by setting
   239         *  the {@link #libType BIOS.libType} configuration parameter.
   240         *
   241         *  @field(LibType_Instrumented) The library supplied is prebuilt with
   242         *  logging and assertions enabled.
   243         *
   244         *  @field(LibType_NonInstrumented) The library supplied is prebuilt
   245         *  with logging and assertions disabled.
   246         *
   247         *  @field(LibType_Debug) The library supplied is prebuilt with
   248         *  logging and assertions enabled together with full symbolic debug
   249         *  enabled.  In addition, this library contains embedded information
   250         *  that enables it to participate in whole program optimization builds.
   251         *
   252         *  @field(LibType_Custom) This option allows you to build the
   253         *  SYS/BIOS library from sources using the options specified by
   254         *  {@link #customCCOpts}.
   255         *
   256         *  @see #libType
   257         */
   258        enum LibType {
   259            LibType_Instrumented,           /*! instrumented */
   260            LibType_NonInstrumented,        /*! non-instrumented */
   261            LibType_Custom,                 /*! custom */
   262            LibType_Debug                   /*! debug */
   263        };
   264
   265        /*! Used in APIs that take a timeout to specify wait forever */
   266        const UInt WAIT_FOREVER = ~(0);
   267
   268        /*! Used in APIs that take a timeout to specify no waiting */
   269        const UInt NO_WAIT = 0;
   270
   271        /*! User startup function type definition. */
   272        typedef Void (*StartupFuncPtr)(Void);
   273
   274        /*!
   275         *  ======== ModuleView ========
   276         *  @_nodoc
   277         */
   278        metaonly struct ModuleView {
   279            String       currentThreadType;
   280            String       rtsGateType;
   281            Int          cpuFreqLow;
   282            Int          cpuFreqHigh;
   283            Bool         clockEnabled;
   284            Bool         swiEnabled;
   285            Bool         taskEnabled;
   286            String       startFunc;
   287        }
   288
   289        /*!
   290         *  ======== ErrorView ========
   291         *  @_nodoc
   292         */
   293        metaonly struct ErrorView {
   294            String mod;
   295            String tab;
   296            String inst;
   297            String field;
   298            String message;
   299        }
   300
   301        /*!
   302         *  ======== rovViewInfo ========
   303         *  @_nodoc
   304         */
   305        @Facet
   306        metaonly config ViewInfo.Instance rovViewInfo =
   307            ViewInfo.create({
   308                viewMap: [
   309                [
   310                    'Module',
   311                    {
   312                        type: ViewInfo.MODULE,
   313                        viewInitFxn: 'viewInitModule',
   314                        structName: 'ModuleView'
   315                    }
   316                ],
   317                [
   318                    'Scan for errors...',
   319                    {
   320                        type: ViewInfo.MODULE_DATA,
   321                        viewInitFxn: 'viewInitErrorScan',
   322                        structName: 'ErrorView'
   323                    }
   324                ],
   325                ]
   326            });
   327
   328        /*!
   329         *  ======== libType ========
   330         *  SYS/BIOS Library type
   331         *
   332         *  The SYS/BIOS runtime is provided in the form of a library that is
   333         *  linked with your application.  Several forms of this library are
   334         *  provided with the SYS/BIOS product.  In addition, there is an
   335         *  option to build the library from source.  This configuration parameter
   336         *  allows you to select the form of SYS/BIOS to use.
   337         *
   338         *  The default value of libType is
   339         *  {@link #LibType_Instrumented BIOS_LibType_Instrumented}.  For a
   340         *  complete list of options and what they offer see {@link #LibType}.
   341         */
   342        metaonly config LibType libType = LibType_Instrumented;
   343
   344        /*!
   345         *  ======== customCCOpts ========
   346         *  Compiler options used to build custom library
   347         */
   348        metaonly config String customCCOpts;
   349
   350        /*!
   351         *  ======== cpuFreq ========
   352         *  CPU frequency in Hz
   353         *
   354         *  This configuration parameter allow SYS/BIOS to convert various
   355         *  periods between timer ticks (or instruction cycles) and real-time
   356         *  units.  For example, timer periods expressed in micro-seconds need
   357         *  to be converted into timer ticks in order to properly program the
   358         *  timers.
   359         *
   360         *  The default value of this parameter is obtained from the platform
   361         *  (the clockRate property of {@link xdc.cfg.Program#cpu Program.cpu})
   362         *  which is the CPU clock rate when the processor is reset.
   363         *
   364         *  @a(Example)
   365         *  If CPU frequency is 720MHz, the following configuration script
   366         *  configures SYS/BIOS with the proper clock frequency:
   367         *  @p(code)
   368         *     var BIOS = xdc.useModule('ti.sysbios.BIOS');
   369         *     BIOS.cpuFreq.hi = 0;
   370         *     BIOS.cpuFreq.lo = 720000000;
   371         *  @p
   372         */
   373        config Types.FreqHz cpuFreq;
   374
   375        /*!
   376         *  ======== taskEnabled ========
   377         *  SYS/BIOS Task services enable flag.
   378         *
   379         *  The following behaviors occur when {@link #taskEnabled} is
   380         *  set to false:
   381         *
   382         *  @p(blist)
   383         *  - Static {@link ti.sysbios.knl.Task Task} creation will
   384         *    result in a fatal build error.
   385         *  - The Idle task object is not created.
   386         *    (The Idle functions are invoked within the {@link #start()}
   387         *    thread.)
   388         *  - Runtime calls to Task_create will trigger an assertion violation
   389         *    via {@link xdc.runtime.Assert#isTrue}.
   390         *  @p
   391         */
   392        config Bool taskEnabled = true;
   393
   394        /*!
   395         *  ======== swiEnabled ========
   396         *  SYS/BIOS Swi services enable flag.
   397         *
   398         *  The following behaviors occur when {@link #swiEnabled} is
   399         *  set to false:
   400         *
   401         *  @p(blist)
   402         *  - Static {@link ti.sysbios.knl.Swi Swi} creation will
   403         *    result in a fatal build error.
   404         *  - The {@link ti.sysbios.knl.Clock Clock module} is
   405         *    effectively disabled as it uses a Swi
   406         *    to process the Clock objects.
   407         *  - See other effects as noted for {@link #clockEnabled} = false;
   408         *  - Runtime calls to Swi_create will trigger an assertion violation
   409         *    via {@link xdc.runtime.Assert#isTrue}.
   410         *  @p
   411         */
   412        config Bool swiEnabled = true;
   413
   414        /*!
   415         *  ======== clockEnabled ========
   416         *  SYS/BIOS Clock services enable flag.
   417         *
   418         *  The following behaviors occur when {@link #clockEnabled} is
   419         *  set to false:
   420         *
   421         *  @p(blist)
   422         *  - Static Clock creation will result in a fatal build error.
   423         *  - No Clock Swi is created.
   424         *  - The {@link ti.sysbios.knl.Clock#tickSource Clock_tickSource}
   425         *    is set to
   426         *    {@link ti.sysbios.knl.Clock#TickSource_NULL Clock_TickSource_NULL}
   427         *    to prevent a Timer object from being created.
   428         *  - For APIs that take a timeout, values other than {@link #NO_WAIT}
   429         *    will be equivalent to {@link #WAIT_FOREVER}.
   430         *  @p
   431         */
   432        config Bool clockEnabled = true;
   433
   434        /*!
   435         *  ======== assertsEnabled ========
   436         *  SYS/BIOS Assert checking in Custom SYS/BIOS library enable flag
   437         *
   438         *  When set to true, Assert checking code is compiled into
   439         *  the custom library created when BIOS.libType = BIOS.LibType_Custom.
   440         *
   441         *  When set to false, Assert checking code is removed from
   442         *  the custom library created when BIOS.libType = BIOS.LibType_Custom.
   443         *  This option can considerably improve runtime performance as well
   444         *  signficantly reduce the application's code size.
   445         *
   446         *  see {@link #libType BIOS.libType}.
   447         */
   448        metaonly config Bool assertsEnabled = true;
   449
   450        /*!
   451         *  ======== logsEnabled ========
   452         *  SYS/BIOS Log support in Custom SYS/BIOS library enable flag
   453         *
   454         *  When set to true, SYS/BIOS execution Log code is compiled into
   455         *  the custom library created when BIOS.libType = BIOS.LibType_Custom.
   456         *
   457         *  When set to false, all Log code is removed from
   458         *  the custom library created when BIOS.libType = BIOS.LibType_Custom.
   459         *  This option can considerably improve runtime performance as well
   460         *  signficantly reduce the application's code size.
   461         *
   462         *  see {@link #libType BIOS.libType}.
   463         */
   464        metaonly config Bool logsEnabled = true;
   465
   466        /*!
   467         *  ======== heapSize ========
   468         *  Size of system heap.
   469         *
   470         *  If the application configuration does not set
   471         *  Memory.defaultHeapInstance, then SYS/BIOS will create a
   472         *  {@link ti.sysbios.heaps.HeapMem HeapMem} heap of this size.  This
   473         *  heap will be assigned to
   474         *  {@link xdc.runtime.Memory#defaultHeapInstance Memory.defaultHeapInstance}
   475         *  and will therefore be used as the default system heap.  This heap
   476         *  will also be used by the SYS/BIOS version of the standard C library
   477         *  functions malloc(), calloc() and free().
   478         */
   479        config SizeT heapSize = 0x1000;
   480
   481        /*!
   482         *  ======== heapSection ========
   483         *  Section to place the system heap.
   484         *
   485         *  This configuration parameter allows you to specify a named output
   486         *  section that will contain the SYS/BIOS system heap.  The system heap
   487         *  is, by default, used to allocate {@link ti.sysbios.knl.Task Task}
   488         *  stacks and instance object state structures.  So, giving this section
   489         *  a name and explicitly placing it via a linker command file can
   490         *  significantly improve system performance.
   491         *
   492         *  If heapSection is `null` (or `undefined`) the system heap is placed in
   493         *  the target's default data section.
   494         */
   495        config String heapSection = null;
   496
   497        /*!
   498         *  ======== rtsGateType ========
   499         *  Gate to make sure TI RTS library APIs are re-entrant.
   500         *
   501         *  The application gets to determine the type of gate (lock) that is used
   502         *  in the TI RTS library. The gate will be used to guarantee re-entrancy
   503         *  of the RTS APIs.
   504         *
   505         *  The type of gate depends on the type of threads that are going to
   506         *  be calling into the RTS library.  For example, if both Swi and Task
   507         *  threads are going to be calling the RTS library's printf, GateSwi
   508         *  should be used. In this case, Hwi threads are not impacted (i.e.
   509         *  disabled) during the printf calls from the Swi or Task threads.
   510         *
   511         *  If NoLocking is used, the RTS lock is not plugged and re-entrancy for
   512         *  the TI RTS library calls are not guaranteed. The application can plug
   513         *  the RTS locks directly if it wants.
   514         *
   515         *  Numerous gate types are provided by SYS/BIOS.  Each has its advantages
   516         *  and disadvantages.  The following list summarizes when each type is
   517         *  appropriate for protecting an underlying non-reentrant RTS library.
   518         *  @p(dlist)
   519         *      - {@link #GateHwi}:
   520         *        Interrupts are disabled and restored to maintain re-entrancy.
   521         *        Use if only making RTS calls from a Hwi, Swi and/or Task.
   522         *
   523         *      - {@link #GateSwi}:
   524         *        Swis are disabled and restored to maintain re-entrancy. Use if
   525         *        only making RTS calls from a Swi and/or Task.
   526         *
   527         *      - {@link #GateMutex}:
   528         *        A single mutex is used to maintain re-entrancy.  Use if only
   529         *        making RTS calls from a Task.  Blocks only Tasks that are
   530         *        also trying to execute critical regions of RTS library.
   531         *
   532         *      - {@link #GateMutexPri}:
   533         *        A priority inheriting mutex is used to maintain re-entrancy.
   534         *        Blocks only Tasks that are also trying to execute critical
   535         *        regions of RTS library.  Raises the priority of the Task that
   536         *        is executing the critical region in the RTS library to the
   537         *        level of the highest priority Task that is block by the mutex.
   538         *  @p
   539         *
   540         *  The default value of rtsGateType depends on the type of threading
   541         *  model enabled by other configuration parameters.
   542         *  If {@link #taskEnabled} is true, {@link #GateMutex} is used.
   543         *  If {@link #swiEnabled} is true and {@link #taskEnabled} is false:
   544         *  {@link #GateSwi} is used.
   545         *  If both {@link #swiEnabled} and {@link #taskEnabled} are false:
   546         *  {@link xdc.runtime#GateNull} is used.
   547         *
   548         *  If {@link #taskEnabled} is false, the user should not select
   549         *  {@link #GateMutex} (or other Task level gates). Similarly, if
   550         *  {@link #taskEnabled} and {@link #swiEnabled}are false, the user
   551         *  should not select {@link #GateSwi} or the Task level gates.
   552         */
   553        metaonly config RtsLockType rtsGateType;
   554
   555        /*!
   556         *  ======== startupFxns ========
   557         *  Functions to be executed at the beginning of BIOS_start()
   558         *
   559         *  These user (or middleware) functions are executed before Hwis,
   560         *  Swis, and Tasks are started.
   561         */
   562        metaonly config StartupFuncPtr startupFxns[] = [];
   563
   564        /*!
   565         *  ======== addUserStartupFunction ========
   566         *  @_nodoc
   567         *  Statically add a function to the startupFxns table.
   568         */
   569        metaonly Void addUserStartupFunction(StartupFuncPtr func);
   570
   571        /*!
   572         *  ======== start ========
   573         *  Start SYS/BIOS
   574         *
   575         *  The user's main() function is required to call this function
   576         *  after all other user initializations have been performed.
   577         *
   578         *  This function does not return.
   579         *
   580         *  This function performs any remaining SYS/BIOS initializations
   581         *  and then transfers control to the highest priority ready
   582         *  task if {@link #taskEnabled} is true. If {@link #taskEnabled}
   583         *  is false, control is transferred directly to the Idle Loop.
   584         *
   585         *  The SYS/BIOS start sequence is as follows:
   586         *  @p(blist)
   587         *  - Invoke all the functions in the {@link #startupFxns} array.
   588         *  - call {@link ti.sysbios.hal.Hwi#enable Hwi_startup()}
   589         *    to enable interrupts.
   590         *  - if {@link #swiEnabled} is true, call
   591         *    {@link ti.sysbios.knl.Swi#enable Swi_startup()} to enable
   592         *    the Swi scheduler.
   593         *  - Start any statically created or constructed Timers
   594         *    in the {@link ti.sysbios.hal.Timer#StartMode Timer_StartMode_AUTO}
   595         *    mode.
   596         *  - if {@link #taskEnabled} is true, enable the Task scheduler
   597         *    and transfer the execution thread to the highest priority
   598         *    task in the {@link ti.sysbios.knl.Task#Mode Task_Mode_READY}
   599         *    mode.
   600         *  - Otherwise, fall directly into the Idle Loop.
   601         *  @p
   602         *
   603         */
   604        @DirectCall
   605        Void start();
   606
   607        /*!
   608         *  ======== exit ========
   609         *  Exit currently running SYS/BIOS executable
   610         *
   611         *  This function is called when a SYS/BIOS executable needs to terminate
   612         *  normally.  This function sets the internal SYS/BIOS threadType to
   613         *  {@link #ThreadType_Main} and then calls
   614         *  {@link xdc.runtime.System#exit System_exit}(stat), passing along
   615         *  the 'stat' argument.
   616         *
   617         *  All functions bound via
   618         * `{@link xdc.runtime.System#atexit System_atexit}` or the ANSI C
   619         *  Standard Library `atexit` function are then executed.
   620         *
   621         *  @param(stat)    exit status to return to calling environment.
   622         */
   623        @DirectCall
   624        Void exit(Int stat);
   625
   626        /*!
   627         *  ======== getThreadType ========
   628         *  Get the current thread type
   629         *
   630         *  @b(returns)     Current thread type
   631         */
   632        @DirectCall
   633        ThreadType getThreadType();
   634
   635        /*!
   636         *  @_nodoc
   637         *  ======== setThreadType ========
   638         *  Set the current thread type
   639         *
   640         *  Called by the various threadType owners.
   641         *
   642         *  @param(ttype)   New thread type value
   643         *  @b(returns)     Previous thread type
   644         */
   645        @DirectCall
   646        ThreadType setThreadType(ThreadType ttype);
   647
   648        /*!
   649         *  ======== setCpuFrequnecy ========
   650         *  Set CPU Frequency in Hz
   651         *
   652         *  This API is not thread safe. Please use appropriate locks.
   653         */
   654        @DirectCall
   655        Void setCpuFreq(Types.FreqHz *freq);
   656
   657        /*!
   658         *  ======== getCpuFrequency ========
   659         *  Get CPU frequency in Hz
   660         *
   661         *  This API is not thread safe. Please use appropriate locks.
   662         */
   663        @DirectCall
   664        Void getCpuFreq(Types.FreqHz *freq);
   665
   666    internal:
   667
   668        /*!
   669         *  ======== buildingAppLib ========
   670         *  Enable custom build of SYS/BIOS from source
   671         *
   672         *  true = building application-specific custom lib
   673         *  false = building internal instrumented/nonInstrumented lib
   674         */
   675        metaonly config Bool buildingAppLib = true;
   676
   677        /*!
   678         *  ======== includeXdcRuntime ========
   679         *  Include xdc.runtime sources in custom build
   680         */
   681        metaonly config Bool includeXdcRuntime = false;
   682
   683        /*!
   684         *  ======== customBuild ========
   685         *  Enable custom build of SYS/BIOS from source
   686         *
   687         *  set to true when BIOS.libType == BIOS.LibType_Custom
   688         *  used for controling "visible" xml attribute.
   689         */
   690        metaonly config Bool customBuild = false;
   691
   692        /*!
   693         *  ======== libDir ========
   694         *  Specify output library directory
   695         */
   696        metaonly config String libDir = null;
   697
   698        /*!
   699         *  ======== getCCOpts ========
   700         *  Get the compiler options necessary to build
   701         */
   702        metaonly String getCCOpts(String target);
   703
   704        /*!
   705         *  ======== getDefs ========
   706         *  Get the compiler -D options necessary to build
   707         */
   708        metaonly String getDefs();
   709
   710        /*!
   711         *  ======== getCFiles ========
   712         *  Get the library C source files.
   713         */
   714        metaonly String getCFiles(String target);
   715
   716        /*!
   717         *  ======== getAsmFiles ========
   718         *  Get the library Asm source files.
   719         */
   720        metaonly Any getAsmFiles(String target);
   721
   722        /* used to determine number of bits in an Int */
   723        struct intSize {
   724            Int intSize;
   725        }
   726
   727        /* Number of bits in an integer. Used for error checking */
   728        metaonly config Char bitsPerInt;
   729
   730        /*
   731         *  Error.raiseHook that disables defangs GateMutex thread
   732         *  type checking assert
   733        */
   734        Void errorRaiseHook(Error.Block *eb);
   735
   736        /*
   737         *  User/default Error.raiseHook.
   738         *  BIOS_errorRaiseHook() calls this after defanging GateMutex
   739         */
   740        config Void (*installedErrorHook)(Error.Block *);
   741
   742        /* Generated start function */
   743        Void startFunc();
   744
   745        /*!
   746         *  ======== registerRTSLock ========
   747         *  Register the RTS lock
   748         *
   749         *  Added as a startup function in BIOS.xs.
   750         */
   751        Void registerRTSLock();
   752
   753        /*!
   754         *  ======== removeRTSLock ========
   755         *  Remove the RTS locks
   756         *
   757         *  This function is called by BIOS_exit().
   758         */
   759        Void removeRTSLock();
   760
   761        /*!
   762         *  ======== fireFrequencyUpdate ========
   763         */
   764        function fireFrequencyUpdate(newFreq);
   765
   766        /*! Gate proxy to be used for the rts gate */
   767        proxy RtsGateProxy inherits xdc.runtime.IGateProvider;
   768
   769        /*! Function type for BIOS_start generation */
   770        typedef Void (*StartFuncPtr)(void);
   771
   772        struct Module_State {
   773            Types.FreqHz                    cpuFreq;        /* in KHz */
   774            UInt                            rtsGateCount;   /* count for nesting */
   775            IArg                            rtsGateKey;     /* count for nesting */
   776            RtsGateProxy.Handle             rtsGate;
   777            ThreadType                      threadType;     /* Curr Thread Type */
   778                                                            /* (Hwi, Swi, Task) */
   779            StartFuncPtr                    startFunc;
   780        };
   781    }
   782    /*
   783     *  @(#) ti.sysbios; 2, 0, 0, 0,515; 6-15-2011 16:23:48; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   784
   785     */
   786


package ti.sysbios

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     */
    35
    36    requires ti.sysbios.family;
    37
    38    /*!
    39     *  ======== ti.sysbios ========
    40     *  SYS/BIOS Scalable/Extensible Real-time Kernel
    41     *
    42     *  SYS/BIOS is a scalable real-time kernel. It is designed to be used
    43     *  by applications that require real-time scheduling and synchronization
    44     *  or real-time instrumentation. SYS/BIOS provides preemptive
    45     *  multi-threading, hardware abstraction, real-time analysis, and
    46     *  configuration tools. SYS/BIOS is designed to minimize memory and
    47     *  CPU requirements on the target.
    48     *
    49     *  This package contains the {@link ti.sysbios.BIOS BIOS} module, which
    50     *  serves as the "top level" configuration entry point for SYS/BIOS.  The
    51     *  BIOS module provides basic configuration parameters necessary to use
    52     *  SYS/BIOS and provides links to more advanced configuration options that
    53     *  can be used to further optimize SYS/BIOS for your application.
    54     *
    55     *  SYS/BIOS is implemented as a set of RTSC packages, each of which
    56     *  delivers a subset of the functionality. The RTSC standard recommends
    57     *  a naming convention for packages to aid readability and uniqueness.
    58     *  If you are familiar with the Java package naming convention,
    59     *  you will find SYS/BIOS's packages to be quite similar.
    60     *
    61     *  SYS/BIOS packages conform to this convention with names that consist
    62     *  of a hierarchical naming pattern; each level is separated by a period
    63     *  ("."). Usually, the highest level of the name is the vendor ("ti"),
    64     *  followed by the product ("sysbios"), and then followed by the module
    65     *  and submodule names (for example, "knl").
    66     *
    67     *  These names have the added benefit of reflecting the physical layout
    68     *  of the package within the file system where SYS/BIOS has been installed.
    69     *  For example, the {@link ti.sysbios.knl} package files can be found at
    70     *  `BIOS_INSTALL_DIR/bios_6_3#_##/packages/ti/sysbios/knl`.
    71     *
    72     *  For more information about SYS/BIOS, see the following:
    73     *
    74     *  @p(html)
    75     *  <ul>
    76     *  <li><a
    77     *  href=http://processors.wiki.ti.com/index.php/SYS/BIOS_Getting_Started_Guide>
    78     *  <i>SYS/BIOS Getting Started Guide</i></a></li>
    79     *  <li><a href=http://www-s.ti.com/sc/techlit/spruex3>
    80     *  <i>SYS/BIOS 6.x User's Guide</i></a></li>
    81     *  <li><a href=http://www-s.ti.com/sc/techlit/spraas7>
    82     *  <i>Migrating a DSP/BIOS 5 Application to SYS/BIOS 6</i></a></li>
    83     *  <li><a href=http://rtsc.eclipse.org/docs-tip/Main_Page>
    84     *  RTSC-pedia wiki</a></li>
    85     *  <li><a href=http://processors.wiki.ti.com/index.php/Category:SYSBIOS>
    86     *  SYS/BIOS Information Wiki</a></li>
    87     *  <li><a href=http://focus.ti.com/docs/toolsw/folders/print/dspbios6.html>
    88     *  SYS/BIOS 6.x Product Information</a></li>
    89     *  <li><a href=http://e2e.ti.com/support/embedded/f/355.aspx>
    90     *  SYS/BIOS forum in TI E2E Community</a></li>
    91     *  </ul>
    92     *  @p
    93     *
    94     */
    95    package ti.sysbios [2,0,0,0] {
    96        module BIOS;
    97    }
    98    /*
    99     *  @(#) ti.sysbios; 2, 0, 0, 0,515; 6-15-2011 16:23:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   100
   101     */
   102


package ti.sysbios.benchmarks

     1    /*
     2     *  Copyright 2011 by Texas Instruments Incorporated.
     3     *
     4     */
     5
     6    /*
     7     *  ======== package.xdc ========
     8     *
     9     */
    10
    11    /*!
    12     *  ======== ti.sysbios.benchmarks ========
    13     *  BIOS 6 size and timing benchmarks.
    14     *  @p(html)
    15     *  See <a href="./doc-files/Results.html">Results.html</a> for results.
    16     *  @p
    17     *  Refer to the BIOS User's Guide Appendix for a complete description of the
    18     *  benchmarks.
    19     */
    20    package ti.sysbios.benchmarks [1,1,0,0] {
    21    }
    22    /*
    23     *  @(#) ti.sysbios.benchmarks; 1, 1, 0, 0,46; 5-13-2011 16:19:37; /db/vtree/library/trees/avalabench/avalabench-b09x/src/ xlibrary
    24
    25     */
    26


DSP/BIOS Benchmarks

Benchmark Timing Results

Chip Type | Board | Model/Endian
C64x+ | 64x+ Functional Simulator | Little Endian
C674x | 674x Functional Simulator | Little Endian
C66 | TCI6616 Functional Simulator | Little Endian
C64T | 64T Functional Simulator | Little Endian
A8F | evmDM8168 | Little Endian
Arm9 | Arm9 Simulator | Little Endian
M3 | Stellaris LM3S8962 | Little Endian
MSP430 | exp430F5438 | Little Endian
MSP430X | exp430F5438 | Little Endian
MSP430X_small | exp430F5438 | Little Endian
C28L | 28L ezdsp2812 | Little Endian

Benchmark Sizing Results

Chip Type | Model/Endian
C64x+ | Little Endian
C674x | Little Endian
C66x | Little Endian
C64T | Little Endian
A8F | Little Endian
Arm9 | Little Endian
M3 | Little Endian
MSP430 | Little Endian
MSP430X | Little Endian
MSP430X_small | Little Endian
C28L | Little Endian


DSP/BIOS sizes for A8F (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 14744 | 321 | 704 | 15769 | 1024 | 0 | 8 | 18324 | 19356
Hwi application | 14892 | 321 | 720 | 15933 | 1024 | 0 | 8 | 18360 | 19392
Clock application | 19480 | 381 | 1008 | 20869 | 1024 | 0 | 8 | 18840 | 19872
Clock Object application | 19480 | 381 | 1040 | 20901 | 1024 | 0 | 8 | 18872 | 19904
Swi application | 15796 | 341 | 776 | 16913 | 1024 | 0 | 8 | 18452 | 19484
Swi Object application | 15796 | 345 | 816 | 16957 | 1024 | 0 | 8 | 18508 | 19540
Task application | 21464 | 421 | 1192 | 23077 | 1024 | 1024 | 8 | 19076 | 21132
Task Object application | 21464 | 425 | 1240 | 23129 | 1024 | 1536 | 8 | 19152 | 21720
Semaphore application | 22416 | 433 | 1256 | 24105 | 1024 | 1536 | 8 | 19172 | 21740
Semaphore Object application | 22416 | 437 | 1264 | 24117 | 1024 | 1536 | 8 | 19192 | 21760
Default Configuration | 35216 | 6085 | 1472 | 42773 | 4096 | 2048 | 4096 | 21272 | 31512

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 22116 | 521 | 1336 | 23973 | 1024 | 1536 | 4096 | 19224 | 25880
Dynamic Task application | 23928 | 645 | 1320 | 25893 | 1024 | 1536 | 4096 | 19232 | 25888
Dynamic Semaphore application | 24384 | 713 | 1328 | 26425 | 1024 | 1536 | 4096 | 19240 | 25896


DSP/BIOS sizes for Arm9 (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 6540 | 273 | 152 | 6965 | 1024 | 0 | 8 | 1892 | 2924
Hwi application | 6688 | 273 | 176 | 7137 | 1024 | 0 | 8 | 1924 | 2956
Clock application | 9428 | 305 | 296 | 10029 | 1024 | 0 | 8 | 2640 | 3672
Clock Object application | 9428 | 305 | 320 | 10053 | 1024 | 0 | 8 | 2672 | 3704
Swi application | 7516 | 289 | 224 | 8029 | 1024 | 0 | 8 | 2016 | 3048
Swi Object application | 7516 | 293 | 264 | 8073 | 1024 | 0 | 8 | 2072 | 3104
Task application | 11460 | 341 | 488 | 12289 | 1024 | 1024 | 8 | 2876 | 4932
Task Object application | 11460 | 345 | 536 | 12341 | 1024 | 1536 | 8 | 2952 | 5520
Semaphore application | 12372 | 353 | 544 | 13269 | 1024 | 1536 | 8 | 2972 | 5540
Semaphore Object application | 12372 | 357 | 560 | 13289 | 1024 | 1536 | 8 | 2992 | 5560
Default Configuration | 24404 | 5581 | 728 | 30713 | 4096 | 2048 | 4096 | 4584 | 14824

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 12088 | 441 | 600 | 13129 | 1024 | 1536 | 4096 | 3024 | 9680
Dynamic Task application | 13900 | 565 | 608 | 15073 | 1024 | 1536 | 4096 | 3032 | 9688
Dynamic Semaphore application | 14356 | 633 | 616 | 15605 | 1024 | 1536 | 4096 | 3040 | 9696


DSP/BIOS sizes for C2000 (COFF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 4088 | 1666 | 806 | 6560 | 4 | 0 | 0 | 1300 | 1304
Hwi application | 4696 | 1672 | 858 | 7226 | 4 | 0 | 0 | 1300 | 1304
Clock application | 7310 | 1720 | 1300 | 10330 | 4 | 0 | 0 | 1820 | 1824
Clock Object application | 7310 | 1720 | 1332 | 10362 | 4 | 0 | 0 | 1820 | 1824
Swi application | 5310 | 1684 | 956 | 7950 | 4 | 0 | 0 | 1428 | 1432
Swi Object application | 5310 | 1688 | 1004 | 8002 | 4 | 0 | 0 | 1428 | 1432
Task application | 8700 | 1750 | 1538 | 11988 | 4 | 1024 | 0 | 2076 | 3104
Task Object application | 8700 | 1754 | 1610 | 12064 | 4 | 1536 | 0 | 2204 | 3744
Semaphore application | 9190 | 1762 | 1636 | 12588 | 4 | 1536 | 0 | 2204 | 3744
Semaphore Object application | 9190 | 1766 | 1656 | 12612 | 4 | 1536 | 0 | 2204 | 3744
Default Configuration | 22038 | 11540 | 1702 | 35280 | 4 | 512 | 8198 | 5228 | 13942

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 10196 | 1820 | 1706 | 13722 | 4 | 1536 | 4102 | 2204 | 7846
Dynamic Task application | 11684 | 2012 | 1720 | 15416 | 4 | 1536 | 4102 | 2332 | 7974
Dynamic Semaphore application | 11970 | 2076 | 1734 | 15780 | 4 | 1536 | 4102 | 2332 | 7974


DSP/BIOS sizes for C64P (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 9248 | 878 | 116 | 10242 | 1024 | 0 | 8 | 316 | 1348
Hwi application | 10208 | 990 | 136 | 11334 | 1024 | 0 | 8 | 340 | 1372
Clock application | 17472 | 1058 | 444 | 18974 | 1024 | 0 | 8 | 796 | 1828
Clock Object application | 17472 | 1056 | 476 | 19004 | 1024 | 0 | 8 | 828 | 1860
Swi application | 11616 | 1010 | 244 | 12870 | 1024 | 0 | 8 | 440 | 1472
Swi Object application | 11616 | 1014 | 288 | 12918 | 1024 | 0 | 8 | 492 | 1524
Task application | 20192 | 1094 | 680 | 21966 | 1024 | 1024 | 8 | 1036 | 3092
Task Object application | 20192 | 1098 | 732 | 22022 | 1024 | 1536 | 8 | 1116 | 3684
Semaphore application | 21472 | 1106 | 748 | 23326 | 1024 | 1536 | 8 | 1140 | 3708
Semaphore Object application | 21472 | 1110 | 764 | 23346 | 1024 | 1536 | 8 | 1164 | 3732
Default Configuration | 42240 | 6702 | 936 | 49878 | 4096 | 2048 | 4096 | 3268 | 13508

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 22080 | 1250 | 816 | 24146 | 1024 | 1536 | 4096 | 1212 | 7868
Dynamic Task application | 24608 | 1410 | 816 | 26834 | 1024 | 1536 | 4096 | 1212 | 7868
Dynamic Semaphore application | 25216 | 1478 | 828 | 27522 | 1024 | 1536 | 4096 | 1228 | 7884


DSP/BIOS sizes for C64T (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 9280 | 830 | 116 | 10226 | 1024 | 0 | 8 | 308 | 1340
Hwi application | 10080 | 942 | 136 | 11158 | 1024 | 0 | 8 | 332 | 1364
Clock application | 18656 | 1034 | 460 | 20150 | 1024 | 0 | 8 | 792 | 1824
Clock Object application | 18656 | 1034 | 508 | 20198 | 1024 | 0 | 8 | 824 | 1856
Swi application | 11264 | 958 | 228 | 12450 | 1024 | 0 | 8 | 436 | 1468
Swi Object application | 11264 | 962 | 272 | 12498 | 1024 | 0 | 8 | 492 | 1524
Task application | 21184 | 1074 | 688 | 22946 | 1024 | 1024 | 8 | 1032 | 3088
Task Object application | 21184 | 1078 | 744 | 23006 | 1024 | 1536 | 8 | 1112 | 3680
Semaphore application | 22336 | 1086 | 764 | 24186 | 1024 | 1536 | 8 | 1136 | 3704
Semaphore Object application | 22336 | 1090 | 784 | 24210 | 1024 | 1536 | 8 | 1160 | 3728
Default Configuration | 42272 | 6610 | 924 | 49806 | 4096 | 2048 | 4096 | 3260 | 13500

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 23296 | 1230 | 828 | 25354 | 1024 | 1536 | 4096 | 1208 | 7864
Dynamic Task application | 26048 | 1390 | 836 | 28274 | 1024 | 1536 | 4096 | 1216 | 7872
Dynamic Semaphore application | 26720 | 1458 | 840 | 29018 | 1024 | 1536 | 4096 | 1224 | 7880


DSP/BIOS sizes for C66 (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 9184 | 1870 | 132 | 11186 | 1024 | 0 | 8 | 308 | 1340
Hwi application | 10144 | 1982 | 128 | 12254 | 1024 | 0 | 8 | 332 | 1364
Clock application | 17344 | 2050 | 676 | 20070 | 1024 | 0 | 8 | 1068 | 2100
Clock Object application | 17344 | 2050 | 704 | 20098 | 1024 | 0 | 8 | 1100 | 2132
Swi application | 11424 | 2002 | 252 | 13678 | 1024 | 0 | 8 | 436 | 1468
Swi Object application | 11424 | 2006 | 308 | 13738 | 1024 | 0 | 8 | 488 | 1520
Task application | 20096 | 2086 | 864 | 23046 | 1024 | 1024 | 8 | 1308 | 3364
Task Object application | 20096 | 2090 | 912 | 23098 | 1024 | 1536 | 8 | 1388 | 3956
Semaphore application | 21248 | 2098 | 952 | 24298 | 1024 | 1536 | 8 | 1412 | 3980
Semaphore Object application | 21248 | 2102 | 956 | 24306 | 1024 | 1536 | 8 | 1436 | 4004
Default Configuration | 41664 | 7702 | 1172 | 50538 | 4096 | 2048 | 4096 | 3544 | 13784

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 21952 | 2242 | 1016 | 25210 | 1024 | 1536 | 4096 | 1472 | 8128
Dynamic Task application | 24448 | 2402 | 1004 | 27854 | 1024 | 1536 | 4096 | 1484 | 8140
Dynamic Semaphore application | 25056 | 2470 | 1032 | 28558 | 1024 | 1536 | 4096 | 1488 | 8144


DSP/BIOS sizes for C674 (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 9280 | 878 | 116 | 10274 | 1024 | 0 | 8 | 316 | 1348
Hwi application | 10240 | 990 | 136 | 11366 | 1024 | 0 | 8 | 340 | 1372
Clock application | 17536 | 1058 | 440 | 19034 | 1024 | 0 | 8 | 796 | 1828
Clock Object application | 17536 | 1056 | 472 | 19064 | 1024 | 0 | 8 | 828 | 1860
Swi application | 11648 | 1010 | 244 | 12902 | 1024 | 0 | 8 | 436 | 1468
Swi Object application | 11648 | 1014 | 288 | 12950 | 1024 | 0 | 8 | 500 | 1532
Task application | 20288 | 1094 | 668 | 22050 | 1024 | 1024 | 8 | 1036 | 3092
Task Object application | 20288 | 1098 | 724 | 22110 | 1024 | 1536 | 8 | 1116 | 3684
Semaphore application | 21568 | 1106 | 740 | 23414 | 1024 | 1536 | 8 | 1140 | 3708
Semaphore Object application | 21568 | 1110 | 760 | 23438 | 1024 | 1536 | 8 | 1164 | 3732
Default Configuration | 42304 | 6702 | 932 | 49938 | 4096 | 2048 | 4096 | 3268 | 13508

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 22144 | 1250 | 804 | 24198 | 1024 | 1536 | 4096 | 1212 | 7868
Dynamic Task application | 24672 | 1410 | 816 | 26898 | 1024 | 1536 | 4096 | 1220 | 7876
Dynamic Semaphore application | 25280 | 1478 | 824 | 27582 | 1024 | 1536 | 4096 | 1228 | 7884


DSP/BIOS sizes for M3 (ELF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 4976 | 297 | 464 | 5737 | 1024 | 0 | 8 | 968 | 2000
Hwi application | 5068 | 297 | 488 | 5853 | 1024 | 0 | 8 | 1000 | 2032
Clock application | 6796 | 361 | 768 | 7925 | 1024 | 0 | 8 | 1428 | 2460
Clock Object application | 6796 | 361 | 800 | 7957 | 1024 | 0 | 8 | 1460 | 2492
Swi application | 5662 | 317 | 544 | 6523 | 1024 | 0 | 8 | 1092 | 2124
Swi Object application | 5662 | 321 | 576 | 6559 | 1024 | 0 | 8 | 1148 | 2180
Task application | 8096 | 397 | 952 | 9445 | 1024 | 1024 | 8 | 1664 | 3720
Task Object application | 8096 | 401 | 1000 | 9497 | 1024 | 1536 | 8 | 1740 | 4308
Semaphore application | 8778 | 409 | 1016 | 10203 | 1024 | 1536 | 8 | 1760 | 4328
Semaphore Object application | 8778 | 413 | 1032 | 10223 | 1024 | 1536 | 8 | 1780 | 4348
Default Configuration | 16530 | 5997 | 1184 | 23711 | 4096 | 2048 | 4096 | 3788 | 14028

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 8594 | 497 | 1072 | 10163 | 1024 | 1536 | 4096 | 1812 | 8468
Dynamic Task application | 9708 | 621 | 1080 | 11409 | 1024 | 1536 | 4096 | 1820 | 8476
Dynamic Semaphore application | 10004 | 689 | 1088 | 11781 | 1024 | 1536 | 4096 | 1828 | 8484


DSP/BIOS sizes for MSP430 (COFF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 2604 | 802 | 146 | 3552 | 512 | 0 | 0 | 282 | 794
Hwi application | 2768 | 804 | 166 | 3738 | 512 | 0 | 0 | 294 | 806
Clock application | 5110 | 868 | 408 | 6386 | 512 | 0 | 0 | 488 | 1000
Clock Object application | 5110 | 868 | 430 | 6408 | 512 | 0 | 0 | 510 | 1022
Swi application | 3674 | 844 | 224 | 4742 | 512 | 0 | 0 | 340 | 852
Swi Object application | 3674 | 846 | 252 | 4772 | 512 | 0 | 0 | 368 | 880
Task application | 6660 | 884 | 544 | 8088 | 512 | 1024 | 0 | 612 | 2148
Task Object application | 6660 | 886 | 582 | 8128 | 512 | 1536 | 0 | 650 | 2698
Semaphore application | 7406 | 890 | 598 | 8894 | 512 | 1536 | 0 | 662 | 2710
Semaphore Object application | 7406 | 892 | 610 | 8908 | 512 | 1536 | 0 | 674 | 2722
Default Configuration | 17208 | 6412 | 668 | 24288 | 4096 | 512 | 4096 | 2146 | 10850

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 8206 | 946 | 638 | 9790 | 512 | 1536 | 4096 | 698 | 6842
Dynamic Task application | 9624 | 1054 | 646 | 11324 | 512 | 1536 | 4096 | 702 | 6846
Dynamic Semaphore application | 9928 | 1088 | 654 | 11670 | 512 | 1536 | 4096 | 706 | 6850


DSP/BIOS sizes for MSP430X (COFF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 2944 | 870 | 224 | 4038 | 512 | 0 | 0 | 528 | 1040
Hwi application | 3136 | 874 | 258 | 4268 | 512 | 0 | 0 | 550 | 1062
Clock application | 5708 | 950 | 618 | 7276 | 512 | 0 | 0 | 838 | 1350
Clock Object application | 5708 | 950 | 648 | 7306 | 512 | 0 | 0 | 868 | 1380
Swi application | 4066 | 918 | 352 | 5336 | 512 | 0 | 0 | 626 | 1138
Swi Object application | 4066 | 922 | 398 | 5386 | 512 | 0 | 0 | 672 | 1184
Task application | 7452 | 972 | 842 | 9266 | 512 | 1024 | 0 | 1044 | 2580
Task Object application | 7452 | 976 | 908 | 9336 | 512 | 1536 | 0 | 1110 | 3158
Semaphore application | 8336 | 982 | 932 | 10250 | 512 | 1536 | 0 | 1128 | 3176
Semaphore Object application | 8336 | 986 | 950 | 10272 | 512 | 1536 | 0 | 1146 | 3194
Default Configuration | 20304 | 6702 | 1112 | 28118 | 4096 | 512 | 4096 | 2706 | 11410

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 9420 | 1064 | 998 | 11482 | 512 | 1536 | 4096 | 1188 | 7332
Dynamic Task application | 11004 | 1202 | 1012 | 13218 | 512 | 1536 | 4096 | 1196 | 7340
Dynamic Semaphore application | 11376 | 1254 | 1026 | 13656 | 512 | 1536 | 4096 | 1204 | 7348


DSP/BIOS sizes for MSP430X_small (COFF)

(all sizes are in 8-bit bytes)

Static Module Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Kernel Only | 2524 | 802 | 146 | 3472 | 512 | 0 | 0 | 282 | 794
Hwi application | 2662 | 804 | 166 | 3632 | 512 | 0 | 0 | 294 | 806
Clock application | 4844 | 868 | 408 | 6120 | 512 | 0 | 0 | 488 | 1000
Clock Object application | 4844 | 868 | 430 | 6142 | 512 | 0 | 0 | 510 | 1022
Swi application | 3466 | 844 | 224 | 4534 | 512 | 0 | 0 | 340 | 852
Swi Object application | 3466 | 846 | 252 | 4564 | 512 | 0 | 0 | 368 | 880
Task application | 6354 | 884 | 544 | 7782 | 512 | 1024 | 0 | 612 | 2148
Task Object application | 6354 | 886 | 582 | 7822 | 512 | 1536 | 0 | 650 | 2698
Semaphore application | 7094 | 890 | 598 | 8582 | 512 | 1536 | 0 | 662 | 2710
Semaphore Object application | 7094 | 892 | 610 | 8596 | 512 | 1536 | 0 | 674 | 2722
Default Configuration | 16766 | 6412 | 668 | 23846 | 4096 | 512 | 4096 | 2146 | 10850

Dynamic Applications

 |  |  | ROM |  |  |  | RAM |  |
 | Code | Initialized Data | C-initialization | Total ROM | ISR/C Stack | Task Stacks | Heaps | BSS | Total RAM
Dynamic Memory application | 7864 | 946 | 638 | 9448 | 512 | 1536 | 4096 | 698 | 6842
Dynamic Task application | 9226 | 1054 | 646 | 10926 | 512 | 1536 | 4096 | 702 | 6846
Dynamic Semaphore application | 9528 | 1088 | 654 | 11270 | 512 | 1536 | 4096 | 706 | 6850


A8F

A8F Timing Benchmarks

ti.platforms.evmDM8168

Benchmark | Cycles | (1)
Interrupt latency | 1746
Hwi_enable | 15
Hwi_disable | 22
Hwi dispatcher prolog | 1812
Hwi dispatcher epilog | 758
Hwi dispatcher | 940
Hardware Interrupt to Blocked Task | 1655
Hardware Interrupt to Software Interrupt | 1910
Swi_enable | 497
Swi_disable | 307
Post Software Interrupt Again | 93
Post Software Interrupt without Context Switch | 309
Post Software Interrupt with Context Switch | 291
Create a New Task without Context Switch | 2179
Set a Task Priority without a Context Switch | 688
Task_yield | 860
Post Semaphore, No Waiting Task | 95
Post Semaphore No Task Switch | 348
Post Semaphore with Task Switch | 444
Pend on Semaphore, No Context Switchi | 218
Pend on Semaphore with Task Switch | 362
Clock_getTicks | 13

(1) The benchmark application was built using BIOS.LibType_Custom with the following compiler options: "--neon --endian=little -mv7A8 --abi=eabi -ms --embed_inline_assembly --opt_for_speed=2 --program_level_compile -o3 -g --optimize_with_debug".

Timings were obtained using the evmDM8168 development board.

The A8 core was running at 987MHz, with L1 & L2 caches enabled, and all code & data placed in OCMC0.

Unlike other target benchmarks that are collected using flat memory simulators or hardware with zero wait-state memory and no cache, these A8F numbers are collected on a real board with cache enabled and no-attempt to pre-fill the cache. These numbers are effected by varying amounts of cache filling depending on the dynamics of the cache and the previous function calls.


Arm9

Arm9 Timing Benchmarks

ti.platforms.sim470xx

Benchmark | Cycles | (1)
Interrupt latency | 132
Hwi_enable | 0
Hwi_disable | 3
Hwi dispatcher prolog | 121
Hwi dispatcher epilog | 123
Hwi dispatcher | 242
Hardware Interrupt to Blocked Task | 408
Hardware Interrupt to Software Interrupt | 262
Swi_enable | 68
Swi_disable | 7
Post Software Interrupt Again | 25
Post Software Interrupt without Context Switch | 87
Post Software Interrupt with Context Switch | 149
Create a New Task without Context Switch | 1528
Set a Task Priority without a Context Switch | 180
Task_yield | 175
Post Semaphore, No Waiting Task | 39
Post Semaphore No Task Switch | 163
Post Semaphore with Task Switch | 216
Pend on Semaphore, No Context Switchi | 53
Pend on Semaphore with Task Switch | 204
Clock_getTicks | 6

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-me -mv5e --abi=eabi -ms --embed_inline_assembly --opt_for_speed=2 --program_level_compile -o3".

Timings were obtained using the flat memory model ARM926EJ-S Cycle Accurate Simulator.


C28_large

C28_large Timing Benchmarks

ti.platforms.ezdsp28235

Benchmark | Cycles | (1)
Interrupt latency | 155 | (2)
Hwi_enable | 19
Hwi_disable | 18
Hwi dispatcher prolog | 219
Hwi dispatcher epilog | 158
Hwi dispatcher | 372
Hardware Interrupt to Blocked Task | 625
Hardware Interrupt to Software Interrupt | 455
Swi_enable | 101
Swi_disable | 15
Post Software Interrupt Again | 34
Post Software Interrupt without Context Switch | 142
Post Software Interrupt with Context Switch | 278
Create a New Task without Context Switch | 3114
Set a Task Priority without a Context Switch | 281
Task_yield | 246
Post Semaphore, No Waiting Task | 61
Post Semaphore No Task Switch | 239
Post Semaphore with Task Switch | 306
Pend on Semaphore, No Context Switchi | 60
Pend on Semaphore with Task Switch | 320
Clock_getTicks | 14

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-v28 -DLARGE_MODEL=1 -ml -mo --program_level_compile -o3".

Timings were obtained using the ezdsp28335 development board.

(2) The C28x targets also supports zero latency interrupts. See ti.sysbios.family.c28.Hwi cdocs for details.


C64P

C64P Timing Benchmarks

ti.platforms.simDA830

Benchmark | Cycles | (1)
Interrupt latency | 91
Hwi_enable | 1
Hwi_disable | 1
Hwi dispatcher prolog | 109
Hwi dispatcher epilog | 113
Hwi dispatcher | 220
Hardware Interrupt to Blocked Task | 386
Hardware Interrupt to Software Interrupt | 228
Swi_enable | 56
Swi_disable | 14
Post Software Interrupt Again | 42
Post Software Interrupt without Context Switch | 84
Post Software Interrupt with Context Switch | 143
Create a New Task without Context Switch | 1382
Set a Task Priority without a Context Switch | 196
Task_yield | 174
Post Semaphore, No Waiting Task | 52
Post Semaphore No Task Switch | 170
Post Semaphore with Task Switch | 222
Pend on Semaphore, No Context Switchi | 45
Pend on Semaphore with Task Switch | 195
Clock_getTicks | 12

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-mv64p -mi10 -mo -pdr -pden -pds=238 -pds=880 -pds1110 --embed_inline_assembly --program_level_compile -o3".

Timings were obtained using the flat memory model DA830 functional simulator (which can run 64x+ code).


C64T

C64T Timing Benchmarks

ti.platforms.simTesla

Benchmark | Cycles | (1)
Interrupt latency | 127
Hwi_enable | 1
Hwi_disable | 1
Hwi dispatcher prolog | 142
Hwi dispatcher epilog | 221
Hwi dispatcher | 360
Hardware Interrupt to Blocked Task | 530
Hardware Interrupt to Software Interrupt | 342
Swi_enable | 62
Swi_disable | 13
Post Software Interrupt Again | 45
Post Software Interrupt without Context Switch | 92
Post Software Interrupt with Context Switch | 155
Create a New Task without Context Switch | 1629
Set a Task Priority without a Context Switch | 207
Task_yield | 189
Post Semaphore, No Waiting Task | 55
Post Semaphore No Task Switch | 178
Post Semaphore with Task Switch | 244
Pend on Semaphore, No Context Switchi | 53
Pend on Semaphore with Task Switch | 213
Clock_getTicks | 13

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-mv=tesla --abi=eabi -mi10 -mo -pdr -pden -pds=238 -pds=880 -pds1110 --embed_inline_assembly --program_level_compile -o3".

Timings were obtained using the flat memory model OMAP4 Tesla Megamodule Functional Simulator


C66

C66 Timing Benchmarks

ti.platforms.simTCI6616

Benchmark | Cycles | (1)
Interrupt latency | 90
Hwi_enable | 1
Hwi_disable | 1
Hwi dispatcher prolog | 108
Hwi dispatcher epilog | 111
Hwi dispatcher | 216
Hardware Interrupt to Blocked Task | 383
Hardware Interrupt to Software Interrupt | 227
Swi_enable | 56
Swi_disable | 13
Post Software Interrupt Again | 42
Post Software Interrupt without Context Switch | 84
Post Software Interrupt with Context Switch | 143
Create a New Task without Context Switch | 1368
Set a Task Priority without a Context Switch | 193
Task_yield | 172
Post Semaphore, No Waiting Task | 50
Post Semaphore No Task Switch | 170
Post Semaphore with Task Switch | 220
Pend on Semaphore, No Context Switchi | 44
Pend on Semaphore with Task Switch | 193
Clock_getTicks | 12

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-mv6600 --abi=eabi -mi10 -mo -pdr -pden -pds=238 -pds=880 -pds1110 --embed_inline_assembly --program_level_compile -o3".

Timings were obtained using the flat memory model TCI6616 functional simulator.


C674

C674 Timing Benchmarks

ti.platforms.simDA830

Benchmark | Cycles | (1)
Interrupt latency | 91
Hwi_enable | 1
Hwi_disable | 1
Hwi dispatcher prolog | 109
Hwi dispatcher epilog | 113
Hwi dispatcher | 220
Hardware Interrupt to Blocked Task | 386
Hardware Interrupt to Software Interrupt | 228
Swi_enable | 56
Swi_disable | 14
Post Software Interrupt Again | 42
Post Software Interrupt without Context Switch | 84
Post Software Interrupt with Context Switch | 143
Create a New Task without Context Switch | 1376
Set a Task Priority without a Context Switch | 196
Task_yield | 174
Post Semaphore, No Waiting Task | 51
Post Semaphore No Task Switch | 170
Post Semaphore with Task Switch | 222
Pend on Semaphore, No Context Switchi | 45
Pend on Semaphore with Task Switch | 195
Clock_getTicks | 12

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-mv6740 -mi10 -mo -pdr -pden -pds=238 -pds=880 -pds1110 --embed_inline_assembly --program_level_compile -o3".

Timings were obtained using the flat memory model DA830 functional simulator.


M3

M3 Timing Benchmarks

ti.platforms.evmLM3S8962

Benchmark | Cycles | (1)
Interrupt latency | 91 | (2)
Hwi_enable | 1
Hwi_disable | 6
Hwi dispatcher prolog | 88
Hwi dispatcher epilog | 163
Hwi dispatcher | 243
Hardware Interrupt to Blocked Task | 388
Hardware Interrupt to Software Interrupt | 276
Swi_enable | 59
Swi_disable | 12
Post Software Interrupt Again | 30
Post Software Interrupt without Context Switch | 99
Post Software Interrupt with Context Switch | 158
Create a New Task without Context Switch | 1546
Set a Task Priority without a Context Switch | 171
Task_yield | 162
Post Semaphore, No Waiting Task | 46
Post Semaphore No Task Switch | 146
Post Semaphore with Task Switch | 193
Pend on Semaphore, No Context Switchi | 55
Pend on Semaphore with Task Switch | 203
Clock_getTicks | 10

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "--endian=little -mv7M3 --abi=eabi -ms --embed_inline_assembly --opt_for_speed=2 --program_level_compile -o3".

Timings were obtained using the Stellaris evmLM3S8962 board running at 80MHz.

(2) The M3 target also supports zero latency interrupts. See ti.sysbios.family.arm.m3.Hwi cdocs for details.


MSP430

MSP430 Timing Benchmarks

ti.platforms.exp430F5438

Benchmark | Cycles | (1)
Interrupt latency | 88
Hwi_enable | 2
Hwi_disable | 3
Hwi dispatcher prolog | 94
Hwi dispatcher epilog | 102
Hwi dispatcher | 187
Hardware Interrupt to Blocked Task | 454
Hardware Interrupt to Software Interrupt | 302
Swi_enable | 61
Swi_disable | 18
Post Software Interrupt Again | 32
Post Software Interrupt without Context Switch | 145
Post Software Interrupt with Context Switch | 261
Create a New Task without Context Switch | 2492
Set a Task Priority without a Context Switch | 256
Task_yield | 244
Post Semaphore, No Waiting Task | 55
Post Semaphore No Task Switch | 206
Post Semaphore with Task Switch | 307
Pend on Semaphore, No Context Switch | 83
Pend on Semaphore with Task Switch | 304
Clock_getTicks | 50

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-vmsp --program_level_compile -o3".

Timings were obtained using the expMSP4305438 board.


MSP430X

MSP430X Timing Benchmarks

ti.platforms.exp430F5438

Benchmark | Cycles | (1)
Interrupt latency | 97
Hwi_enable | 2
Hwi_disable | 3
Hwi dispatcher prolog | 108
Hwi dispatcher epilog | 127
Hwi dispatcher | 223
Hardware Interrupt to Blocked Task | 561
Hardware Interrupt to Software Interrupt | 372
Swi_enable | 69
Swi_disable | 22
Post Software Interrupt Again | 39
Post Software Interrupt without Context Switch | 181
Post Software Interrupt with Context Switch | 345
Create a New Task without Context Switch | 3618
Set a Task Priority without a Context Switch | 315
Task_yield | 307
Post Semaphore, No Waiting Task | 69
Post Semaphore No Task Switch | 255
Post Semaphore with Task Switch | 383
Pend on Semaphore, No Context Switch | 99
Pend on Semaphore with Task Switch | 387
Clock_getTicks | 61

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-vmspx --near_data=none --code_model=large --data_model=restricted --program_level_compile -o3".

Timings were obtained using the expMSP4305438 board.


MSP430X_small

MSP430X_small Timing Benchmarks

ti.platforms.exp430F5438

Benchmark | Cycles | (1)
Interrupt latency | 71
Hwi_enable | 2
Hwi_disable | 3
Hwi dispatcher prolog | 78
Hwi dispatcher epilog | 98
Hwi dispatcher | 167
Hardware Interrupt to Blocked Task | 434
Hardware Interrupt to Software Interrupt | 283
Swi_enable | 61
Swi_disable | 18
Post Software Interrupt Again | 34
Post Software Interrupt without Context Switch | 138
Post Software Interrupt with Context Switch | 251
Create a New Task without Context Switch | 2347
Set a Task Priority without a Context Switch | 240
Task_yield | 245
Post Semaphore, No Waiting Task | 55
Post Semaphore No Task Switch | 203
Post Semaphore with Task Switch | 301
Pend on Semaphore, No Context Switch | 76
Pend on Semaphore with Task Switch | 301
Clock_getTicks | 52

(1) The benchmark application was built using BIOS.LibType_Custom with the following BIOS.customCCOpts settings: "-vmspx --code_model=small --data_model=small --program_level_compile -o3".

Timings were obtained using the expMSP4305438 board.


package ti.sysbios.family

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family ========
    40     *  Contains family-specific modules for SYS/BIOS
    41     *
    42     *  The ti.sysbios.family package contains family-specific implementations
    43     *  of modules in the Hardware Abstraction Layer
    44     *  ({@link ti.sysbios.hal HAL}) package.
    45     *
    46     *  The SYS/BIOS ti.sysbios.hal
    47     *  package requires target/device-specific API
    48     *  implementations to achieve their functionality. To provide a common set
    49     *  of APIs for these modules across all supported families/devices, SYS/BIOS
    50     *  uses the RTSC proxy-delegate module mechanism. That is, the HAL
    51     *  modules serve as a proxies for a corresponding
    52     *  family-specific module implementation.
    53     *
    54     *  The generic HAL APIs are designed to cover the great majority of use
    55     *  cases. If you are concerned with easy portability between
    56     *  different TI devices, you should use the generic HAL APIs as much
    57     *  as possible. However, if the generic APIs cannot enable use of a
    58     *  device-specific hardware feature that is advantageous to the software
    59     *  application, you may choose to use the target/device-specific APIs.
    60     *
    61     *  During the configuration step of the application build, the
    62     *  modules in the ti.sysbios.hal package locate and bind
    63     *  themselves to appropriate delegate module implementations based on the
    64     *  current target
    65     *  and platform specified in your config.bld file. The delegate binding
    66     *  process is done internally.
    67     *
    68     *  For example, if your config.bld file specifies that one of your build
    69     *  targets is the C64P family, the {@link ti.sysbios.hal.Hwi} knows to
    70     *  bind itself to the {@link ti.sysbios.family.c64p.Hwi} implementation.
    71     *
    72     *  The {@link ./doc-files/delegates.html SYS/BIOS Delegates Usage} page
    73     *  lists the delegates available for every target and platform.
    74     *
    75     */
    76    package ti.sysbios.family [2,0,0,0] {
    77        module Settings;
    78    }
    79
    80    /*
    81     *  @(#) ti.sysbios.family; 2, 0, 0, 0,360; 6-15-2011 16:23:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    82
    83     */
    84


module ti.sysbios.family.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Select the device-specific family modules
    41     *
    42     *  This module selects target-specific implementation modules required by the
    43     *  various SYS/BIOS packages.  These modules are mainted in "family" packages
    44     *  which may also contain modules that are specific to a particular family;
    45     *  for example, cache or power management modules.
    46     */
    47
    48    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    49    {
    50        /*!
    51         *  ======== familyConfigPage ========
    52         *  GUI Config layout page
    53         *
    54         *  This config parameter is the name of the GUI config layout page
    55         *  for the family-specific SYS/BIOS modules.  It is a path relative
    56         *  to the ti.sysbios package base directory, _not_ relative to this
    57         *  package's base.
    58         *
    59         *  @_nodoc
    60         */
    61        config String familyConfigPage = "family/defaultConfig.xml";
    62
    63        /*!
    64         *  ======== bootModule ========
    65         *  Device-specific Boot module
    66         *
    67         *  This parameter is used by the BIOS Overview Grace page to provide a
    68         *  link to the device-specific Boot module.
    69         *
    70         *  @_nodoc
    71         */
    72        config String bootModule;
    73
    74        /*!
    75         *  ======== hwiDelegate ========
    76         *  Device-specific Hwi support services
    77         *
    78         *  This parameter is used by the BIOS Overview Grace page to provide a
    79         *  link to the device-specific module.
    80         *
    81         *  @_nodoc
    82         */
    83        config String hwiDelegate;
    84
    85        /*!
    86         *  ======== timerDelegate ========
    87         *  Device-specific Timer support services
    88         *
    89         *  This parameter is used by the BIOS Overview Grace page to provide a
    90         *  link to the device-specific module.
    91         *
    92         *  @_nodoc
    93         */
    94        config String timerDelegate;
    95
    96        /*!
    97         *  ======== timestampDelegate ========
    98         *  Device-specific Timestamp support services
    99         *
   100         *  This parameter is used by the BIOS Overview Grace page to provide a
   101         *  link to the device-specific module.
   102         *
   103         *  @_nodoc
   104         */
   105        config String timestampDelegate;
   106
   107        /*!
   108         *  ======== familyName ========
   109         *  Name of the SYS/BIOS family package
   110         *
   111         *  @_nodoc
   112         */
   113        config String familyName;
   114
   115        /*!
   116         *  ======== getFamilyName ========
   117         *  Get SYS/BIOS device family name
   118         */
   119        String getFamilyName();
   120    }
   121    /*
   122     *  @(#) ti.sysbios.family; 2, 0, 0, 0,360; 6-15-2011 16:23:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   123
   124     */
   125


package ti.sysbios.family.arm

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm ========
    40     *  Contains specifications for the ARM family-specific SYS/BIOS functions.
    41     *
    42     *  The link below provides SYS/BIOS ARMx register usage information:
    43     *
    44     *      {@link ./doc-files/armregconv.html SYS/BIOS ARM Register Usage}
    45     *
    46     */
    47    package ti.sysbios.family.arm [2,0,0,0] {
    48        module HwiCommon;
    49        module IntrinsicsSupport;
    50        module Settings;
    51        module TaskSupport;
    52    }
    53    /*
    54     *  @(#) ti.sysbios.family.arm; 2, 0, 0, 0,238; 6-15-2011 16:23:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    55
    56     */
    57


module ti.sysbios.family.arm.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  ARM9 target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.arm; 2, 0, 0, 0,238; 6-15-2011 16:23:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.arm.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  ARM9 Task Support Module.
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*! default Task stack size. */
    46        override readonly config SizeT defaultStackSize = 2048;
    47
    48        /*! required stack alignment (in MAUs). */
    49        override readonly config UInt stackAlignment = 8;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arm; 2, 0, 0, 0,238; 6-15-2011 16:23:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.arm.a8.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.a8;
    38
    39    /*!
    40     *  ======== Cache ========
    41     *  ARM Cache Module
    42     *
    43     *  This module manages the data and instruction caches on Cortex A8
    44     *  processors.
    45     *  It provides a list of functions that perform cache operations.  The
    46     *  functions operate on a per cache line except for the 'All' functions
    47     *  which operate on the entire cache specified.  Any Address that is not
    48     *  aligned to a cache line gets rounded down to the address of
    49     *  the nearest cache line.
    50     *
    51     *  The L1 data and program caches as well as the L2 cache are enabled
    52     *  by default early during the startup sequence (prior to any
    53     *  Module_startup()s).
    54     *  Data caching requires the MMU to be enabled and the cacheable
    55     *  attribute of the section/page descriptor for a corresponding
    56     *  memory region to be enabled.
    57     *  Program caching does not require the MMU to be enabled and therefore
    58     *  occurs when the L1 program cache is enabled.
    59     *
    60     *  Note: See the {@link ti.sysbios.family.arm.a8.Mmu} module for
    61     *        information about the MMU.
    62     *
    63     *  Unconstrained Functions
    64     *  All functions
    65     *
    66     *  @p(html)
    67     *  <h3> Calling Context </h3>
    68     *  <table border="1" cellpadding="3">
    69     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    70     *    </colgroup>
    71     *
    72     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    73     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    74     *    <!--                               -->
    75     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td> {@link #invL1dAll}   </td><td>   Y    </td><td>   Y    </td>
    82     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    83     *    <tr><td> {@link #invL1pAll}   </td><td>   Y    </td><td>   Y    </td>
    84     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    85     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td>
    86     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    87     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td>
    88     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    89     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    91     *    <tr><td> {@link #wbInvL1dAll} </td><td>   Y    </td><td>   Y    </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    93     *    <tr><td> {@link #wbL1dAll}    </td><td>   Y    </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td colspan="6"> Definitions: <br />
    96     *       <ul>
    97     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    98     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    99     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   100     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   101     *           <ul>
   102     *             <li> In your module startup after this module is started
   103     *   (e.g. Cache_Module_startupDone() returns TRUE). </li>
   104     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   105     *             <li> During main().</li>
   106     *             <li> During BIOS.startupFxns.</li>
   107     *           </ul>
   108     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   109     *           <ul>
   110     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   111     *             <li> In your module startup before this module is started
   112     *   (e.g. Cache_Module_startupDone() returns FALSE).</li>
   113     *           </ul>
   114     *       </ul>
   115     *    </td></tr>
   116     *
   117     *  </table>
   118     *  @p
   119     */
   120
   121    module Cache inherits ti.sysbios.interfaces.ICache
   122    {
   123        /*!
   124         *  Size of L1 data cache Line
   125         */
   126        const UInt sizeL1dCacheLine = 64;
   127
   128        /*!
   129         *  Size of L1 program cache Line
   130         */
   131        const UInt sizeL1pCacheLine = 64;
   132
   133        /*!
   134         *  Enable L1 and L2 data and program caches.
   135         *
   136         *  To enable a subset of the caches, set this parameter
   137         *  to 'false' and call Cache_enable() within main, passing it only
   138         *  the {@link Cache#Type Cache_Type(s)} to be enabled.
   139         *
   140         *  Data caching requires the MMU and the memory section/page
   141         *  descriptor cacheable attribute to be enabled.
   142         */
   143        config Bool enableCache = true;
   144
   145        /*! @_nodoc
   146         *  ======== getEnabled ========
   147         *  Get the 'type' bitmask of cache(s) enabled.
   148         */
   149        @DirectCall
   150        Bits16 getEnabled();
   151
   152        /*!
   153         *  ======== invL1dAll ========
   154         *  Invalidate all of L1 data cache.
   155         *
   156         *  This function should be used with caution.  In general, the
   157         *  L1 data cache may contain some stack variable or valid data
   158         *  that should not be invalidated.  This function should be used
   159         *  only when all contents of L1 data cache is unwanted.
   160         */
   161        @DirectCall
   162        Void invL1dAll();
   163
   164        /*!
   165         *  ======== invL1pAll ========
   166         *  Invalidate all of L1 program cache.
   167         */
   168        @DirectCall
   169        Void invL1pAll();
   170
   171
   172    internal:
   173
   174        /*!
   175         *  ======== startup ========
   176         *  startup function to enable cache early during climb-up
   177         */
   178        Void startup();
   179
   180        /*!
   181         *  ======== disableL1d ========
   182         *  Disable L1 data cache
   183         *
   184         *  This function performs a write back invalidate all of
   185         *  L1 data cache before it disables the cache.
   186         */
   187        Void disableL1d();
   188
   189        /*!
   190         *  ======== disableL1p ========
   191         *  Disable L1 Program cache
   192         *
   193         *  This function performs an invalidate all of L1 program cache
   194         *  before it disables the cache.
   195         */
   196        Void disableL1p();
   197
   198        /*!
   199         *  ======== disableL2 ========
   200         *  Disable L2 Unified Cache
   201         */
   202        Void disableL2();
   203
   204        /*!
   205         *  ======== enableL1d ========
   206         *  Enable L1 data cache.
   207         */
   208        Void enableL1d();
   209
   210        /*!
   211         *  ======== enableL1p ========
   212         *  Enable L1 program cache.
   213         */
   214        Void enableL1p();
   215
   216        /*!
   217         *  ======== enableL2 ========
   218         *  Enable L2 Unified Cache
   219         */
   220        Void enableL2();
   221
   222        /*!
   223         *  ======== invL1d ========
   224         *  Invalidates range in L1 data cache.
   225         */
   226        Void invL1d(Ptr blockPtr, SizeT byteCnt, Bool wait);
   227
   228        /*!
   229         *  ======== invL1p ========
   230         *  Invalidates range in L1 program cache.
   231         */
   232        Void invL1p(Ptr blockPtr, SizeT byteCnt, Bool wait);
   233
   234    }
   235    /*
   236     *  @(#) ti.sysbios.family.arm.a8; 2, 0, 0, 0,103; 6-15-2011 16:23:46; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   237
   238     */
   239


module ti.sysbios.family.arm.a8.Mmu

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Mmu.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.a8;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    /*!
    43     *  ======== Mmu ========
    44     *  Memory Management Unit Manager.
    45     *
    46     *  This module allows the ARM processor to map a virtual address to a
    47     *  different physical address and enable/disable the MMU.  It does this
    48     *  through a translation table in memory.  The translation table is
    49     *  16KB and manages only the first level descriptor table.  Each entry
    50     *  in the table defines the properties of memory areas of size 1MB.
    51     *  These properties include memory access permissions, cacheability,
    52     *  bufferability, and domain access.
    53     *
    54     *  By default, the MMU translation table is initialized with
    55     *  cache-enabled entries for every memory segment defined in the platform.
    56     *  Cache-disabled entries are also added for the peripheral
    57     *  addresses used by SYS/BIOS (i.e. Timers, Interrupt controller).
    58     *
    59     *  The translation table is placed in
    60     *  an output section called "ti.sysbios.family.arm.a8.mmuTableSection".
    61     *  This section is placed into the platform's default dataMemory and
    62     *  specified to not be initialized via the "NOINIT" type.
    63     *
    64     *  This module does not manage the second level descriptor tables.
    65     *  A 'SECTION' mapped access requires only a first level fetch.  In
    66     *  this case, there is no need for a second level descriptor table.
    67     *  A 'PAGE_TABLE' mapped access requires a second level
    68     *  descriptor table which can be supplied by the user.
    69     *
    70     *  The following is an example of how to place the MMU table
    71     *  and how to enable L1 data caching for the address range
    72     *  0x80000000-0x90000000 in the *.cfg file:
    73     *
    74     *  @p(code)
    75     *
    76     *    var Cache = xdc.useModule('ti.sysbios.family.arm.a8.Cache');
    77     *    var Mmu = xdc.useModule('ti.sysbios.family.arm.a8.Mmu');
    78     *
    79     *    // Enable the cache
    80     *    Cache.enableCache = true;
    81     *
    82     *    // Enable the MMU (Required for L1/L2 data caching)
    83     *    Mmu.enableMMU = true;
    84     *
    85     *    // descriptor attribute structure
    86     *    var attrs = {
    87     *        type: Mmu.FirstLevelDesc_SECTION,  // SECTION descriptor
    88     *        bufferable: true,                  // bufferable
    89     *        cacheable: true,                   // cacheable
    90     *    };
    91     *
    92     *    // Set the descriptor for each entry in the address range
    93     *    for (var i=0x80000000; i < 0x90000000; i = i + 0x00100000) {
    94     *        // Each 'SECTION' descriptor entry spans a 1MB address range
    95     *        Mmu.setFirstLevelDescMeta(i, i, attrs);
    96     *    }
    97     *
    98     *    var memmap = Program.cpu.memoryMap;
    99     *    var DDR = null;
   100     *
   101     *    // Find DDR in memory map
   102     *    for (var i=0; i < memmap.length; i++) {
   103     *        if (memmap[i].name == "DDR") {
   104     *            DDR = memmap[i];
   105     *        }
   106     *    }
   107     *
   108     *    // Place the MMU table in the DDR memory segment if it exists
   109     *    if (DDR != null) {
   110     *        var sectionName = "ti.sysbios.family.arm.a8.mmuTableSection";
   111     *        Program.sectMap[sectionName] = new Program.SectionSpec();
   112     *        Program.sectMap[sectionName].type = "NOINIT";
   113     *        Program.sectMap[sectionName].loadSegment = "DDR";
   114     *    }
   115     *    else {
   116     *        print("No DDR memory segment was found");
   117     *    }
   118     *
   119     *  @p
   120     *
   121     *  Notes:
   122     *  @p(blist)
   123     *      -The 'Supersection' table descriptor is NOT supported.
   124     *      -The 'not global' page descriptor setting is NOT supported.
   125     *      -The 'non-secure' page descriptor setting is NOT supported.
   126     *      -There are size and alignment requirements on the second
   127     *       level descriptor tables depending on the page size.
   128     *      -See the ARM Architecture Reference Manual for more info.
   129     *  @p
   130     *
   131     */
   132
   133    @Template ("./Mmu.xdt") /* generate function to init MMU page table */
   134    @ModuleStartup          /* call to initTableBuf() in startup */
   135
   136    module Mmu
   137    {
   138        // -------- ROV views --------
   139
   140        /*! @_nodoc */
   141        metaonly struct PageView {
   142            String      Type;
   143            Ptr         AddrVirtual;
   144            Ptr         AddrPhysical;
   145            Ptr         Level2TablePtr;
   146            Bool        Bufferable;
   147            Bool        Cacheable;
   148            Bool        Shareable;
   149            Bool        Noexecute;
   150            String      L1DWritePolicy;
   151            UInt        IMP;
   152            UInt        Domain;
   153            String      Access;
   154        };
   155
   156        @Facet
   157        metaonly config ViewInfo.Instance rovViewInfo =
   158            ViewInfo.create({
   159                viewMap: [
   160                    ['PageView', {
   161                        type: ViewInfo.MODULE_DATA,
   162                        viewInitFxn: 'viewPages',
   163                        structName: 'PageView'
   164                    }]
   165               ]
   166           });
   167
   168       /*! First Level descriptors */
   169        enum FirstLevelDesc {
   170            FirstLevelDesc_FAULT = 0,       /*! Virtual address is unmapped */
   171            FirstLevelDesc_PAGE_TABLE = 1,  /*! Page table addr descriptor  */
   172            FirstLevelDesc_SECTION = 2      /*! Section descriptor          */
   173        };
   174
   175        /*!
   176         *  Structure for setting first level descriptor entries
   177         *
   178         *  If the 'cacheable' attribute is true and 'bufferable' is true,
   179         *  L1 data cache operates as a write-back cache.
   180         *  If 'cacheable' is true but 'bufferable' is false,
   181         *  L1 data cache operates as a write-through cache.
   182         *
   183         *  See the 'Translation Tables' section of the ARM v7 Architecture
   184         *  Reference Manual for more details.
   185         */
   186        struct FirstLevelDescAttrs {
   187            FirstLevelDesc type;    /*! first level descriptor type         */
   188            Bool  bufferable;       /*! is memory section bufferable        */
   189            Bool  cacheable;        /*! is memory section cacheable         */
   190            Bool  shareable;        /*! is memory section shareable         */
   191            Bool  noexecute;        /*! is memory section not executable    */
   192            UInt8 imp;              /*! implementation defined              */
   193            UInt8 domain;           /*! domain access control value 0-15    */
   194            UInt8 accPerm;          /*! access permission bits value 0-3    */
   195        };
   196
   197        /*!
   198         *  ======== A_nullPointer ========
   199         *  Assert raised when a pointer is null
   200         */
   201        config xdc.runtime.Assert.Id A_nullPointer  = {
   202            msg: "A_nullPointer: Pointer is null"
   203        };
   204
   205        /*!
   206         *  ======== A_unknownDescType ========
   207         *  Assert raised when the descriptor type is not recognized.
   208         */
   209        config xdc.runtime.Assert.Id A_unknownDescType =
   210            {msg: "A_unknownDescType: Descriptor type is not recognized"};
   211
   212        /*! default descriptor attributes structure */
   213        config FirstLevelDescAttrs defaultAttrs = {
   214            type: FirstLevelDesc_SECTION,   /* SECTION descriptor           */
   215            bufferable: false,              /* false by default             */
   216            cacheable: false,               /* false by default             */
   217            shareable: false,               /* false by default             */
   218            noexecute: false,               /* false by default             */
   219            imp: 1,                         /* set to 1 for A8 devices      */
   220            domain: 0,                      /* default Domain is 0          */
   221            accPerm: 3,                     /* allow read/write             */
   222        };
   223
   224        /*!
   225         *  ======== enableMMU ========
   226         *  Configuration parameter to enable MMU.
   227         */
   228        config Bool enableMMU = true;
   229
   230        /*!
   231         *  ======== cachePlatformMemory ========
   232         *  Flag to automatically mark platform's code/data/stack memory as
   233         *  cacheable in MMU descriptor table
   234         *
   235         *  By default, all memory regions defined in the platform an
   236         *  application is built with are marked as cacheable.
   237         *
   238         *  @see xdc.bld.Program#platform
   239         *
   240         *  If manual configuration of memory regions is required, set
   241         *  this config parameter to 'false'.
   242         */
   243        metaonly config Bool cachePlatformMemory = true;
   244
   245        /*!
   246         *  ======== setFirstLevelDescMeta ========
   247         *  Statically sets the descriptor for the virtual address.
   248         *
   249         *  The first level table entry for the virtual address is mapped
   250         *  to the physical address with the attributes specified. The
   251         *  descriptor table is effective when the MMU is enabled.
   252         *
   253         *  @param(virtualAddr)  The modified virtual address
   254         *  @param(phyAddr)      The physical address
   255         *  @param(attrs)        Pointer to first level descriptor attribute struct
   256         */
   257        metaonly Void setFirstLevelDescMeta(Ptr virtualAddr, Ptr phyAddr,
   258                                            FirstLevelDescAttrs attrs);
   259
   260        /*! @_nodoc
   261         *  ======== disable ========
   262         *  Disables the MMU.
   263         *
   264         *  If the MMU is already disabled, then simply return.
   265         *  Otherwise this function does the following:
   266         *  If the L1 data cache is enabled, write back invalidate all
   267         *  of L1 data cache.  If the L1 program cache is enabled,
   268         *  invalidate all of L1 program cache. This function does not
   269         *  change the cache L1 data/program settings.
   270         */
   271        @DirectCall
   272        Void disable();
   273
   274        /*!
   275         *  ======== enable ========
   276         *  Enables the MMU.
   277         *
   278         *  If the MMU is already enabled, then simply return.
   279         *  Otherwise this function does the following:
   280         *  If the L1 program cache is enabled, invalidate all of L1
   281         *  program cache.  This function does not change the L1
   282         *  data/program cache settings.
   283         */
   284        @DirectCall
   285        Void enable();
   286
   287        /*!
   288         *  ======== initDescAttrs() ========
   289         *  Initializes the first level descriptor attribute structure
   290         *
   291         *  @param(attrs)      Pointer to first level descriptor attribute struct
   292         */
   293        @DirectCall
   294        Void initDescAttrs(FirstLevelDescAttrs *attrs);
   295
   296        /*!
   297         *  ======== isEnabled ========
   298         *  Determines if the MMU is enabled
   299         */
   300        @DirectCall
   301        Bool isEnabled();
   302
   303        /*!
   304         *  ======== setFirstLevelDesc ========
   305         *  Sets the descriptor for the virtual address.
   306         *
   307         *  The first level table entry for the virtual address is mapped
   308         *  to the physical address with the attributes specified. The
   309         *  descriptor table is effective when the MMU is enabled.
   310         *
   311         *  @param(virtualAddr)  The modified virtual address
   312         *  @param(phyAddr)      The physical address
   313         *  @param(attrs)        Pointer to first level descriptor attribute struct
   314         */
   315        @DirectCall
   316        Void setFirstLevelDesc(Ptr virtualAddr, Ptr phyAddr,
   317                               FirstLevelDescAttrs *attrs);
   318
   319
   320    internal:
   321
   322        /*! static array to hold first level dscriptor table */
   323        metaonly config UInt32 tableBuf[];
   324
   325        /*!
   326         *  ======== enableAsm ========
   327         *  Assembly function to enable the MMU.
   328         */
   329        Void enableAsm();
   330
   331        /*!
   332         *  ======== disableAsm ========
   333         *  Assembly function to disable the MMU.
   334         */
   335        Void disableAsm();
   336
   337        /*! function generated to initialize first level descriptor table */
   338        Void initTableBuf(Module_State *mod);
   339
   340        /*! Module state */
   341        struct Module_State {
   342            UInt32 tableBuf[];      /*! 16KB array for first-level descriptors */
   343        }
   344    }
   345    /*
   346     *  @(#) ti.sysbios.family.arm.a8; 2, 0, 0, 0,103; 6-15-2011 16:23:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   347
   348     */
   349


package ti.sysbios.family.arm.a8

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.a8 ========
    40     *  Contains specifications for the a8 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.a8 [2,0,0,0] {
    43        module Cache;
    44        module Mmu;
    45        module TimestampProvider;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.arm.a8; 2, 0, 0, 0,103; 6-15-2011 16:23:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


module ti.sysbios.family.arm.a8.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.a8;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  A8 TimestampProvider.
    43     *
    44     *  The source of the timestamps for the A8 TimestampProvider is
    45     *  the A8's internal PMC counter which counts CPU cycles.
    46     *
    47     *  As this counter is only 32 bits in length, provision is made
    48     *  in the get64() API to test if an overflow has occurred since
    49     *  the last invocation of get64() and compensate the return value
    50     *  accordingly.
    51     *
    52     *  As it is possible for the 32 bit counter to roll over more
    53     *  than once between successive get64() calls, it is up to the user
    54     *  to call the get64() API often enough to guarantee coherency in
    55     *  successive timestamps. A simple mechanism to do this would be
    56     *  to add a Clock function that simply invokes get64():
    57     *
    58     *  @p(code)
    59     *  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
    60     *  var TimestampProvider = xdc.useModule('ti.sysbios.family.arm.a8.TimestampProvider');
    61     *  var clockParams = new Clock.Params();
    62     *  clockParams.period = 1;     // call every Clock tick
    63     *  Clock.create($externModFxn(TimestampProvider.get64), 1, clockParams);
    64     *  @p
    65     *
    66     *  @p(html)
    67     *  <h3> Calling Context </h3>
    68     *  <table border="1" cellpadding="3">
    69     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    70     *    </colgroup>
    71     *
    72     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    73     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    74     *    <!--                                                              -->
    75     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td colspan="6"> Definitions: <br />
    82     *       <ul>
    83     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    84     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    85     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    86     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    87     *           <ul>
    88     *             <li> In your module startup after this module is started
    89     *    (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    90     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    91     *             <li> During main().</li>
    92     *             <li> During BIOS.startupFxns.</li>
    93     *           </ul>
    94     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    95     *           <ul>
    96     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    97     *             <li> In your module startup before this module is started
    98     *    (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    99     *           </ul>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     */
   106
   107    @ModuleStartup          /* To get Clock Timer Handle */
   108
   109    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
   110    {
   111        /*! @_nodoc */
   112        @XmlDtd
   113        metaonly struct Module_View {
   114        };
   115
   116    internal:   /* not for client use */
   117
   118        UInt32 getCCNT32();
   119        UInt32 getOverflowCCNT();
   120        Void initCCNT();
   121
   122        struct Module_State {
   123            UInt32          upper32Bits;    /* upper 32 bits of counter */
   124        }
   125    }
   126    /*
   127     *  @(#) ti.sysbios.family.arm.a8; 2, 0, 0, 0,103; 6-15-2011 16:23:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   128
   129     */
   130


module ti.sysbios.family.arm.a8.intcps.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm.a8.intcps;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    import xdc.runtime.Diags;
    41    import xdc.runtime.Log;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.BIOS;
    45    import ti.sysbios.interfaces.IHwi;
    46
    47    /*!
    48     *  ======== Hwi ========
    49     *  Hardware Interrupt Support Module.
    50     *
    51     *  This Hwi module provides ARM family-specific implementations of the
    52     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    53     *
    54     *  Additional ARM device-specific APIs are also provided.
    55     *
    56     *  @a(NOTE)
    57     *  In this Hwi module implementation, the instance config parameter value
    58     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    59     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    60     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    61     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    62     *  silently converted to {@link #MaskingOption_SELF}.
    63     *
    64     */
    65
    66    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
    67    @ModuleStartup          /* generates call to Hwi_Module_startup at startup */
    68
    69    module Hwi inherits ti.sysbios.interfaces.IHwi
    70    {
    71
    72        // -------- Module Constants --------
    73
    74        /*! intcps supports 128 interrupts. */
    75        const Int NUM_INTERRUPTS = 128;
    76
    77        // -------- Module Types --------
    78
    79        /*! Hwi vector function type definition. */
    80        typedef Void (*VectorFuncPtr)(void);
    81
    82        /*!
    83         *  ======== BasicView ========
    84         *  @_nodoc
    85         */
    86        metaonly struct BasicView {
    87            Ptr         halHwiHandle;
    88            String      label;
    89            Int         intNum;
    90            UInt        priority;
    91            String      fxn;
    92            UArg        arg;
    93        };
    94
    95        /*!
    96         *  ======== DetailedView ========
    97         *  @_nodoc
    98         */
    99        metaonly struct DetailedView {
   100            Ptr         halHwiHandle;
   101            String      label;
   102            Int         intNum;
   103            UInt        priority;
   104            String      fxn;
   105            UArg        arg;
   106            Ptr         irp;
   107            Bool        enabled;
   108            Bool        pending;
   109        };
   110
   111        /*!
   112         *  ======== ModuleView ========
   113         *  @_nodoc
   114         */
   115        metaonly struct ModuleView {
   116            String      options[4];
   117            UInt        spuriousInterrupts;
   118            UInt        lastSpuriousInterrupt;
   119            SizeT       hwiStackPeak;
   120            SizeT       hwiStackSize;
   121            Ptr         hwiStackBase;
   122        };
   123
   124        /*!
   125         *  ======== rovViewInfo ========
   126         *  @_nodoc
   127         */
   128        @Facet
   129        metaonly config ViewInfo.Instance rovViewInfo =
   130            ViewInfo.create({
   131                viewMap: [
   132                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   133                    ['Detailed', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDetailed', structName: 'DetailedView'}],
   134                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   135                ]
   136            });
   137
   138        /*! Interrupt type. IRQ or FIQ */
   139        enum Type {
   140            Type_IRQ,               /*! IRQ interrupt. */
   141            Type_FIQ                /*! FIQ interrupt. */
   142        };
   143
   144        /*! Interrupt Controller. Symbol "Hwi_intc" is physical device */
   145        struct Intc {
   146            UInt32 REVISION;        /*! 0x00 Config Register */
   147
   148            UInt32 hole0[3];        /*! 0x04-0x0C */
   149
   150            UInt32 SYSCONFIG;       /*! 0x10 Config Register */
   151            UInt32 SYSSTATUS;       /*! 0x14 Status Register */
   152
   153            UInt32 hole1[10];       /*! 0x18-0x3c */
   154
   155            UInt32 SIR_IRQ;         /*! 0x40 Source IRQ Register */
   156            UInt32 SIR_FIQ;         /*! 0x44 Source FIQ Register */
   157            UInt32 CONTROL;         /*! 0x48 Control Register */
   158            UInt32 PROTECTION;      /*! 0x4C Protection Register */
   159            UInt32 IDLE;            /*! 0x50 Idle Register */
   160
   161            UInt32 hole2[3];        /*! 0x54-0x5C */
   162
   163            UInt32 IRQ_PRIORITY;    /*! 0x60 IRQ Priority Register */
   164            UInt32 FIQ_PRIORITY;    /*! 0x64 IRQ Priority Register */
   165            UInt32 THRESHOLD;       /*! 0x68 Threshold Register */
   166
   167            UInt32 hole3[5];        /*! 0x6C-0x7C */
   168
   169            UInt32 ITR0;            /*! 0x80 Interrupt Input Register */
   170            UInt32 MIR0;            /*! 0x84 Mask Interrupt Register */
   171            UInt32 MIR_CLEAR0;      /*! 0x88 MIR Clear Register */
   172            UInt32 MIR_SET0;        /*! 0x8C MIR Set Register */
   173            UInt32 ISR_SET0;        /*! 0x90 Interrupt Set Register */
   174            UInt32 ISR_CLEAR0;      /*! 0x94 Interrupt Clear Register */
   175            UInt32 PENDING_IRQ0;    /*! 0x98 Pending IRQ Register */
   176            UInt32 PENDING_FIQ0;    /*! 0x9C Pending FIQ Register */
   177
   178            UInt32 ITR1;            /*! 0xA0 Interrupt Input Register */
   179            UInt32 MIR1;            /*! 0xA4 Mask Interrupt Register */
   180            UInt32 MIR_CLEAR1;      /*! 0xA8 MIR Clear Register */
   181            UInt32 MIR_SET1;        /*! 0xAC MIR Set Register */
   182            UInt32 ISR_SET1;        /*! 0xB0 Interrupt Set Register */
   183            UInt32 ISR_CLEAR1;      /*! 0xB4 Interrupt Clear Register */
   184            UInt32 PENDING_IRQ1;    /*! 0xB8 Pending IRQ Register */
   185            UInt32 PENDING_FIQ1;    /*! 0xBC Pending FIQ Register */
   186
   187            UInt32 ITR2;            /*! 0xC0 Interrupt Input Register */
   188            UInt32 MIR2;            /*! 0xC4 Mask Interrupt Register */
   189            UInt32 MIR_CLEAR2;      /*! 0xC8 MIR Clear Register */
   190            UInt32 MIR_SET2;        /*! 0xCC MIR Set Register */
   191            UInt32 ISR_SET2;        /*! 0xD0 Interrupt Set Register */
   192            UInt32 ISR_CLEAR2;      /*! 0xD4 Interrupt Clear Register */
   193            UInt32 PENDING_IRQ2;    /*! 0xD8 Pending IRQ Register */
   194            UInt32 PENDING_FIQ2;    /*! 0xDC Pending FIQ Register */
   195
   196            UInt32 ITR3;            /*! 0xE0 Interrupt Input Register */
   197            UInt32 MIR3;            /*! 0xE4 Mask Interrupt Register */
   198            UInt32 MIR_CLEAR3;      /*! 0xE8 MIR Clear Register */
   199            UInt32 MIR_SET3;        /*! 0xEC MIR Set Register */
   200            UInt32 ISR_SET3;        /*! 0xF0 Interrupt Set Register */
   201            UInt32 ISR_CLEAR3;      /*! 0xF4 Interrupt Clear Register */
   202            UInt32 PENDING_IRQ3;    /*! 0xF8 Pending IRQ Register */
   203            UInt32 PENDING_FIQ3;    /*! 0xFC Pending FIQ Register */
   204
   205            UInt32 ILR[128];        /*! 0x100 thru 0x2FC */
   206        };
   207
   208        extern volatile Intc intc;
   209
   210        /*!
   211         *  Exception Context - Register contents at the time of an exception.
   212         */
   213        struct ExcContext {
   214            /* Thread Context */
   215            BIOS.ThreadType threadType; /* Type of thread executing at */
   216                                        /* the time the exception occurred */
   217            Ptr     threadHandle;       /* Handle to thread executing at */
   218                                        /* the time the exception occurred */
   219            Ptr     threadStack;        /* Address of stack contents of thread */
   220                                        /* executing at the time the exception */
   221                                        /* occurred */
   222
   223            /* Internal Registers */
   224            Ptr     r0;
   225            Ptr     r1;
   226            Ptr     r2;
   227            Ptr     r3;
   228            Ptr     r4;
   229            Ptr     r5;
   230            Ptr     r6;
   231            Ptr     r7;
   232            Ptr     r8;
   233            Ptr     r9;
   234            Ptr     r10;
   235            Ptr     r11;
   236            Ptr     r12;
   237            Ptr     sp;
   238            Ptr     lr;
   239            Ptr     pc;
   240            Ptr     psr;
   241        }
   242
   243        // -------- Module Parameters --------
   244
   245        /*! Reset Handler. Default is c_int00 */
   246        metaonly config VectorFuncPtr resetFunc;
   247
   248        /*!
   249         * Undefined instruction exception handler.
   250         * Default is an internal exception handler.
   251         */
   252        metaonly config VectorFuncPtr undefinedInstFunc;
   253
   254        /*!
   255         * SWI Handler. Default is internal SWI handler.
   256         * Default is an internal exception handler.
   257         */
   258        metaonly config VectorFuncPtr swiFunc;
   259
   260        /*!
   261         * Prefetch abort exception handler.
   262         * Default is an internal exception handler.
   263         */
   264        metaonly config VectorFuncPtr prefetchAbortFunc;
   265
   266        /*!
   267         * Data abort exception handler.
   268         * Default is an internal exception handler.
   269         */
   270        metaonly config VectorFuncPtr dataAbortFunc;
   271
   272        /*!
   273         * Reserved exception handler.
   274         * Default is an internal exception handler.
   275         */
   276        metaonly config VectorFuncPtr reservedFunc;
   277
   278        /*! IRQ interrupt handler. Default is internal IRQ dispatcher */
   279        metaonly config VectorFuncPtr irqFunc;
   280
   281        /*! FIQ interrupt handler. Default is internal FIQ dispatcher */
   282        metaonly config VectorFuncPtr fiqFunc;
   283
   284        /*!
   285         *  Enable full exception decoding
   286         *
   287         *  When this is enabled, the exception handler will fully
   288         *  decode an exception and dump the registers to the
   289         *  system console.
   290         */
   291        metaonly config Bool enableException = false;
   292
   293        /*!
   294         *  FIQ stack pointer. Default = null.
   295         *  (Indicates that stack is to be created using
   296         *  staticPlace()
   297         */
   298        config Ptr fiqStack = null;
   299
   300        /*!
   301         * FIQ stack size in MAUs.
   302         * Default is 1024 bytes.
   303         */
   304        metaonly config SizeT fiqStackSize = 1024;
   305
   306        /*!
   307         *  Memory section used for FIQ stack
   308         *  Default is null.
   309         */
   310        metaonly config String fiqStackSection = null;
   311
   312        /*!
   313         *  Exception stack pointer. Default = null.
   314         *  (Indicates that stack is to be created using
   315         *  staticPlace()
   316         */
   317        config Ptr excStack = null;
   318
   319        /*!
   320         * Exception stack size in MAUs.
   321         * Default is 1024 bytes.
   322         */
   323        metaonly config SizeT excStackSize = 1024;
   324
   325        /*!
   326         *  Memory section used for Exception stack
   327         *  Default is null.
   328         */
   329        metaonly config String excStackSection = null;
   330
   331        /*! Initial MIR0 Interrupt Mask. Default is 0xffffffff */
   332        config Bits32 mir0Mask = 0xffffffff;
   333
   334        /*! Initial MIR1 Interrupt Mask. Default is 0xffffffff */
   335        config Bits32 mir1Mask = 0xffffffff;
   336
   337        /*! Initial MIR2 Interrupt Mask. Default is 0xffffffff */
   338        config Bits32 mir2Mask = 0xffffffff;
   339
   340        /*! Initial MIR3 Interrupt Mask. Default is 0xffffffff */
   341        config Bits32 mir3Mask = 0xffffffff;
   342
   343        /*!
   344         *  Error raised when an attempt is made to create a Hwi
   345         *  that has already been created.
   346         */
   347        config Error.Id E_alreadyDefined = {
   348            msg: "E_alreadyDefined: Hwi already defined, intnum: %d"
   349        };
   350
   351        /*!
   352         *  Error raised when an undefined interrupt has fired.
   353         */
   354        config Error.Id E_undefined = {
   355            msg: "E_undefined: Hwi undefined, intnum: %d"
   356        };
   357
   358        /*!
   359         *  Error raised if an attempt is made to create a Hwi
   360         *  with an interrupt number greater than NUM_INTERRUPTS - 1.
   361         */
   362        config Error.Id E_badIntNum = {
   363            msg: "E_badIntNum, intnum: %d is out of range"
   364        };
   365
   366        /*!
   367         *  Error raised when an exception occurs
   368         */
   369        config Error.Id E_excMin = {
   370            msg: "E_exception: pc = 0x%08x, lr = 0x%08x."
   371        };
   372
   373        /*!
   374         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   375         */
   376        config Log.Event LM_begin = {
   377            mask: Diags.USER1 | Diags.USER2,
   378            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   379        };
   380
   381        /*!
   382         *  Issued just after return from Hwi function (with interrupts disabled)
   383         */
   384        config Log.Event LD_end = {
   385            mask: Diags.USER2,
   386            msg: "LD_end: hwi: 0x%x"
   387        };
   388
   389
   390        // -------- Module Functions --------
   391
   392        /*!
   393         *  ======== disable ========
   394         */
   395        @Macro
   396        override UInt disable();
   397
   398        /*!
   399         *  ======== enable ========
   400         */
   401        @Macro
   402        override UInt enable();
   403
   404        /*!
   405         *  ======== restore ========
   406         */
   407        @Macro
   408        override Void restore(UInt key);
   409
   410        /*!
   411         *  ======== inUseMeta ========
   412         *  @_nodoc
   413         *  Check for Hwi already in use.
   414         *  For internal SYS/BIOS use only.
   415         *  Should be called prior to any internal Hwi.create().
   416         *
   417         *  @param(intNum)  interrupt number
   418         */
   419        metaonly Bool inUseMeta(UInt intNum);
   420
   421        /*!
   422         *  ======== getHandle ========
   423         *  Returns Hwi_Handle associated with intNum
   424         *
   425         *  @param(intNum)  interrupt number
   426         */
   427        @DirectCall
   428        Handle getHandle(UInt intNum);
   429
   430        /*!
   431         *  ======== enableFIQ ========
   432         *  Enable FIQ interrupts.
   433         *
   434         *  @b(returns)     previous FIQ interrupt enable/disable state
   435         */
   436        @DirectCall
   437        UInt enableFIQ();
   438
   439        /*!
   440         *  ======== disableFIQ ========
   441         *  Disable FIQ interrupts.
   442         *
   443         *  @b(returns)     previous FIQ interrupt enable/disable state
   444         */
   445        @DirectCall
   446        UInt disableFIQ();
   447
   448        /*!
   449         *  ======== restoreFIQ ========
   450         *  Restore FIQ interrupts.
   451         *
   452         *  @param(key)     enable/disable state to restore
   453         */
   454        @DirectCall
   455        Void restoreFIQ(UInt key);
   456
   457        /*!
   458         *  ======== enableIRQ ========
   459         *  Enable IRQ interrupts.
   460         *
   461         *  @param(key)     enable/disable state to restore
   462         */
   463        @DirectCall
   464        UInt enableIRQ();
   465
   466        /*!
   467         *  ======== disableIRQ ========
   468         *  Disable IRQ interrupts.
   469         *
   470         *  @b(returns)     previous IRQ interrupt enable/disable state
   471         */
   472        @DirectCall
   473        UInt disableIRQ();
   474
   475        /*!
   476         *  ======== restoreIRQ ========
   477         *  Restore IRQ interrupts.
   478         *
   479         *  @param(key)     enable/disable state to restore
   480         */
   481        @DirectCall
   482        Void restoreIRQ(UInt key);
   483
   484        /*!
   485         *  ======== disableMIR0 ========
   486         *  Disable specific interrupts.
   487         *
   488         *  Disables specific interrupts by setting the bits specified by
   489         *  mask in the Mask Interrupts Register (MIR).
   490         *
   491         *  @param(mask)    bitmask of interrupts to disable
   492         *  @b(returns)     previous MIR0 settings bitmask
   493         */
   494        @DirectCall
   495        Bits32 disableMIR0(Bits32 mask);
   496        @DirectCall
   497        Bits32 disableMIR1(Bits32 mask);
   498        @DirectCall
   499        Bits32 disableMIR2(Bits32 mask);
   500        @DirectCall
   501        Bits32 disableMIR3(Bits32 mask);
   502
   503        /*!
   504         *  ======== enableMIR ========
   505         *  Enable specific interrupts.
   506         *
   507         *  Enables specific interrupts by clearing the bits specified by
   508         *  mask in the Mask Interrupts Register (MIR).
   509         *
   510         *  @param(mask)    bitmask of interrupts to enable
   511         *  @b(returns)     previous MIR settings bitmask
   512         */
   513        @DirectCall
   514        Bits32 enableMIR0(Bits32 mask);
   515        @DirectCall
   516        Bits32 enableMIR1(Bits32 mask);
   517        @DirectCall
   518        Bits32 enableMIR2(Bits32 mask);
   519        @DirectCall
   520        Bits32 enableMIR3(Bits32 mask);
   521
   522        /*!
   523         *  ======== restoreMIR0 ========
   524         *  Restore maskable interrupts to the state they were in
   525         *  when either disableMIR0() or enableMIR0() was called.
   526         *
   527         *  Simply writes mask to the MIR register.
   528         *
   529         *  @param(mask)    bitmask of interrupts to restore
   530         *  @b(returns)     previous MIR0 settings bitmask
   531         */
   532        @DirectCall
   533        Bits32 restoreMIR0(Bits32 mask);
   534        @DirectCall
   535        Bits32 restoreMIR1(Bits32 mask);
   536        @DirectCall
   537        Bits32 restoreMIR2(Bits32 mask);
   538        @DirectCall
   539        Bits32 restoreMIR3(Bits32 mask);
   540
   541        /*!
   542         *  ======== setPriority ========
   543         *  Set an interrupt's priority.
   544         *
   545         *  Not an instance function so that it can be used
   546         *  with non-dispatched interrupts.
   547         *
   548         *  @param(intNum)      ID of interrupt
   549         *  @param(priority)    priority
   550         */
   551        @DirectCall
   552        Void setPriority(UInt intNum, UInt priority);
   553
   554        /*!
   555         *  ======== setType ========
   556         *  Set an interrupt's type (FIQ/IRQ).
   557         *
   558         *  Not an instance function so that it can be used
   559         *  with non-dispatched interrupts.
   560         *
   561         *  @param(intNum)      ID of interrupt
   562         *  @param(type)        type = FIQ/IRQ
   563         */
   564        @DirectCall
   565        Void setType(UInt intNum, Type type);
   566
   567    instance:
   568
   569        /*! Interrupt type (IRQ/FIQ. Default is IRQ. */
   570        config Type type = Type_IRQ;
   571
   572        /*
   573         *  Interrupt priority.
   574         *  Valid priorities are 0 - 63. 0 is the highest priority.
   575         *  The default is 63 which is the lowest priority interrupt.
   576         */
   577        override config Int priority = 63;
   578
   579        /*! The interrupt controller is designed for priority based interrupts */
   580        override config IHwi.MaskingOption maskSetting = IHwi.MaskingOption_LOWER;
   581
   582        /*!
   583         *  ======== reconfig ========
   584         *  Reconfigure a dispatched interrupt.
   585         */
   586        @DirectCall
   587        Void reconfig(FuncPtr fxn, const Params *params);
   588
   589    internal:   /* not for client use */
   590
   591        /*
   592         * Swi and Task module function pointers.
   593         * Used to decouple Hwi from Swi and Task when
   594         * dispatcherSwiSupport or
   595         * dispatcherTaskSupport is false.
   596         */
   597        config UInt (*swiDisable)();
   598        config Void (*swiRestoreHwi)(UInt);
   599        config UInt (*taskDisable)();
   600        config Void (*taskRestoreHwi)(UInt);
   601
   602        /* assembly code mode registers setup */
   603        Void init();
   604
   605        /* Interrupt Dispatcher assembly code wrapper */
   606        Void dispatchIRQ();
   607
   608        /* Interrupt Dispatcher C code */
   609        Void dispatchIRQC(Irp irp);
   610
   611        /* default FIQ Interrupt Dispatcher */
   612        Void dispatchFIQC();
   613
   614        /* non plugged interrupt handler */
   615        Void nonPluggedHwiHandler(UArg arg);
   616
   617        /*!
   618         *  const array to hold all HookSet objects.
   619         */
   620        config HookSet hooks[length] = [];
   621
   622        /*! Meta World Only Hwi Configuration Object. */
   623        metaonly struct InterruptObj {
   624            Bool used;              /* Interrupt already defined? */
   625            FuncPtr fxn;            /* Dispatched ISR function */
   626        };
   627
   628        /*!
   629         * Meta-only array of interrupt objects.
   630         * This meta-only array of Hwi config objects is initialized
   631         * in Hwi.xs:module$meta$init().
   632         */
   633        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   634
   635        struct Instance_State {
   636            Type        type;           // Interrupt Type
   637            UInt        priority;       // Interrupt Priority
   638            UArg        arg;            // Argument to Hwi function.
   639            FuncPtr     fxn;            // Hwi function.
   640            Irp         irp;            // current IRP
   641            Ptr         hookEnv[];
   642        };
   643
   644        struct Module_State {
   645            Bits32      mir0Mask;       // Initial MIR0 mask
   646            Bits32      mir1Mask;       // Initial MIR1 mask
   647            Bits32      mir2Mask;       // Initial MIR2 mask
   648            Bits32      mir3Mask;       // Initial MIR2 mask
   649            UInt        spuriousInts;   // Count of spurious interrupts
   650            UInt        lastSpuriousInt;// Most recent spurious interrupt
   651            UInt        irp;            // temporary irp storage for IRQ handler
   652            Char        *taskSP;        // temporary storage of interrupted
   653                                        // Task's SP during ISR execution
   654
   655            Char        *isrStack;      // Points to isrStack address
   656            Ptr         isrStackBase;   // _stack
   657            Ptr         isrStackSize;   // _STACK_SIZE
   658            Char        fiqStack[];     // buffer used for FIQ stack
   659            SizeT       fiqStackSize;
   660            Hwi.Object  nonPluggedHwi;  // default Hwi object
   661            Handle      dispatchTable[NUM_INTERRUPTS];
   662                                        // dispatch table
   663        };
   664    }
   665
   666    /*
   667     *  @(#) ti.sysbios.family.arm.a8.intcps; 2, 0, 0, 0,78; 6-15-2011 16:23:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   668
   669     */
   670


package ti.sysbios.family.arm.a8.intcps

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.a8.intcps ========
    40     *  Contains specifications for the a8 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.a8.intcps [2,0,0,0] {
    43        module Hwi;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.a8.intcps; 2, 0, 0, 0,78; 6-15-2011 16:23:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


package ti.sysbios.family.arm.a8.omap3430

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.a8.omap3430 ========
    40     *  Contains specifications for the a8 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.a8.omap3430 [2,0,0,0] {
    43        module TimerSupport;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.a8.omap3430; 2, 0, 0, 0,94; 6-15-2011 16:23:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


package ti.sysbios.family.arm.a8.sim

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.a8.sim  ========
    40     *  Contains specifications for the a8 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.a8.sim [2,0,0,0] {
    43        module TaskSupport;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.a8.sim; 2, 0, 0, 0,81; 6-15-2011 16:24:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


module ti.sysbios.family.arm.a8.sim.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.a8.sim;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  ARM9 Task Support Module.
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*! default Task stack size. */
    46        override readonly config SizeT defaultStackSize = 2048;
    47
    48        /*! required stack alignment (in MAUs). */
    49        override readonly config UInt stackAlignment = 8;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arm.a8.sim; 2, 0, 0, 0,81; 6-15-2011 16:24:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


package ti.sysbios.family.arm.a8.ti81xx

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.a8.ti81xx ========
    40     *  Contains specifications for the a8 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.a8.ti81xx [2,0,0,0] {
    43        module TimerSupport;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.a8.ti81xx; 2, 0, 0, 0,78; 6-15-2011 16:24:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


module ti.sysbios.family.arm.arm9.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.arm9;
    38
    39    /*!
    40     *  ======== Cache ========
    41     *  ARM Cache Module
    42     *
    43     *  This module manages the data and instruction caches on ARM processors.
    44     *  It provides a list of functions that perform cache operations.  The
    45     *  functions operate on a per cache line except for the 'All' functions
    46     *  which operate on the entire cache specified.  Any Address that is not
    47     *  aligned to a cache line gets rounded down to the address of
    48     *  the nearest cache line.
    49     *
    50     *  The L1 data and program caches are enabled
    51     *  by default early during the startup sequence (prior to any Module_startup()s).
    52     *  Data caching requires the MMU to be enabled and the cacheable
    53     *  attribute of the section/page descriptor for a corresponding
    54     *  memory region to be enabled.
    55     *  Program caching does not require the MMU to be enabled and therefore
    56     *  occurs when the L1 program cache is enabled.
    57     *
    58     *  Note: See the {@link ti.sysbios.family.arm.arm9.Mmu} module for
    59     *        information about the MMU.
    60     *
    61     *  Unconstrained Functions
    62     *  All functions
    63     *
    64     *  @p(html)
    65     *  <h3> Calling Context </h3>
    66     *  <table border="1" cellpadding="3">
    67     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    68     *
    69     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    70     *    <!--                                                                                                                 -->
    71     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #invL1dAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #invL1pAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    76     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    78     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #wbInvL1dAll} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> {@link #wbL1dAll}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td colspan="6"> Definitions: <br />
    82     *       <ul>
    83     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    84     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    85     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    86     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    87     *           <ul>
    88     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    89     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    90     *             <li> During main().</li>
    91     *             <li> During BIOS.startupFxns.</li>
    92     *           </ul>
    93     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    94     *           <ul>
    95     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    96     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       </ul>
    99     *    </td></tr>
   100     *
   101     *  </table>
   102     *  @p
   103     */
   104
   105    module Cache inherits ti.sysbios.interfaces.ICache
   106    {
   107        /*!
   108         *  Size of L1 data cache Line
   109         */
   110        const UInt sizeL1dCacheLine = 32;
   111
   112        /*!
   113         *  Size of L1 program cache Line
   114         */
   115        const UInt sizeL1pCacheLine = 32;
   116
   117        /*!
   118         *  Enable L1 data and program caches.
   119         *
   120         *  To enable a subset of the caches, set this parameter
   121         *  to 'false' and call Cache_enable() within main, passing it only
   122         *  the {@link Cache#Type Cache_Type(s)} to be enabled.
   123         *
   124         *  Data caching requires the MMU and the memory section/page
   125         *  descriptor cacheable attribute to be enabled.
   126         */
   127        config Bool enableCache = true;
   128
   129        /*! @_nodoc
   130         *  ======== getEnabled ========
   131         *  Get the 'type' bitmask of cache(s) enabled.
   132         */
   133        @DirectCall
   134        Bits16 getEnabled();
   135
   136        /*!
   137         *  ======== invL1dAll ========
   138         *  Invalidate all of L1 data cache.
   139         *
   140         *  This function should be used with caution.  In general, the
   141         *  L1 data cache may contain some stack variable or valid data
   142         *  that should not be invalidated.  This function should be used
   143         *  only when all contents of L1 data cache is unwanted.
   144         */
   145        @DirectCall
   146        Void invL1dAll();
   147
   148        /*!
   149         *  ======== invL1pAll ========
   150         *  Invalidate all of L1 program cache.
   151         */
   152        @DirectCall
   153        Void invL1pAll();
   154
   155
   156    internal:
   157
   158        /*!
   159         *  ======== startup ========
   160         *  startup function to enable cache early during climb-up
   161         */
   162        Void startup();
   163
   164        /*!
   165         *  ======== disableL1d ========
   166         *  Disable L1 data cache
   167         *
   168         *  This function performs a write back invalidate all of
   169         *  L1 data cache before it disables the cache.
   170         */
   171        Void disableL1d();
   172
   173        /*!
   174         *  ======== disableL1p ========
   175         *  Disable L1 Program cache
   176         *
   177         *  This function performs an invalidate all of L1 program cache
   178         *  before it disables the cache.
   179         */
   180        Void disableL1p();
   181
   182        /*!
   183         *  ======== enableL1d ========
   184         *  Enable L1 data cache.
   185         */
   186        Void enableL1d();
   187
   188        /*!
   189         *  ======== enableL1p ========
   190         *  Enable L1 program cache.
   191         */
   192        Void enableL1p();
   193
   194        /*!
   195         *  ======== invL1d ========
   196         *  Invalidates range in L1 data cache.
   197         */
   198        Void invL1d(Ptr blockPtr, SizeT byteCnt, Bool wait);
   199
   200        /*!
   201         *  ======== invL1p ========
   202         *  Invalidates range in L1 program cache.
   203         */
   204        Void invL1p(Ptr blockPtr, SizeT byteCnt, Bool wait);
   205
   206    }
   207    /*
   208     *  @(#) ti.sysbios.family.arm.arm9; 2, 0, 0, 0,116; 6-15-2011 16:24:10; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   209
   210     */
   211


module ti.sysbios.family.arm.arm9.Mmu

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Mmu.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.arm9;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    /*!
    43     *  ======== Mmu ========
    44     *  Memory Management Unit Manager.
    45     *
    46     *  This module allows the ARM processor to map a virtual address to a
    47     *  different physical address and enable/disable the MMU.  It does this
    48     *  through a translation table in memory.  The translation table is
    49     *  16KB and manages only the first level descriptor table.  Each entry
    50     *  in the table defines the properties of memory areas of size 1MB.
    51     *  These properties include memory access permissions, cacheability,
    52     *  bufferability, and domain access.
    53     *
    54     *  By default, the MMU translation table contains cache-enabled entries
    55     *  for every memory segment from the platform.
    56     *  Cache-disabled entries are added the peripheral
    57     *  addresses used by SYS/BIOS (i.e. Timers, Interrupt controller).
    58     *  The translation table is placed in
    59     *  an output section called "ti.sysbios.family.arm.arm9.mmuTableSection".
    60     *  This section is placed into the platform's default dataMemory and
    61     *  specified to not be initialized via the "NOINIT" type.  If
    62     *  cacheable is true and bufferable is true, L1 data cache operates as
    63     *  a write-back cache.  If cacheable is true but bufferable is false,
    64     *  L1 data cache operates as a write-through cache.
    65     *
    66     *  This module does not manage the second level descriptor tables.
    67     *  A 'SECTION' mapped access requires only a first level fetch.  In
    68     *  this case, there is no need for a second level descriptor table.
    69     *  A 'COARSE' or 'FINE' mapped access requires a second level
    70     *  descriptor table which can be supplied by the user.
    71     *
    72     *  Note:  There are size and alignment requirements on the second
    73     *         level descriptor tables depending on the page size.
    74     *         See the ARM Architecture Reference Manual for more info.
    75     *
    76     *  The following is an example of how to place the MMU table
    77     *  and how to enable L1 data caching for the address range
    78     *  0xC3000000-0xC4000000 in the *.cfg file:
    79     *
    80     *  @p(code)
    81     *
    82     *    var Cache = xdc.useModule('ti.sysbios.family.arm.arm9.Cache');
    83     *    var Mmu = xdc.useModule('ti.sysbios.family.arm.arm9.Mmu');
    84     *
    85     *    // Enable the cache
    86     *    Cache.enableCache = true;
    87     *
    88     *    // Enable the MMU (Required for L1 data caching)
    89     *    Mmu.enableMMU = true;
    90     *
    91     *    // descriptor attribute structure
    92     *    var attrs = {
    93     *        type: Mmu.FirstLevelDesc_SECTION,  // SECTION descriptor
    94     *        bufferable: true,                  // bufferable
    95     *        cacheable: true,                   // cacheable
    96     *        imp: 1,                            // implementation defined
    97     *        domain: 0,                         // domain between 0-15
    98     *        accPerm: 3,                        // read/write permission
    99     *    };
   100     *
   101     *    // Set the descriptor for each entry in the address range
   102     *    for (var i=0xC3000000; i < 0xC4000000; i = i + 0x00100000) {
   103     *        // Each 'SECTION' descriptor entry spans a 1MB address range
   104     *        Mmu.setFirstLevelDescMeta(i, i, attrs);
   105     *    }
   106     *
   107     *    var memmap = Program.cpu.memoryMap;
   108     *    var DDR = null;
   109     *
   110     *    // Find DDR in memory map
   111     *    for (var i=0; i < memmap.length; i++) {
   112     *        if (memmap[i].name == "DDR") {
   113     *            DDR = memmap[i];
   114     *        }
   115     *    }
   116     *
   117     *    // Place the MMU table in the DDR memory segment if it exists
   118     *    if (DDR != null) {
   119     *        var sectionName = "ti.sysbios.family.arm.arm9.mmuTableSection";
   120     *        Program.sectMap[sectionName] = new Program.SectionSpec();
   121     *        Program.sectMap[sectionName].type = "NOINIT";
   122     *        Program.sectMap[sectionName].loadSegment = "DDR";
   123     *    }
   124     *    else {
   125     *        print("No DDR memory segment was found");
   126     *    }
   127     *
   128     *  @p
   129     *
   130     *  The following is an example of using a second level descriptor
   131     *  to specify a 4KB block of memory.  The first level descriptor
   132     *  is specified as a COARSE page table.  The second level descriptors
   133     *  are specified as a small page, cacheable, and bufferable for the
   134     *  addresses 0xFFFEE000-0xFFFF0000.  This code is be placed in main()
   135     *  in the *.c file.   The MMU should not be enabled prior to initializing
   136     *  the second level descriptors.
   137     *
   138     *  @p(code)
   139     *
   140     *    #define MMU_LEVEL2DESC_SMALLPAGE    0x2
   141     *    #define MMU_LEVEL2DESC_BUFFERABLE   0x4
   142     *    #define MMU_LEVEL2DESC_CACHEABLE    0x8
   143     *
   144     *    #pragma DATA_ALIGN(mmuL2Table, 4096);    // align to 4KB
   145     *
   146     *    UInt32 mmuL2Table[256];   // each level 2 descriptor specifies a 4KB block
   147     *
   148     *    Void main(Int argc, Char * argv[])
   149     *    {
   150     *        Mmu_FirstLevelDescAttrs attrs;
   151     *        Int i;
   152     *
   153     *        // initialize the second level descriptors
   154     *        for (i=0; i < 256; i++) {
   155     *             mmuL2Table[i] = 0;
   156     *        }
   157     *
   158     *        // change the address starting at 0xFFFEE000 to be a small page
   159     *        mmuL2Table[0xEE] = 0xFFFEE000 | // set the physical address
   160     *            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
   161     *            0xFF0;                      // set Access Permission bits to 1
   162     *
   163     *        // change the address starting at 0xFFFEF000 to be a small page
   164     *        mmuL2Table[0xEF] = 0xFFFEF000 | // set the physical address
   165     *            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
   166     *            0xFF0;                      // set Access Permission bits to 1
   167     *
   168     *        // change the address starting at 0xFFFF0000 to be a small page
   169     *        mmuL2Table[0xF0] = 0xFFFF0000 | // set the physical address
   170     *            MMU_LEVEL2DESC_SMALLPAGE |  // set descriptor to small page (4KB)
   171     *            MMU_LEVEL2DESC_CACHEABLE |  // set cacheable bit to true
   172     *            MMU_LEVEL2DESC_BUFFERABLE | // set bufferable bit to true
   173     *            0xFF0;                      // set Access Permission bits to 1
   174     *
   175     *        // first level descriptor properties
   176     *        attrs.type = Mmu_FirstLevelDesc_COARSE; // set to a coarse descriptor
   177     *        attrs.imp = 1;                          // defined to be 1 for ARM9
   178     *        attrs.domain = 0;                       // set domain to 0
   179     *
   180     *        // Set the first level descriptor for the virtual address 0xFFFF0000.
   181     *        Mmu_setFirstLevelDesc((Ptr)0xFFFF0000, &mmuL2Table, &attrs);
   182     *
   183     *        // enable MMU
   184     *        Mmu_enable();
   185     *
   186     *        BIOS_start();
   187     *    }
   188     *
   189     *  @p
   190     *
   191     */
   192
   193    @Template ("./Mmu.xdt") /* generate function to init MMU page table */
   194    @ModuleStartup          /* call to initTableBuf() in startup */
   195
   196    module Mmu
   197    {
   198        // -------- ROV views --------
   199
   200        /*! @_nodoc */
   201        metaonly struct PageView {
   202            String      Type;
   203            Ptr         AddrVirtual;
   204            Ptr         AddrPhysical;
   205            Ptr         Level2TablePtr;
   206            Bool        Bufferable;
   207            Bool        Cacheable;
   208            String      L1DWritePolicy;
   209            UInt        IMP;
   210            UInt        Domain;
   211            String      Access;
   212        };
   213
   214        @Facet
   215        metaonly config ViewInfo.Instance rovViewInfo =
   216            ViewInfo.create({
   217                viewMap: [
   218                    ['PageView', {
   219                        type: ViewInfo.MODULE_DATA,
   220                        viewInitFxn: 'viewPages',
   221                        structName: 'PageView'
   222                    }]
   223               ]
   224           });
   225
   226       /*! First Level descriptors */
   227        enum FirstLevelDesc {
   228            FirstLevelDesc_FAULT = 0,      /*! Virtual address is unmapped  */
   229            FirstLevelDesc_COARSE = 1,     /*! Coarse page table descriptor */
   230            FirstLevelDesc_SECTION = 2,    /*! Section descriptor           */
   231            FirstLevelDesc_FINE = 3        /*! Fine page table descriptor   */
   232        };
   233
   234        /*!
   235         *  Structure for setting first level descriptor entries
   236         *
   237         *  See the 'Translation Tables' section of the ARM Architecture
   238         *  Reference Manual for details
   239         */
   240        struct FirstLevelDescAttrs {
   241            FirstLevelDesc type;   /*! first level descriptor type          */
   242            Bool  bufferable;       /*! is memory section bufferable        */
   243            Bool  cacheable;        /*! is memory section cacheable         */
   244            UInt8 imp;             /*! implementation defined               */
   245            UInt8 domain;          /*! domain access control value 0-15     */
   246            UInt8 accPerm;         /*! access permission bits value 0-3     */
   247        };
   248
   249        /*!
   250         *  ======== A_nullPointer ========
   251         *  Assert raised when a pointer is null
   252         */
   253        config xdc.runtime.Assert.Id A_nullPointer  = {
   254            msg: "A_nullPointer: Pointer is null"
   255        };
   256
   257        /*!
   258         *  ======== A_unknownDescType ========
   259         *  Assert raised when the descriptor type is not recognized.
   260         */
   261        config xdc.runtime.Assert.Id A_unknownDescType =
   262            {msg: "A_unknownDescType: Descriptor type is not recognized"};
   263
   264        /*! default descriptor attributes structure */
   265        config FirstLevelDescAttrs defaultAttrs = {
   266            type: FirstLevelDesc_SECTION,   /* SECTION descriptor        */
   267            bufferable: false,              /* false by default          */
   268            cacheable: false,               /* false by default          */
   269            imp: 1,                         /* set to 1 for ARM9 devices */
   270            domain: 0,                      /* default Domain is 0       */
   271            accPerm: 3,                     /* allow read/write          */
   272        };
   273
   274        /*!
   275         *  ======== enableMMU ========
   276         *  Configuration parameter to enable MMU.
   277         */
   278        config Bool enableMMU = true;
   279
   280        /*!
   281         *  ======== cachePlatformMemory ========
   282         *  Flag to automatically mark platform's code/data/stack memory as
   283         *  cacheable in MMU descriptor table
   284         *
   285         *  By default, all memory regions defined in the platform an
   286         *  application is built with are marked as cacheable.
   287         *
   288         *  @see xdc.bld.Program#platform
   289         *
   290         *  If manual configuration of memory regions is required, set
   291         *  this config parameter to 'false'.
   292         */
   293        metaonly config Bool cachePlatformMemory = true;
   294
   295        /*!
   296         *  ======== setFirstLevelDescMeta ========
   297         *  Statically sets the descriptor for the virtual address.
   298         *
   299         *  The first level table entry for the virtual address is mapped
   300         *  to the physical address with the attributes specified. The
   301         *  descriptor table is effective when the MMU is enabled.
   302         *
   303         *  @param(virtualAddr)  The modified virtual address
   304         *  @param(phyAddr)      The physical address
   305         *  @param(attrs)        Pointer to first level descriptor attribute struct
   306         */
   307        metaonly Void setFirstLevelDescMeta(Ptr virtualAddr, Ptr phyAddr,
   308                                            FirstLevelDescAttrs attrs);
   309
   310        /*!
   311         *  ======== disable ========
   312         *  Disables the MMU.
   313         *
   314         *  If the MMU is already disabled, then simply return.
   315         *  Otherwise this function does the following:
   316         *  If the L1 data cache is enabled, write back invalidate all
   317         *  of L1 data cache.  If the L1 program cache is enabled,
   318         *  invalidate all of L1 program cache. This function does not
   319         *  change the cache L1 data/program settings.
   320         */
   321        @DirectCall
   322        Void disable();
   323
   324        /*!
   325         *  ======== enable ========
   326         *  Enables the MMU.
   327         *
   328         *  If the MMU is already enabled, then simply return.
   329         *  Otherwise this function does the following:
   330         *  If the L1 program cache is enabled, invalidate all of L1
   331         *  program cache.  This function does not change the L1
   332         *  data/program cache settings.
   333         */
   334        @DirectCall
   335        Void enable();
   336
   337        /*!
   338         *  ======== initDescAttrs() ========
   339         *  Initializes the first level descriptor attribute structure
   340         *
   341         *  @param(attrs)      Pointer to first level descriptor attribute struct
   342         */
   343        @DirectCall
   344        Void initDescAttrs(FirstLevelDescAttrs *attrs);
   345
   346        /*!
   347         *  ======== isEnabled ========
   348         *  Determines if the MMU is enabled
   349         */
   350        @DirectCall
   351        Bool isEnabled();
   352
   353        /*!
   354         *  ======== setFirstLevelDesc ========
   355         *  Sets the descriptor for the virtual address.
   356         *
   357         *  The first level table entry for the virtual address is mapped
   358         *  to the physical address with the attributes specified. The
   359         *  descriptor table is effective when the MMU is enabled.
   360         *
   361         *  @param(virtualAddr)  The modified virtual address
   362         *  @param(phyAddr)      The physical address
   363         *  @param(attrs)        Pointer to first level descriptor attribute struct
   364         */
   365        @DirectCall
   366        Void setFirstLevelDesc(Ptr virtualAddr, Ptr phyAddr,
   367                               FirstLevelDescAttrs *attrs);
   368
   369
   370    internal:
   371
   372        /*! static array to hold first level dscriptor table */
   373        metaonly config UInt32 tableBuf[];
   374
   375        /*!
   376         *  ======== enableAsm ========
   377         *  Assembly function to enable the MMU.
   378         */
   379        Void enableAsm();
   380
   381        /*!
   382         *  ======== disableAsm ========
   383         *  Assembly function to disable the MMU.
   384         */
   385        Void disableAsm();
   386
   387        /*! function generated to initialize first level descriptor table */
   388        Void initTableBuf(Module_State *mod);
   389
   390        /*! Module state */
   391        struct Module_State {
   392            UInt32 tableBuf[];      /*! 16KB array for first-level descriptors */
   393        }
   394    }
   395    /*
   396     *  @(#) ti.sysbios.family.arm.arm9; 2, 0, 0, 0,116; 6-15-2011 16:24:10; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   397
   398     */
   399


package ti.sysbios.family.arm.arm9

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.arm9 ========
    40     *  Contains specifications for the ARM9 family-specific SYS/BIOS functions.
    41     */
    42    package ti.sysbios.family.arm.arm9 [2,0,0,0] {
    43        module Cache;
    44        module Mmu;
    45    }
    46    /*
    47     *  @(#) ti.sysbios.family.arm.arm9; 2, 0, 0, 0,116; 6-15-2011 16:24:10; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    48
    49     */
    50


module ti.sysbios.family.arm.da830.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm.da830;
    37
    38    import xdc.runtime.Diags;
    39    import xdc.runtime.Log;
    40    import xdc.runtime.Assert;
    41    import xdc.rov.ViewInfo;
    42    import xdc.runtime.Error;
    43
    44    /*!
    45     *  ======== Hwi ========
    46     *  Hardware Interrupt Support Module.
    47     *
    48     *  This Hwi module provides ARM family-specific implementations of the
    49     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    50     *
    51     *  Additional ARM device-specific APIs are also provided.
    52     *
    53     *  IRQ Interrupts are nestable and can invoke SYS/BIOS functions.
    54     *  FIQ Interrupts are non-nestable and cannot invoke SYS/BIOS functions.
    55     *
    56     *  The IRQ dispatcher re-enables IRQ interrupts prior to invoking the
    57     *  ISR function associated with an interrupt but uses the CP INTC's
    58     *  Host Interrupt Nesting Level Register (HINLR) to suppress lower
    59     *  priority interrupts while the interrupt is being serviced.
    60     *
    61     *  The default FIQ handler does not re-enable FIQ interrupts nor
    62     *  use the HINLR. It simply calls the registered FIQ ISR and returns.
    63     *
    64     *  To statically configure a non-dispatched interrupt:
    65     *  To dynamically configure a non-dispatched interrupt:
    66     *
    67     *  @p(html)
    68     *  <h3> Calling Context </h3>
    69     *  <table border="1" cellpadding="3">
    70     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    71     *
    72     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    73     *    <!--                                                                                                                 -->
    74     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #disableFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    78     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #disableIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #enableFIQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #enableIRQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    86     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    87     *    <tr><td> {@link #restoreFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    88     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    89     *    <tr><td> {@link #restoreIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    90     *    <tr><td> {@link #setPriority}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td colspan="6"> Definitions: <br />
    99     *       <ul>
   100     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   101     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   102     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   103     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   104     *           <ul>
   105     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   106     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   107     *             <li> During main().</li>
   108     *             <li> During BIOS.startupFxns.</li>
   109     *           </ul>
   110     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   111     *           <ul>
   112     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   113     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   114     *           </ul>
   115     *       </ul>
   116     *    </td></tr>
   117     *
   118     *
   119     *  </table>
   120     *  @p
   121     */
   122
   123    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   124    @ModuleStartup          /* generates call to Hwi_Module_startup at startup */
   125
   126    module Hwi inherits ti.sysbios.interfaces.IHwi
   127    {
   128
   129        // -------- Module Constants --------
   130
   131        /*! The DA830 ARM Interrupt Controller has 101 defined interrupts. */
   132        const Int NUM_INTERRUPTS = 101;
   133
   134        // -------- Module Types --------
   135
   136        /*! Hwi vector function type definition. */
   137        typedef Void (*VectorFuncPtr)(void);
   138
   139        /*! @_nodoc Hwi plug function type definition. */
   140        typedef Void (*PlugFuncPtr)(void);
   141
   142        /*!
   143         * Common Platform Interrupt Controller.
   144         */
   145        struct CPINTC {
   146            UInt32 REV;         /*! 0x00 Revision Register */
   147            UInt32 CR;          /*! 0x04 Control Register */
   148            UInt32 RES_08;      /*! 0x08 reserved */
   149            UInt32 HCR;         /*! 0x0C Host Control Register */
   150            UInt32 GER;         /*! 0x10 Global Enable Register */
   151            UInt32 RES_14;      /*! 0x14 reserved */
   152            UInt32 RES_18;      /*! 0x18 reserved */
   153            UInt32 GNLR;        /*! 0x1C Global Nesting Level Register */
   154            UInt32 SISR;        /*! 0x20 Status Index Set Register */
   155            UInt32 SICR;        /*! 0x24 Status Index Clear Register */
   156            UInt32 EISR;        /*! 0x28 Enable Index Set Register */
   157            UInt32 EICR;        /*! 0x2C Enable Index Clear Register */
   158            UInt32 GWER;        /*! 0x30 Global Wakeup Enable Register */
   159            UInt32 HIEISR;      /*! 0x34 Host Int Enable Index Set Register */
   160            UInt32 HIDISR;      /*! 0x38 Host Int Disable Index Set Register */
   161            UInt32 RES_3C;      /*! 0x3C reserved */
   162            UInt32 PPR;         /*! 0x40 Pacer Prescale Register */
   163            UInt32 RES_44;      /*! 0x44 reserved */
   164            UInt32 RES_48;      /*! 0x48 reserved */
   165            UInt32 RES_4C;      /*! 0x4C reserved */
   166            Ptr   *VBR;         /*! 0x50 Vector Base Register */
   167            UInt32 VSR;         /*! 0x54 Vector Size Register */
   168            Ptr    VNR;         /*! 0x58 Vector Null Register */
   169            UInt32 RES_5C[9];   /*! 0x5C-0x7C reserved */
   170            Int32  GPIR;        /*! 0x80 Global Prioritized Index Register */
   171            Ptr   *GPVR;        /*! 0x84 Global Prioritized Vector Register */
   172            UInt32 RES_88;      /*! 0x88 reserved */
   173            UInt32 RES_8C;      /*! 0x8C reserved */
   174            UInt32 GSIER;       /*! 0x90 Global Secure Interrupt Enable Register */
   175            UInt32 SPIR;        /*! 0x94 Secure Prioritized Index Register */
   176            UInt32 RES_98[26];  /*! 0x98-0xFC reserved */
   177            UInt32 PPMR[64];    /*! 0x100-0x1FC Pacer Parameter/Map Registers */
   178            UInt32 SRSR[32];    /*! 0x200-0x27C Status Raw/Set Registers */
   179            UInt32 SECR[32];    /*! 0x280-0x2FC Status Enabled/Clear Registers */
   180            UInt32 ESR[32];     /*! 0x300-0x37C Enable Set Registers */
   181            UInt32 ECR[32];     /*! 0x380-0x3FC Enable Clear Registers */
   182            UInt8  CMR[1024];   /*! 0x400-0x7FC Channel Map Registers */
   183            UInt8  HIMR[256];   /*! 0x800-0x8FC Host Interrupt Map Registers */
   184            UInt32 HIPIR[256];  /*! 0x900-0xCFC Host Interrupt Pri Index Registers */
   185            UInt32 PR[32];      /*! 0xD00-0xD7C Polarity Registers */
   186            UInt32 TR[32];      /*! 0xD80-0xDFC Type Registers */
   187            UInt32 WER[64];     /*! 0xE00-0xEFC Wakeup Enable Registers */
   188            UInt32 DSR[64];     /*! 0xF00-0xFFC Debug Select Registers */
   189            UInt32 SER[32];     /*! 0x1000-0x107C Secure Enable Registers */
   190            UInt32 SDR[32];     /*! 0x1080-0x10FC Secure Disable Registers */
   191            UInt32 HINLR[256];  /*! 0x1100-0x14FC Host Interrupt Nesting Level Registers */
   192            UInt32 HIER[8];     /*! 0x1500-0x151F Host Interrupt Enable Registers */
   193            UInt32 RES_1520[56];/*! 0x1520-0x15fC Reserved */
   194            Ptr   *HIPVR[256];  /*! 0x1600-0x19fC Host Interrupt Prioritized Vector */
   195        };
   196
   197        /*!
   198         * Physical Common Platform Interrupt Controller Device.
   199         * Short name is "Hwi_cpIntc"
   200         * Long name is "ti_sysbios_family_arm_da830_Hwi_cpIntc"
   201         */
   202        extern volatile CPINTC cpIntc;
   203
   204        /*!
   205         *  ======== BasicView ========
   206         *  @_nodoc
   207         */
   208        metaonly struct BasicView {
   209            Ptr         halHwiHandle;
   210            String      label;
   211            Int         intNum;
   212            Int         priority;
   213            String      fxn;
   214            UArg        arg;
   215            Ptr         irp;
   216            String      status;
   217        };
   218
   219        /*!
   220         *  ======== ModuleView ========
   221         *  @_nodoc
   222         */
   223        metaonly struct ModuleView {
   224            String      options[4];
   225            SizeT       hwiStackPeak;
   226            SizeT       hwiStackSize;
   227            Ptr         hwiStackBase;
   228            UInt        priorities[256];
   229        };
   230
   231        /*!
   232         *  ======== rovViewInfo ========
   233         *  @_nodoc
   234         */
   235        @Facet
   236        metaonly config ViewInfo.Instance rovViewInfo =
   237            ViewInfo.create({
   238                viewMap: [
   239                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   240                    ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
   241                ]
   242            });
   243
   244        // -------- Module Parameters --------
   245
   246        /*! Assert when bad maskSetting parameter provided */
   247        config Assert.Id A_unsupportedMaskingOption = {
   248            msg: "A_unsupportedMaskingOption: unsupported maskSetting."
   249        };
   250
   251        /*! Reset Handler. Default is c_int00 */
   252        metaonly config VectorFuncPtr resetFunc;
   253
   254        /*! Undefined instruction exception handler. Default is self loop */
   255        metaonly config VectorFuncPtr undefinedInstFunc;
   256
   257        /*! SWI Handler. Default is internal SWI handler */
   258        metaonly config VectorFuncPtr swiFunc;
   259
   260        /*! Prefetch abort exception handler. Default is self loop */
   261        metaonly config VectorFuncPtr prefetchAbortFunc;
   262
   263        /*! Data abort exception handler. Default is self loop */
   264        metaonly config VectorFuncPtr dataAbortFunc;
   265
   266        /*! Reserved exception handler. Default is self loop */
   267        metaonly config VectorFuncPtr reservedFunc;
   268
   269        /*! IRQ interrupt handler. Default is internal IRQ dispatcher */
   270        metaonly config VectorFuncPtr irqFunc;
   271
   272        /*! FIQ interrupt handler. Default is internal FIQ dispatcher */
   273        metaonly config VectorFuncPtr fiqFunc;
   274
   275        /*!
   276         *  non-dispatched interrupt object.
   277         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   278         */
   279        metaonly struct NonDispatchedInterrupt {
   280            Int             intNum;
   281            PlugFuncPtr     fxn;            /*! "Hwi_plug'd" ISR function. */
   282            UInt            priority;
   283            Bool            enableInt;
   284        };
   285
   286        /*!
   287         *  non-dispatched interrupt array.
   288         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   289         */
   290        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   291
   292        /*!
   293         *  FIQ stack pointer. Default = null.
   294         *  (Indicates that stack is to be created using
   295         *  staticPlace()
   296         */
   297        config Ptr fiqStack = null;
   298
   299        /*!
   300         *  FIQ stack size in bytes.
   301         *  Default is 1024 bytes.
   302         */
   303        metaonly config SizeT fiqStackSize = 1024;
   304
   305        /*!
   306         *  Memory section used for FIQ stack
   307         *  Default is null.
   308         */
   309        metaonly config String fiqStackSection = null;
   310
   311        /*!
   312         *  IRQ stack pointer. Default = null.
   313         *  (Indicates that stack is to be created using
   314         *  staticPlace()
   315         */
   316        config Ptr irqStack = null;
   317
   318        /*!
   319         *  IRQ stack size in bytes.
   320         *  Default is 256 bytes.
   321         *  This is enough room for 32 nested IRQ interrupts.
   322         *
   323         *  An IRQ interrupt pushes 2 32bit words onto the IRQ stack.
   324         */
   325        metaonly config SizeT irqStackSize = 256;
   326
   327        /*!
   328         *  Memory section used for IRQ stack
   329         *  Default is null.
   330         */
   331        metaonly config String irqStackSection = null;
   332
   333        /*!
   334         *  Location of the Interrupt Vector Table
   335         *
   336         *  The default placement of the Interrupt Vector Table
   337         *  is immediately after the ARM exception table located
   338         *  at 0xffff0000.
   339         *
   340         *  The vector table is internally assigned to the ".vectorTable"
   341         *  memory section.
   342         */
   343        metaonly config Ptr vectorTableAddress = 0xffff0040;
   344
   345        /*!
   346         *  Error raised when Hwi is already defined
   347         */
   348        config Error.Id E_alreadyDefined = {
   349            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   350        };
   351
   352        /*!
   353         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   354         */
   355        config Log.Event LM_begin = {
   356            mask: Diags.USER1 | Diags.USER2,
   357            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   358        };
   359
   360        /*!
   361         *  Issued just after return from Hwi function (with interrupts disabled)
   362         */
   363        config Log.Event LD_end = {
   364            mask: Diags.USER2,
   365            msg: "LD_end: hwi: 0x%x"
   366        };
   367
   368
   369        // -------- Module Functions --------
   370
   371        /*!
   372         *  ======== disable ========
   373         */
   374        @Macro
   375        override UInt disable();
   376
   377        /*!
   378         *  ======== enable ========
   379         */
   380        @Macro
   381        override UInt enable();
   382
   383        /*!
   384         *  ======== restore ========
   385         */
   386        @Macro
   387        override Void restore(UInt key);
   388
   389        /*!
   390         *  ======== inUseMeta ========
   391         *  @_nodoc
   392         *  Check for Hwi already in use.
   393         *  For internal SYS/BIOS use only.
   394         *  Should be called prior to any internal Hwi.create().
   395         *
   396         *  @param(intNum)  interrupt number
   397         */
   398        metaonly Bool inUseMeta(UInt intNum);
   399
   400        /*!
   401         *  @_nodoc
   402         *  ======== plug ========
   403         *  Plug an interrupt vector with an ISR address.
   404         *
   405         *  Hwi_plug writes an Interrupt Service Fetch Packet (ISFP) into the
   406         *  Interrupt Service Table (IST), at the address corresponding to intNum
   407         *  The op-codes written in the ISFP create a branch to the function
   408         *  entry  point specified by fxn:
   409         *
   410         *  @p(code)
   411         *          stw     b0, *SP--[1]
   412         *          mvk     fxn, b0
   413         *          mvkh    fxn, b0
   414         *          b       b0
   415         *          ldw     *++SP[1],b0
   416         *          nop     4
   417         *  @p
   418         *
   419         *  Hwi_plug hooks up the specified function as the branch target of a
   420         *  hardware interrupt (fielded by the CPU) at the vector address
   421         *  specified in intNum. Hwi_plug does not enable the interrupt.
   422         *  Use Hwi_enableIER to enable specific interrupts.
   423         *
   424         *  For internal SYS/BIOS use only.
   425         *
   426         *  Constraints and Calling Context
   427         *  o vecid must be a valid interrupt ID in the range of 0-15.
   428         *
   429         *  @param(intNum)  interrupt number
   430         *  @param(fxn)     pointer to ISR function
   431         */
   432        @DirectCall
   433        Void plug(UInt intNum, PlugFuncPtr fxn);
   434
   435        /*!
   436         *  ======== plugMeta ========
   437         *  Statically plug an interrupt vector with an ISR address.
   438         *
   439         *  @param(intNum)  interrupt number
   440         *  @param(fxn)     pointer to ISR function
   441         */
   442        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   443
   444        /*!
   445         *  ======== getHandle ========
   446         *  Returns Hwi_handle associated with intNum
   447         *
   448         *  @param(intNum)  interrupt number
   449         */
   450        @DirectCall
   451        Handle getHandle(UInt intNum);
   452
   453        /*!
   454         *  ======== enableFIQ ========
   455         *  Enable FIQ interrupts.
   456         *
   457         *  @b(returns)     previous FIQ interrupt enable/disable state
   458         */
   459        @DirectCall
   460        UInt enableFIQ();
   461
   462        /*!
   463         *  ======== disableFIQ ========
   464         *  Disable FIQ interrupts.
   465         *
   466         *  @b(returns)     previous FIQ interrupt enable/disable state
   467         */
   468        @DirectCall
   469        UInt disableFIQ();
   470
   471        /*!
   472         *  ======== restoreFIQ ========
   473         *  Restore FIQ interrupts.
   474         *
   475         *  @param(key)     enable/disable state to restore
   476         */
   477        @DirectCall
   478        Void restoreFIQ(UInt key);
   479
   480        /*!
   481         *  ======== enableIRQ ========
   482         *  Enable IRQ interrupts.
   483         *
   484         *  @param(key)     enable/disable state to restore
   485         */
   486        @DirectCall
   487        UInt enableIRQ();
   488
   489        /*!
   490         *  ======== disableIRQ ========
   491         *  Disable IRQ interrupts.
   492         *
   493         *  @b(returns)     previous IRQ interrupt enable/disable state
   494         */
   495        @DirectCall
   496        UInt disableIRQ();
   497
   498        /*!
   499         *  ======== restoreIRQ ========
   500         *  Restore IRQ interrupts.
   501         *
   502         *  @param(key)     enable/disable state to restore
   503         */
   504        @DirectCall
   505        Void restoreIRQ(UInt key);
   506
   507        /*!
   508         *  ======== beginIRQ ========
   509         *  Function to be invoked at the beginning of a
   510         *  non-dispatched IRQ handler. Services cpIntc.
   511         */
   512        @DirectCall
   513        Void beginIRQ();
   514
   515        /*!
   516         *  ======== endIRQ ========
   517         *  Function to be invoked at the end of a
   518         *  non-dispatched IRQ handler. Services cpIntc.
   519         */
   520        @DirectCall
   521        Void endIRQ();
   522
   523        /*!
   524         *  ======== beginFIQ ========
   525         *  Function to be invoked at the beginning of a
   526         *  non-dispatched FIQ handler. Services cpIntc.
   527         */
   528        @DirectCall
   529        Void beginFIQ();
   530
   531        /*!
   532         *  ======== endFIQ ========
   533         *  Function to be invoked at the end of a
   534         *  non-dispatched FIQ handler. Services cpIntc.
   535         */
   536        @DirectCall
   537        Void endFIQ();
   538
   539        /*!
   540         *  ======== setPriority ========
   541         *  Set an interrupt's relative priority.
   542         *
   543         *  Valid priorities are 0 - 31. 0 is highest priority.
   544         *  Priorities 0 - 1 are routed to the ARM's FIQ interrupt.
   545         *  Priorities 2 - 31 are routed to the ARM's IRQ interrupt.
   546         *
   547         *  @param(intNum)      ID of interrupt
   548         *  @param(priority)    priority
   549         */
   550        @DirectCall
   551        Void setPriority(UInt intNum, UInt priority);
   552
   553    instance:
   554
   555        /*!
   556         *  Interrupt priority.
   557         *  Valid priorities are 0 - 31. 0 is highest priority.
   558         *  Priorities 0 - 1 are routed to the ARM's FIQ interrupt.
   559         *  Priorities 2 - 31 are routed to the ARM's IRQ interrupt.
   560         *  The default is 31 which is the lowest priority IRQ interrupt.
   561         */
   562        override config Int priority = 31;
   563
   564        /*!
   565         *  ======== reconfig ========
   566         *  Reconfigure a dispatched interrupt.
   567         */
   568        @DirectCall
   569        Void reconfig(FuncPtr fxn, const Params *params);
   570
   571    internal:   /* not for client use */
   572
   573        /*
   574         * Swi and Task module function pointers.
   575         * Used to decouple Hwi from Swi and Task when
   576         * dispatcherSwiSupport or
   577         * dispatcherTaskSupport is false.
   578         */
   579        config UInt (*swiDisable)();
   580        config Void (*swiRestoreHwi)(UInt);
   581        config UInt (*taskDisable)();
   582        config Void (*taskRestoreHwi)(UInt);
   583
   584        /*! Hwi vector function type definition. */
   585        typedef Void (*HandlerFuncPtr)(Handle, UInt);
   586
   587        /* assembly code mode registers setup */
   588        Void init();
   589
   590        /* Interrupt Dispatcher assembly code wrapper */
   591        Void dispatchIRQ();
   592
   593        /* IRQ Interrupt Dispatcher */
   594        Void dispatchIRQC();
   595
   596        /* default FIQ Interrupt Dispatcher */
   597        Void dispatchFIQC();
   598
   599        /* spurious interrupt handler */
   600        Void spuriousInt();
   601
   602        Void handlerNONE(Handle hwi, UInt intNum);
   603
   604        Void handlerALL(Handle hwi, UInt intNum);
   605
   606        Void handlerLOWER(Handle hwi, UInt intNum);
   607
   608        Void handlerSELF(Handle hwi, UInt intNum);
   609
   610        /*!
   611         *  const array to hold all HookSet objects.
   612         */
   613        config HookSet hooks[length] = [];
   614
   615        /*! Meta World Only Hwi Configuration Object. */
   616        metaonly struct InterruptObj {
   617            String name;            /* symbol used for vector table entry */
   618            Bool used;              /* Interrupt already defined? */
   619            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   620            UInt priority;          /* used to determine FIQ/IRQ type */
   621            FuncPtr fxn;            /* Dispatched ISR function */
   622            PlugFuncPtr pfxn;       /* "Hwi_plug'd" ISR function. */
   623        };
   624
   625        /*!
   626         * Meta-only array of interrupt objects.
   627         * This meta-only array of Hwi config objects is initialized
   628         * in Hwi.xs:module$meta$init().
   629         */
   630        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   631
   632        struct Instance_State {
   633            UArg            arg;            // Argument to Hwi function.
   634            FuncPtr         fxn;            // Hwi function.
   635            Int             intNum;         // Interrupt number
   636            HandlerFuncPtr  handler;        // MaskingOption-unique handler
   637            Irp             irp;            // current IRP
   638            Ptr             hookEnv[];
   639        };
   640
   641        struct Module_State {
   642            Bits32      er[4];          // Initial Enable Reg values
   643            UInt        irp;            // temporary irp storage for IRQ handler
   644            UInt8       priorities[NUM_INTERRUPTS];
   645                                        // table of interrupt priorities
   646            Char        *taskSP;        // temporary storage of interrupted
   647                                        // Task's SP during ISR execution
   648            /* ROM */
   649            Char        *isrStack;      // Points to isrStack address
   650            Ptr         isrStackBase;   // _stack
   651            Ptr         isrStackSize;   // _STACK_SIZE
   652            Ptr         vectorTableBase;// Points to base of vector table
   653
   654            Char        fiqStack[];     // buffer used for FIQ stack
   655            SizeT       fiqStackSize;
   656
   657            Char        irqStack[];     // buffer used for IRQ stack
   658            SizeT       irqStackSize;
   659
   660            Handle      dispatchTable[NUM_INTERRUPTS];
   661                                        // dispatch table
   662        };
   663    }
   664
   665    /*
   666     *  @(#) ti.sysbios.family.arm.da830; 2, 0, 0, 0,188; 6-15-2011 16:24:17; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   667
   668     */
   669


package ti.sysbios.family.arm.da830

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     * .da830 target-specific modules
    36     *
    37     */
    38
    39    requires ti.sysbios.interfaces;
    40
    41    /*!
    42     *  ======== ti.sysbios.family.da830 ========
    43     *  Contains specifications for the.da830 device-specific SYS/BIOS functions.
    44     *
    45     */
    46    package ti.sysbios.family.arm.da830 [2,0,0,0] {
    47        module TimestampProvider;
    48        module Hwi;
    49        module TimerSupport;
    50        module Clobber;
    51    }
    52    /*
    53     *  @(#) ti.sysbios.family.arm.da830; 2, 0, 0, 0,188; 6-15-2011 16:24:18; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    54
    55     */
    56


module ti.sysbios.family.arm.da830.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.da830;
    39
    40    import xdc.runtime.Assert;
    41
    42    /*!
    43     *  ======== TimestampProvider ========
    44     *  Provides.da830 specific timestamp APIs to xdc.runtime.Timestamp
    45     *
    46     *  Uses the iceCrusher Benchmark counters.
    47     *  @p(html)
    48     *  <h3> Calling Context </h3>
    49     *  <table border="1" cellpadding="3">
    50     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    51     *
    52     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    53     *    <!--                                                                                                                 -->
    54     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    55     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    56     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td colspan="6"> Definitions: <br />
    58     *       <ul>
    59     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    60     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    61     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    62     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    63     *           <ul>
    64     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    65     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    66     *             <li> During main().</li>
    67     *             <li> During BIOS.startupFxns.</li>
    68     *           </ul>
    69     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    70     *           <ul>
    71     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    72     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    73     *           </ul>
    74     *       </ul>
    75     *    </td></tr>
    76     *
    77     *
    78     *  </table>
    79     *  @p
    80     */
    81
    82    @ModuleStartup          /* To get Clock Timer Handle */
    83
    84    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    85    {
    86
    87        /*!
    88         *  CountType
    89         *
    90         *  @c(CountType_CYCLES)
    91         *  Timestamp is in cycles.
    92         *
    93         *  @c(CountType_INSTRUCTIONS)
    94         *  Timestamp is in instructions.
    95         */
    96
    97        enum CountType {
    98            CountType_CYCLES,       /*! count cycles */
    99            CountType_INSTRUCTIONS  /*! count instructions */
   100        };
   101
   102        struct IceCrusherRegs {
   103            UInt32  VER;            /*! 0x00 Revision */
   104            UInt32  DBGCFG;         /*! 0x04 Debug Config */
   105            UInt32  DBGCNTL;        /*! 0x08 Debug Control & Status */
   106            UInt32  RES_0C;         /*! 0x0C Reserved */
   107            UInt32  TRIGCNTL;       /*! 0x10 Trigger Control */
   108            UInt32  RSTCNTL;        /*! 0x14 Reset Control */
   109            UInt32  THRDIDCLM;      /*! 0x18 Thread ID Claim */
   110            UInt32  THRDID;         /*! 0x1c Thread ID */
   111            UInt32  INTCNTL;        /*! 0x20 Interrupt Control */
   112            UInt32  ETMCNTL;        /*! 0x24 ETM Control */
   113            UInt32  ETMPID;         /*! 0x28 ETM Process ID */
   114            UInt32  TEST;           /*! 0x2C Test */
   115            UInt32  SWBRKCTL;       /*! 0x30 Software Breakpoint Control */
   116            UInt32  SWBRKVAL;       /*! 0x34 Software Breakpoint Value */
   117            UInt32  RES_38;         /*! 0x38 Reserved */
   118            UInt32  RES_3C;         /*! 0x3C Reserved */
   119            UInt32  BCNT0CTRL;      /*! 0x40 Benchmark Counter 0 Control */
   120            UInt32  BCNT0;          /*! 0x44 Benchmark Counter 0 */
   121            UInt32  RES_48;         /*! 0x48 Reserved */
   122            UInt32  RES_4C;         /*! 0x4C Reserved */
   123            UInt32  BCNT1CTRL;      /*! 0x50 Benchmark Counter 1 Control */
   124            UInt32  BCNT1;          /*! 0x54 Benchmark Counter 1 */
   125            UInt32  RES_58[10];     /*! 0x58 - 0x7C Reserved */
   126            UInt32  HWBRK0CTL;      /*! 0x80 Hardware Breakpoint 0 Control */
   127            UInt32  HWBRK0ADR;      /*! 0x84 Hardware Breakpoint 0 Address */
   128            UInt32  HWBRK0ADRMASK;  /*! 0x88 Hardware Breakpoint 0 Address Mask */
   129            UInt32  RES_8C;         /*! 0x8C Reserved */
   130            UInt32  HWBRK1CTL;      /*! 0x90 Hardware Breakpoint 1 Control */
   131            UInt32  HWBRK1ADR;      /*! 0x94 Hardware Breakpoint 1 Address */
   132            UInt32  HWBRK1ADRMASK;  /*! 0x98 Hardware Breakpoint 1 Address Mask */
   133            UInt32  RES_9C;         /*! 0x9C Reserved */
   134            UInt32  HWBRK2CTL;      /*! 0xA0 Hardware Breakpoint 2 Control */
   135            UInt32  HWBRK2ADR;      /*! 0xA4 Hardware Breakpoint 2 Address */
   136            UInt32  HWBRK2ADRMASK;  /*! 0xA8 Hardware Breakpoint 2 Address Mask */
   137            UInt32  RES_AC;         /*! 0xAC Reserved */
   138            UInt32  HWBRK3CTL;      /*! 0xB0 Hardware Breakpoint 3 Control */
   139            UInt32  HWBRK3ADR;      /*! 0xB4 Hardware Breakpoint 3 Address */
   140            UInt32  HWBRK3ADRMASK;  /*! 0xB8 Hardware Breakpoint 3 Address Mask */
   141            UInt32  RES_BC[14];     /*! 0xBC - 0xF0 Reserved */
   142            UInt32  OS_LOCKSTS;     /*! 0xF4 OS Lock Status */
   143            UInt32  OS_LOCK;        /*! 0xF8 OS Lock */
   144            UInt32  DCON;           /*! 0xFC DCON Register */
   145        }
   146
   147        extern volatile IceCrusherRegs iceRegs;
   148
   149        /*! @_nodoc */
   150        @XmlDtd
   151        metaonly struct Module_View {
   152            UInt32  upper32Bits;
   153        };
   154
   155        /*! Assert when configured benchmark counter is owned by CCS */
   156        config Assert.Id A_counterInUse = {
   157            msg: "A_counterInUse: Benchmark counter already claimed."
   158        };
   159
   160        /*! Assert if interrupt control register is owned by CCS */
   161        config Assert.Id A_intControlInUse = {
   162            msg: "A_intCOntrolInUse: iceCrusher Int Control Register already claimed."
   163        };
   164
   165        /*! ICECrusher Benchmark Counter id. 0 or 1. Default is 1 */
   166        config UInt benchmarkCounterId = 1;
   167
   168        /*!
   169         *  Timestamp count type. Default is CYCLES.
   170         *  CountType_INSTRUCTIONS only supported on benchmarkCounterId 1!!!
   171         */
   172        config CountType countType = CountType_CYCLES;
   173
   174    internal:   /* not for client use */
   175
   176        /*
   177         * iceCrusher Benchmark Counter Overflow Interrupt Handler
   178         */
   179        Void overflowHandler(UArg arg);
   180
   181        /*
   182         * release the iceCrusher Benchmark Counters on exit so CCS can use them again
   183         */
   184        Void releaseCounters();
   185
   186        struct Module_State {
   187            UInt32          upper32Bits;    /* upper 32 bits of counter */
   188            Hwi.Handle      hwi;            /* counter overflow Hwi object */
   189        }
   190    }
   191    /*
   192     *  @(#) ti.sysbios.family.arm.da830; 2, 0, 0, 0,188; 6-15-2011 16:24:17; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   193
   194     */
   195


module ti.sysbios.family.arm.dm6446.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm.dm6446;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    import xdc.runtime.Diags;
    41    import xdc.runtime.Error;
    42    import xdc.runtime.Log;
    43
    44    /*!
    45     *  ======== Hwi ========
    46     *  Hardware Interrupt Support Module.
    47     *
    48     *  This Hwi module provides ARM family-specific implementations of the
    49     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    50     *
    51     *  Additional ARM device-specific APIs are also provided.
    52     *
    53     *  @a(NOTE)
    54     *  In this Hwi module implementation, the instance config parameter value
    55     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    56     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    57     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    58     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    59     *  silently converted to {@link #MaskingOption_SELF}.
    60     *
    61     *  @p(html)
    62     *  <h3> Calling Context </h3>
    63     *  <table border="1" cellpadding="3">
    64     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    65     *
    66     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    67     *    <!--                                                                                                                 -->
    68     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #disableEINT0}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #disableEINT1}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #disableFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #disableIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    76     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #enableEINT0}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #enableEINT1}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #enableFIQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #enableIRQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    84     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    85     *    <tr><td> {@link #restoreEINT0}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #restoreEINT1}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #restoreFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    88     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    89     *    <tr><td> {@link #restoreIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    90     *    <tr><td> {@link #setPriority}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td colspan="6"> Definitions: <br />
    99     *       <ul>
   100     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   101     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   102     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   103     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   104     *           <ul>
   105     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   106     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   107     *             <li> During main().</li>
   108     *             <li> During BIOS.startupFxns.</li>
   109     *           </ul>
   110     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   111     *           <ul>
   112     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   113     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   114     *           </ul>
   115     *       </ul>
   116     *    </td></tr>
   117     *
   118     *
   119     *  </table>
   120     *  @p
   121     */
   122
   123    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   124    @ModuleStartup          /* generates call to Hwi_Module_startup at startup */
   125
   126    module Hwi inherits ti.sysbios.interfaces.IHwi
   127    {
   128
   129        // -------- Module Constants --------
   130
   131        /*! The DM6446 ARM Interrupt Controller supports 64 interrupts. */
   132        const Int NUM_INTERRUPTS = 64;
   133
   134        // -------- Module Types --------
   135
   136        /*! Hwi vector function type definition. */
   137        typedef Void (*VectorFuncPtr)(void);
   138
   139        /*!
   140         * ARM Interrupt Controller.
   141         */
   142        struct AINTC {
   143            UInt32 FIQ0;    /*! 0x00 Interrupt Status of INT [31:0] if mapped to FIQ */
   144            UInt32 FIQ1;    /*! 0x04 Interrupt Status of INT [63:32] if mapped to FIQ */
   145            UInt32 IRQ0;    /*! 0x08 Interrupt Status of INT [31:0] if mapped to IRQ */
   146            UInt32 IRQ1;    /*! 0x0C Interrupt Status of INT [63:32] if mapped to IRQ */
   147            UInt32 FIQENTRY;/*! 0x10 Entry Address [28:0] for valid FIQ interrupt */
   148            UInt32 IRQENTRY;/*! 0x14 Entry Address [28:0] for valid IRQ interrupt */
   149            UInt32 EINT0;   /*! 0x18 Interrupt Enable Register 0 */
   150            UInt32 EINT1;   /*! 0x1C Interrupt Enable Register 1 */
   151            UInt32 INTCTL;  /*! 0x20 Interrupt Operation Control Register */
   152            UInt32 EABASE;  /*! 0x24 Interrupt Entry Base Address */
   153            UInt32 RES[2];  /*! 0x28 reserved */
   154            UInt32 INTPR[8];/*! 0x30 Interrupt 0-7 Priority select */
   155    //      UInt32 INTPR1;  /*! 0x34 Interrupt 8-15 Priority select */
   156    //      UInt32 INTPR2;  /*! 0x38 Interrupt 16-23 Priority select */
   157    //      UInt32 INTPR3;  /*! 0x3C Interrupt 24-31 Priority select */
   158    //      UInt32 INTPR4;  /*! 0x40 Interrupt 32-39 Priority select */
   159    //      UInt32 INTPR5;  /*! 0x44 Interrupt 40-47 Priority select */
   160    //      UInt32 INTPR6;  /*! 0x48 Interrupt 48-55 Priority select */
   161    //      UInt32 INTPR7;  /*! 0x4C Interrupt 56-63 Priority select */
   162        };
   163
   164        /*!
   165         * Physical ARM Interrupt Controller Device.
   166         * Short name is "Hwi_aIntc"
   167         * Long name is "ti_sysbios_family_arm_dm6446_Hwi_aIntc"
   168         */
   169        extern volatile AINTC aIntc;
   170
   171        /*!
   172         *  ======== BasicView ========
   173         *  @_nodoc
   174         */
   175        metaonly struct BasicView {
   176            Ptr         halHwiHandle;
   177            String      label;
   178            Int         intNum;
   179            Int         priority;
   180            String      fxn;
   181            UArg        arg;
   182            Ptr         irp;
   183            String      status;
   184        };
   185
   186        /*!
   187         *  ======== ModuleView ========
   188         *  @_nodoc
   189         */
   190        metaonly struct ModuleView {
   191            String      options[4];
   192            SizeT       hwiStackPeak;
   193            SizeT       hwiStackSize;
   194            Ptr         hwiStackBase;
   195        };
   196
   197        /*!
   198         *  ======== rovViewInfo ========
   199         *  @_nodoc
   200         */
   201        @Facet
   202        metaonly config ViewInfo.Instance rovViewInfo =
   203            ViewInfo.create({
   204                viewMap: [
   205                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   206                    ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
   207                ]
   208            });
   209
   210        // -------- Module Parameters --------
   211
   212        /*! Reset Handler. Default is c_int00 */
   213        metaonly config VectorFuncPtr resetFunc;
   214
   215        /*! Undefined instruction exception handler. Default is self loop */
   216        metaonly config VectorFuncPtr undefinedInstFunc;
   217
   218        /*! SWI Handler. Default is internal SWI handler */
   219        metaonly config VectorFuncPtr swiFunc;
   220
   221        /*! Prefetch abort exception handler. Default is self loop */
   222        metaonly config VectorFuncPtr prefetchAbortFunc;
   223
   224        /*! Data abort exception handler. Default is self loop */
   225        metaonly config VectorFuncPtr dataAbortFunc;
   226
   227        /*! Reserved exception handler. Default is self loop */
   228        metaonly config VectorFuncPtr reservedFunc;
   229
   230        /*! IRQ interrupt handler. Default is internal IRQ dispatcher */
   231        metaonly config VectorFuncPtr irqFunc;
   232
   233        /*! FIQ interrupt handler. Default is internal FIQ dispatcher */
   234        metaonly config VectorFuncPtr fiqFunc;
   235
   236        /*!
   237         *  FIQ stack pointer. Default = null.
   238         *  (Indicates that stack is to be created using
   239         *  staticPlace()
   240         */
   241        config Ptr fiqStack = null;
   242
   243        /*!
   244         *  FIQ stack size in MAUs.
   245         *  Default is 1024 bytes.
   246         */
   247        metaonly config SizeT fiqStackSize = 1024;
   248
   249        /*!
   250         *  Memory section used for FIQ stack
   251         *  Default is null.
   252         */
   253        metaonly config String fiqStackSection = null;
   254
   255        /*!
   256         *  EABASE Size Setting. Default is 4 bytes per entry.
   257         *  Options are 4, 8, 16, 32 bytes per entry.
   258         */
   259        config Bits32 eabaseSize = 4;
   260
   261        /*!
   262         *  Error raised when Hwi is already defined
   263         */
   264        config Error.Id E_alreadyDefined = {
   265            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   266        };
   267
   268        /*!
   269         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   270         */
   271        config Log.Event LM_begin = {
   272            mask: Diags.USER1 | Diags.USER2,
   273            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   274        };
   275
   276        /*!
   277         *  Issued just after return from Hwi function (with interrupts disabled)
   278         */
   279        config Log.Event LD_end = {
   280            mask: Diags.USER2,
   281            msg: "LD_end: hwi: 0x%x"
   282        };
   283
   284
   285        // -------- Module Functions --------
   286
   287        /*!
   288         *  ======== disable ========
   289         */
   290        @Macro
   291        override UInt disable();
   292
   293        /*!
   294         *  ======== enable ========
   295         */
   296        @Macro
   297        override UInt enable();
   298
   299        /*!
   300         *  ======== restore ========
   301         */
   302        @Macro
   303        override Void restore(UInt key);
   304
   305        /*!
   306         *  @_nodoc
   307         *  ======== inUseMeta ========
   308         *  Check for Hwi already in use.
   309         *  For internal SYS/BIOS use only.
   310         *  Should be called prior to any internal Hwi.create().
   311         *
   312         *  @param(intNum)  interrupt number
   313         */
   314        metaonly Bool inUseMeta(UInt intNum);
   315
   316        /*!
   317         *  ======== getHandle ========
   318         *  Returns pointer to Hwi instance object.
   319         *
   320         *  @param(intNum)  interrupt number
   321         */
   322        @DirectCall
   323        Object *getHandle(UInt intNum);
   324
   325        /*!
   326         *  @_nodoc
   327         *  ======== getInstance ========
   328         *  Returns pointer to Hwi instance object.
   329         *
   330         *  @param(intNum)  interrupt number
   331         */
   332        @DirectCall
   333        Object *getInstance(UInt intNum);
   334
   335        /*!
   336         *  ======== enableFIQ ========
   337         *  Enable FIQ interrupts.
   338         *
   339         *  @b(returns)     previous FIQ interrupt enable/disable state
   340         */
   341        @DirectCall
   342        UInt enableFIQ();
   343
   344        /*!
   345         *  ======== disableFIQ ========
   346         *  Disable FIQ interrupts.
   347         *
   348         *  @b(returns)     previous FIQ interrupt enable/disable state
   349         */
   350        @DirectCall
   351        UInt disableFIQ();
   352
   353        /*!
   354         *  ======== restoreFIQ ========
   355         *  Restore FIQ interrupts.
   356         *
   357         *  @param(key)     enable/disable state to restore
   358         */
   359        @DirectCall
   360        Void restoreFIQ(UInt key);
   361
   362        /*!
   363         *  ======== enableIRQ ========
   364         *  Enable IRQ interrupts.
   365         *
   366         *  @param(key)     enable/disable state to restore
   367         */
   368        @DirectCall
   369        UInt enableIRQ();
   370
   371        /*!
   372         *  ======== disableIRQ ========
   373         *  Disable IRQ interrupts.
   374         *
   375         *  @b(returns)     previous IRQ interrupt enable/disable state
   376         */
   377        @DirectCall
   378        UInt disableIRQ();
   379
   380        /*!
   381         *  ======== restoreIRQ ========
   382         *  Restore IRQ interrupts.
   383         *
   384         *  @param(key)     enable/disable state to restore
   385         */
   386        @DirectCall
   387        Void restoreIRQ(UInt key);
   388
   389        /*!
   390         *  ======== disableEINT0 ========
   391         *  Disable specific interrupts (0-31).
   392         *
   393         *  Disables specific interrupts by clearing the bits specified by
   394         *  'mask' in the EINT0.
   395         *
   396         *  @param(mask)    bitmask of interrupts to disable
   397         *  @b(returns)     previous EINT0 settings bitmask
   398         */
   399        @DirectCall
   400        Bits32 disableEINT0(Bits32 mask);
   401
   402        /*!
   403         *  ======== disableEINT1 ========
   404         *  Disable specific interrupts (32-63).
   405         *
   406         *  Disables specific interrupts by clearing the bits specified by
   407         *  'mask' in the EINT1.
   408         *
   409         *  @param(mask)    bitmask of interrupts to disable
   410         *  @b(returns)     previous EINT1 settings bitmask
   411         */
   412        @DirectCall
   413        Bits32 disableEINT1(Bits32 mask);
   414
   415        /*!
   416         *  ======== enableEINT0 ========
   417         *  Enable specific interrupts (0-31).
   418         *
   419         *  Enables specific interrupts by clearing the bits specified by
   420         *  'mask' in the EINT0.
   421         *
   422         *  @param(mask)    bitmask of interrupts to disable
   423         *  @b(returns)     previous EINT0 settings bitmask
   424         */
   425        @DirectCall
   426        Bits32 enableEINT0(Bits32 mask);
   427
   428        /*!
   429         *  ======== enableEINT1 ========
   430         *  Enable specific interrupts (32-63).
   431         *
   432         *  Enables specific interrupts by clearing the bits specified by
   433         *  'mask' in the EINT0.
   434         *
   435         *  @param(mask)    bitmask of interrupts to disable
   436         *  @b(returns)     previous EINT0 settings bitmask
   437         */
   438        @DirectCall
   439        Bits32 enableEINT1(Bits32 mask);
   440
   441        /*!
   442         *  ======== restoreEINT0 ========
   443         *  Restore maskable interrupts to the state they were in
   444         *  when either disableEINT0() or enableEINT0() was called.
   445         *
   446         *  Simply writes mask to the EINT0 register.
   447         *
   448         *  @param(mask)    bitmask of interrupts to restore
   449         *  @b(returns)     previous EINT0 settings bitmask
   450         */
   451        @DirectCall
   452        Bits32 restoreEINT0(Bits32 mask);
   453
   454        /*!
   455         *  ======== restoreEINT1 ========
   456         *  Restore maskable interrupts to the state they were in
   457         *  when either disableEINT1() or enableEINT1() was called.
   458         *
   459         *  Simply writes mask to the EINT1 register.
   460         *
   461         *  @param(mask)    bitmask of interrupts to restore
   462         *  @b(returns)     previous EINT1 settings bitmask
   463         */
   464        @DirectCall
   465        Bits32 restoreEINT1(Bits32 mask);
   466
   467        /*!
   468         *  ======== setPriority ========
   469         *  Set an interrupt's relative priority.
   470         *
   471         *  Priority 0-1 define the interrupt as an FIQ interrupt
   472         *  Priority 2-7 define the interrupt as an IRQ interrupt
   473         *
   474         *  @param(intNum)      ID of interrupt
   475         *  @param(priority)    priority
   476         */
   477        @DirectCall
   478        Void setPriority(UInt intNum, UInt priority);
   479
   480    instance:
   481
   482        /*! disableMask0. default is derived from MaskingOption_SELF maskSetting. */
   483        config Bits32 disableMask0 = 0;
   484
   485        /*! disableMask1. default is derived from MaskingOption_SELF maskSetting. */
   486        config Bits32 disableMask1 = 0;
   487
   488        /*! restoreMask0. default is derived from MaskingOption_SELF maskSetting. */
   489        config Bits32 restoreMask0 = 0;
   490
   491        /*! restoreMask1. default is derived from MaskingOption_SELF maskSetting. */
   492        config Bits32 restoreMask1 = 0;
   493
   494        /*!
   495         *  Interrupt priority (0-7). Default is 7 which is the
   496         *  lowest priority IRQ interrupt.
   497         */
   498        override config Int priority = 7;
   499
   500        /*!
   501         *  ======== reconfig ========
   502         *  Reconfigure a dispatched interrupt.
   503         */
   504        @DirectCall
   505        Void reconfig(FuncPtr fxn, const Params *params);
   506
   507    internal:   /* not for client use */
   508
   509        /*
   510         * Swi and Task module function pointers.
   511         * Used to decouple Hwi from Swi and Task when
   512         * dispatcherSwiSupport or
   513         * dispatcherTaskSupport is false.
   514         */
   515        config UInt (*swiDisable)();
   516        config Void (*swiRestoreHwi)(UInt);
   517        config UInt (*taskDisable)();
   518        config Void (*taskRestoreHwi)(UInt);
   519
   520        /* assembly code mode registers setup */
   521        Void init();
   522
   523        /* Interrupt Dispatcher assembly code wrapper */
   524        Void dispatchIRQ();
   525
   526        /* IRQ Interrupt Dispatcher */
   527        Void dispatchIRQC(Irp irp);
   528
   529        /* default FIQ Interrupt Dispatcher */
   530        Void dispatchFIQC();
   531
   532        /*!
   533         *  const array to hold all HookSet objects.
   534         */
   535        config HookSet hooks[length] = [];
   536
   537        /*! Meta World Only Hwi Configuration Object. */
   538        metaonly struct InterruptObj {
   539            Bool used;              /* Interrupt already defined? */
   540            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   541            FuncPtr fxn;            /* Dispatched ISR function */
   542        };
   543
   544        /*!
   545         * Meta-only array of interrupt objects.
   546         * This meta-only array of Hwi config objects is initialized
   547         * in Hwi.xs:module$meta$init().
   548         */
   549        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   550
   551        metaonly config Bool assignResetVector = true;
   552
   553        struct Instance_State {
   554            UInt        priority;       // Interrupt Priority
   555            Bits32      disableMask0;   // EINT0 disable mask
   556            Bits32      disableMask1;   // EINT1 disable mask
   557            Bits32      restoreMask0;   // EINT0 restore mask
   558            Bits32      restoreMask1;   // EINT1 restore mask
   559            UArg        arg;            // Argument to Hwi function.
   560            FuncPtr     fxn;            // Hwi function.
   561            Int         intNum;         // Interrupt number
   562            Irp         irp;            // current IRP
   563            Ptr         hookEnv[];
   564        };
   565
   566        struct Module_State {
   567            Bits32      eint0Mask;      // Initial EINT0 mask
   568            Bits32      eint1Mask;      // Initial EINT1 mask
   569            UInt        irp;            // temporary irp storage for IRQ handler
   570            Char        *taskSP;        // temporary storage of interrupted
   571                                        // Task's SP during ISR execution
   572
   573            /* ROM */
   574            Char        *isrStack;      // Points to isrStack address
   575            Ptr         isrStackBase;   // _stack
   576            Ptr         isrStackSize;   // _STACK_SIZE
   577            Char        fiqStack[];     // buffer used for FIQ stack
   578            SizeT       fiqStackSize;
   579
   580            Handle      dispatchTable[NUM_INTERRUPTS];
   581                                        // dispatch table
   582        };
   583    }
   584
   585    /*
   586     *  @(#) ti.sysbios.family.arm.dm6446; 2, 0, 0, 0,237; 6-15-2011 16:24:17; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   587
   588     */
   589


package ti.sysbios.family.arm.dm6446

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *  dm6446 target-specific modules
    36     *
    37     */
    38
    39    requires ti.sysbios.interfaces;
    40
    41    /*!
    42     *  ======== ti.sysbios.family.arm.dm6446 ========
    43     *  Contains specifications for the dm6446 device-specific SYS/BIOS functions.
    44     *
    45     */
    46    package ti.sysbios.family.arm.dm6446 [2,0,0,0] {
    47        module Hwi;
    48        module TimerSupport;
    49        module Clobber;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arm.dm6446; 2, 0, 0, 0,237; 6-15-2011 16:24:18; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


C6000 DSP/BIOS Register Usage

C6x Register Usage

Arm9 DSP/BIOS Register Usage

This document provides a table describing the various Arm9 targets register conventions in terms of preservation across multi-threaded context switching and preconditions.

Overview

In a multi-threaded application using DSP/BIOS, it is necessary to know which registers can or cannot be modified. Furthermore, users need to understand which registers need to be saved/restored across a function call or an interrupt.

The following definitions describe the various possible register handling behaviors:

  • Scratch register. These registers are saved/restored by the Hwi dispatcher with temporary register bit masks.
  • Preserved register. These registers are saved/restored during a Task context switch.
  • Initialized register. These registers are set to a particular value during Hwi processing and restored to their incoming value upon exiting from the interrupt routine.
  • Read-Only register. These registers may be read but must not be modified.
  • Global register. These registers are shared across all threads in the system. To make a temporary change, save the register, make the change, and then restore it.
  • Other. These registers do not fit into one of the categories above.

Register Conventions

Table 1 Register and Status Bit Handling

Register

Status Bit

Register or Status Bit Name

Type

Notes

R0-R3, R12

General purpose registers

Scratch

R4-R11

General purpose registers

Preserved

R13 (SP)

Stack pointer

Initialized

Hwi dispatcher sets to Hwi stack before calling ISR

R14 (LR)

Link Register

Preserved

PSR

Program Status Register

N,Z,C,V

Condition Codes

Preserved

Q

Overflow

Preserved

GE[3:0]

Condition Codes

Preserved

E

Endian bit

Preserved

Untouched

A

Imprecise Abort Disable

Preserved

Untouched

I

IRQ Disable

Global

Hwi_enable/disable/restore operate on this bit

F

FIQ Disable

Preserved

?The FIQ bit is preserved and untouched by BIOS

M[4:0]

Mode bits

Other

BIOS sets the mode bits to System Mode (0b11111) during startup and prior to invoking a Hwi thread.

T

Thumb

Global

BIOS fully supports Arm/Thumb inter-working.

J

Jazelle

Preserved

Untouched

R13_svc

Supervisor mode R13

Other

? Untouched

R14_svc

Supervisor mode R14

Other

? Untouched

SPSR_svc

Supervisor mode SPSR

Other

? Untouched

R13_abt

Abort mode R13

Other

? Untouched

R14_abt

Abort mode R14

Other

? Untouched

SPSR_abt

Abort mode SPSR

Other

? Untouched

R13_und

Undefined mode R13

Other

? Untouched

R14_und

Undefined mode R14

Other

? Untouched

SPSR_und

Undefined mode SPSR

Other

? Untouched

R13_irq

Interrupt mode R13

Initialized

? BIOS sets to top of IRQ stack buffer (Hwi.irqStack)

R14_irq

Interrupt mode R14

Other

? During ISR, points to interrupt return address

SPSR_iq

Interrupt mode SPSR

Other

? Untouched

R8_fiq-R12_fiq

FIQ banked registers

Other

Untouched

R13_fiq

FIQ mode R13

Initialized

? BIOS sets to top of FIQ stack buffer (Hwi.fiqStack)

R14_fiq

FIQ mode R14

Other

? Untouched

SPSR_fiq

FIQ mode SPSR

Other

? Untouched

Notes:

.


module ti.sysbios.family.arm.ducati.Core

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Core.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.ducati;
    38
    39    import xdc.runtime.Error;
    40
    41    /*!
    42     *  ======== Core ========
    43     *  Core Identification Module.
    44     *
    45     *  The Core module is used to define which core within a dual core
    46     *  "Ducati" subsystem an application is being built for.
    47     *
    48     *  At runtime, a comparison is made between the configured Core.id
    49     *  and the value of PID0 (at address 0xe00fffe0). If they do not
    50     *  agree, an Error is raised.
    51     *
    52     *  Use of this module has the side effect of configuring default
    53     *  interrupt vector table placements for Core 0 and Core 1 if
    54     *  they haven't already been specified by the
    55     *  {@link ti.sysbios.family.arm.m3.Hwi#vectorTableAddress Hwi.vectorTableAddress}
    56     *  config parameter.
    57     *
    58     *  Core 0's default vector table placement is at 0x400.
    59     *
    60     *  Core 1's default vector table placement is at 0x800.
    61     */
    62
    63    @ModuleStartup          /* to configure static timers */
    64
    65    module Core
    66    {
    67        /*!
    68         *  Ducati Core ID, default is Core 0
    69         *
    70         *  Used for making static decisions based on Core ID
    71         */
    72        config UInt id = 0;
    73
    74        /*!
    75         *  Error raised if Core.id does not match the contents
    76         *  of PID0 (at 0xE00FFFE0).
    77         */
    78        config Error.Id E_mismatchedIds = {
    79            msg: "E_mismatchedIds: Core_Id: %d does not match hardware core Id: %d"
    80        };
    81
    82        /*!
    83         *  ======== getId ========
    84         *  Reads M3 core ID (0 or 1).
    85         *
    86         *  Used for making dynamic decisions based on Core ID
    87         *
    88         *  @b(returns)     core ID
    89         */
    90        @Macro
    91        UInt getId();
    92    }
    93
    94    /*
    95     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:20; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    96
    97     */
    98


module ti.sysbios.family.arm.ducati.CTM

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== CTM.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.ducati;
    38
    39    /*!
    40     *  ======== CTM ========
    41     *  Counter Timer Module Device Definitions.
    42     *
    43     *  For Ducati SYS/BIOS applications,
    44     *  Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18
    45     *  Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22
    46     *  Counters 2/3 are assigned to core 0's TimestampProvider
    47     *  Counters 4/5 are assigned to core 1's TimestampProvider
    48     *  Counters 6,7 are for application use.
    49     *
    50     *  Counters 2/3 and 4/5 are in chained mode and started simultaneously
    51     *  by core 0 so that both cores timestamps are in sync with each other
    52     *  AND both chained timers have independent SHADOW registers to guarantee
    53     *  64bit counter reading coherency.
    54     */
    55
    56    module CTM
    57    {
    58        /*!
    59         *  Counter Timer Module
    60         *  Physical Base address is 0x55080400
    61         *  Auto-configured virtual Base address is 0x40000400
    62         */
    63        struct CTM {
    64            UInt32 CTCNTL;          /*! 0x0000 */
    65            UInt32 RES_04 [7];      /*! 0x0004 - 0x0020 */
    66            UInt32 CTSTMCNTL;       /*! 0x0020 */
    67            UInt32 CTSTMMSTID;      /*! 0x0024 */
    68            UInt32 CTSTMINTVL;      /*! 0x0028 */
    69            UInt32 CTSTMSEL0;       /*! 0x002C */
    70            UInt32 CTSTMSEL1;       /*! 0x0030 */
    71            UInt32 RES_34 [3];      /*! 0x0034 - 0x0040 */
    72            UInt32 TINTVLR[8];      /*! 0x0040 - 0x0060 */
    73            UInt32 RES_60 [7];      /*! 0x0060 - 0x007C */
    74            UInt32 CTNUMDBG;        /*! 0x007C */
    75            UInt32 CTDBGSGL [8];    /*! 0x0080 - 0x00A0 */
    76            UInt32 RES_A0 [20];     /*! 0x00A0 - 0x00F0 */
    77            UInt32 CTGNBL [2];      /*! 0x00F0 - 0x00F8 */
    78            UInt32 CTGRST [2];      /*! 0x00F8 - 0x0100 */
    79            UInt32 CTCR [32];       /*! 0x0100 - 0x0180 */
    80            UInt32 CTCNTR [32];     /*! 0x0180 - 0x0200 */
    81        }
    82
    83        /*!
    84         * Physical CTM Device.
    85         * Short name is "CTM_ctm"
    86         * Long name is "ti_sysbios_family_arm.ducati_CTM_ctm"
    87         */
    88        extern volatile CTM ctm;
    89    }
    90
    91    /*
    92     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:20; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    93
    94     */
    95


module ti.sysbios.family.arm.ducati.GateDualCore

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateDualCore.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm.ducati;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    import xdc.runtime.Assert;
    41    import xdc.runtime.Error;
    42
    43    /*!
    44     *  ======== GateDualCore ========
    45     *  A Gate for use by the two Ducati M3 cores to manage shared resources.
    46     *
    47     *  GateDualCore uses disabling and enabling of interrupts as well as a shared
    48     *  variable between the two M3 cores as the resource locking
    49     *  mechanism. Such a gate guarantees exclusive access to a resource
    50     *  shared between the cores.
    51     *
    52     *  Each gate consumes one 32 bit word of shared memory.
    53     *  An array of these gates is shared between the two M3 cores and
    54     *  therefore the address of this array must be known to both (see
    55     *  {@link #gateArrayAddress}).
    56     *
    57     *  By default, the array has 4 entries (see {@link #numGates})
    58     *  and is placed immediately below Core 0's default interrupt
    59     *  vector table address. It is the responsibility of the user to
    60     *  configure both cores with the same array address and size.
    61     *
    62     *  @a(Restrictions)
    63     *  In a dual core M3 (Ducati) environment, core 0 is responsible
    64     *  for initializing the shared gate variable, therefore core 0
    65     *  must be brought up BEFORE core 1 invokes GateDualCore_enter().
    66     *  This can be achieved by simply running core 0 to its main()
    67     *  function prior to loading and running core 1.
    68     *
    69     *  GateDualCore does not support nesting of {@link #enter}/{@link #leave}
    70     *  calls.
    71     *
    72     *  Global interrupts are disabled upon return from GateDualCore_enter().
    73     *  The duration between the enter and leave should be as short as possible
    74     *  to minimize Hwi latency and stalls by the other M3 core.
    75     *
    76     *  Gate zero (0) is reserved for the {@link ti.sysbios.hal.unicache.Cache}
    77     *  module and is internally configured for its use.
    78     *  @a
    79     */
    80
    81    @Template("./GateDualCore.xdt")  /* generates gateArray */
    82    @ModuleStartup      /* generate a call to startup function */
    83    @InstanceInitError  /* create requires EB */
    84
    85    module GateDualCore inherits xdc.runtime.IGateProvider
    86    {
    87
    88        /*! @_nodoc */
    89        metaonly struct BasicView {
    90            String      label;
    91            UInt        index;
    92            String      owner;
    93            String      gateValue;
    94            UInt        stalls;
    95            UInt        noStalls;
    96            UInt        totalStalls;
    97            UInt        maxStall;
    98        };
    99
   100        @Facet
   101        metaonly config ViewInfo.Instance rovViewInfo =
   102            ViewInfo.create({
   103                viewMap: [
   104                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   105                ]
   106            });
   107
   108        /*! Assert if nested "enter" called. */
   109        config Assert.Id A_nestedEnter = {
   110            msg: "A_nestedEnter: Can't nest 'enter' calls."
   111        };
   112
   113        /*!
   114         *  Error raised if an invalid Gate index is provided
   115         */
   116        config Error.Id E_invalidIndex = {
   117            msg: "E_invalidIndex %d"
   118        };
   119
   120        /*!
   121         *  Error raised if a Gate is already in use
   122         */
   123        config Error.Id E_gateInUse = {
   124            msg: "E_gateInUse %d"
   125        };
   126
   127        /*!
   128         *  Base address of configurable Ducati Gate Array
   129         *
   130         *  Each gate consumes one 32 bit word of shared memory.
   131         *  The array is shared between the two M3 cores and therefore
   132         *  the address of this array must be the same for both.
   133         *
   134         *  By default, the array has 4 entries (see {@link #numGates})
   135         *  and is placed immediately below Core 1's default interrupt
   136         *  vector table address of 0x00000800 (see
   137         *  {@link ti.sysbios.family.arm.m3.Hwi#vectorTableAddress}).
   138         *
   139         *  Gate zero (0) is reserved for the
   140         *  {@link ti.sysbios.hal.unicache.Cache} module.
   141         */
   142        config Ptr gateArrayAddress = 0x000007f0;
   143
   144        /*!
   145         *  Number of Gates that can be created. Default is 4.
   146         *
   147         *  Each gate consumes one 32 bit word of memory.
   148         *  (see {@link #gateArrayAddress}).
   149         */
   150        config UInt numGates = 4;
   151
   152        /*!
   153         *  Gate initialize flag.
   154         *
   155         *  By default, core 0 initializes all of the
   156         *  gates in {@link #gateArray}.
   157         *  This behavior can be overridden by explicitly setting this
   158         *  flag within your config script.
   159         */
   160        config Bool initGates;
   161
   162        /*!
   163         *  Gate statistics collection flag. Default is disabled.
   164         */
   165        config bool enableStats = false;
   166
   167        /*!
   168         *  Shared array of gate variables.
   169         *
   170         *  This global variable is placed in its own data section
   171         *  and that section is placed at {@link #gateArrayAddress}.
   172         *
   173         *  The size of the array is determined by {@link #numGates}
   174         */
   175        extern UInt32 gateArray[numGates];
   176
   177    instance:
   178
   179        /*! index of the gate variable in the shared gateArray table */
   180        config UInt index = 0;
   181
   182        /*!
   183         *  @_nodoc
   184         *  ======== enter ========
   185         *  Enter this gate
   186         */
   187        @DirectCall
   188        override IArg enter();
   189
   190        /*!
   191         *  @_nodoc
   192         *  ======== leave ========
   193         *  Leave this gate
   194         */
   195        @DirectCall
   196        override Void leave(IArg key);
   197
   198        /*!
   199         *  Sync execution with the other M3 core.
   200         */
   201        @DirectCall
   202        Void sync();
   203
   204    internal:
   205
   206        struct Instance_State {
   207            UInt            index;
   208            volatile UInt32 *gatePtr;
   209            volatile UInt8  *gateBytePtr;
   210            /* below are for stats collection */
   211            UInt            stalls;
   212            UInt            noStalls;
   213            UInt            totalStalls;
   214            UInt            maxStall;
   215        };
   216
   217        struct Module_State {
   218            UInt8   usedGates[numGates];
   219        };
   220    }
   221    /*
   222     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:21; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   223
   224     */
   225


package ti.sysbios.family.arm.ducati

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.ducati ========
    40     *  Contains specifications for the Ducati device-specific SYS/BIOS functions.
    41     *
    42     *  The two M3 cores share a number of hardware and software resources.
    43     *
    44     *  The system software must carefully manage these resources when the
    45     *  dynamic loading of applications is required.
    46     *
    47     *  Below is a list of the shared resources that SYS/BIOS modules utilize and
    48     *  manage.
    49     *
    50     *  Shared resources:
    51     *
    52     *  AMMU
    53     *  @p(blist)
    54     *      -Must be configured before unicache is enabled.
    55     *      -Must have a page descriptor for EVERY memory address
    56     *       accessed by either core before unicache is enabled.
    57     *      -AMMU is configured statically, no runtime APIs to modify
    58     *       the AMMU configuration are provided.
    59     *      -Initialization is controlled by the
    60     *       {@link ti.sysbios.hal.ammu.AMMU#configureAmmu AMMU.configureAmmu} flag.
    61     *      -By default, this flag is true.
    62     *  @p
    63     *
    64     *  Unicache
    65     *  @p(blist)
    66     *      -Must be configured and enabled.
    67     *      -Runtime APIs use GateDualCore[0] to arbitrate shared unicache
    68     *       register usage.
    69     *      -Initialization is controlled by the
    70     *       {@link ti.sysbios.hal.unicache.Cache#configureCache Cache.configureCache} flag.
    71     *      -By default this flag is false.
    72     *  @p
    73     *
    74     *  CTM 2,3,4,5 used for timestamping
    75     *  @p(blist)
    76     *      -These counters are initialized by the
    77     *       {@link TimestampProvider TimestampProvider} module, which
    78     *       is used by the {@link xdc.runtime.Timestamp} module to provide
    79     *       timestamp services.
    80     *      -Must be configured and started.
    81     *      -Configured and started by whichever core comes up first
    82     *       and detects (by testing register contents) that the CTM
    83     *       hasn't been configured and started.
    84     *  @p
    85     *
    86     *  Reset Exception vector table (vectors 0-14)
    87     *  @p(blist)
    88     *      -The address of the Reset Exception vector table is shared by
    89     *       both cores.
    90     *      -Vectors 0 and 1 at addresses 0x0 are fetched each time
    91     *       a core is reset. At that time they must contain the SP and
    92     *       address of c_int00 for the core being reset.
    93     *      -Exception vectors 2-14 are used by each core until it has
    94     *       successfully configured its NVIC's Vector Table Offset Register (VTOR)
    95     *       to point to the vector table that will be used afterwards.
    96     *      -The Reset Exception vectors are required to be valid and unique
    97     *       to the core being reset in case an exception occurs prior to the
    98     *       VTOR being configured.
    99     *      -The Reset Exception vector table placement is controlled by the
   100     *       {@link ti.sysbios.family.arm.m3.Hwi#resetVectorAddress Hwi.resetVectorAddress}
   101     *       config parameter.
   102     *      -By default, both cores place their Reset Exception vector table
   103     *       at 0x00000000.
   104     *      -It is left to the system software design to guarantee
   105     *       that only one core is climbing up at a time.
   106     *  @p
   107     *
   108     *  Runtime Exception and Interrupt vector table (vectors 0-79)
   109     *  @p(blist)
   110     *      -The address of the Runtime Exception and Interrupt vector table
   111     *       should be unique to each core.
   112     *      -The Runtime Exception and Interrupt vector table
   113     *       placement is controlled by the
   114     *       {@link ti.sysbios.family.arm.m3.Hwi#vectorTableAddress Hwi.vectorTableAddress}
   115     *       config parameter.
   116     *      -Default behavior is that core 0 places its runtime vector table
   117     *       at 0x400 and core 1 places its runtime vector table at 0x800.
   118     *  @p
   119     *
   120     *  GateDualCore[0] is used by the unicache module.
   121     *  GateDualCore[1-n] can be used by applications to manage shared hardware/software resources
   122     *  @p(blist)
   123     *      -Initialization is controlled by the
   124     *       {@link GateDualCore#initGates GateDualCore.initGates} flag.
   125     *      -By default, core 0 initializes the gate objects.
   126     *  @p
   127     *
   128     */
   129    package ti.sysbios.family.arm.ducati [2,0,0,0] {
   130        module Core;
   131        module CTM;
   132        module GateDualCore;
   133        module Timer;
   134        module TimerSupport;
   135        module TimestampProvider;
   136        module Wugen;
   137    }
   138    /*
   139     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:22; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   140
   141     */
   142


module ti.sysbios.family.arm.ducati.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.ducati;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.family.arm.m3.Hwi;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Ducati Cortex M3 Timer Peripherals Manager.
    50     *
    51     *  The timers used in Ducati are the NVIC SysTick timer
    52     *  and the two CTM timers (0 and 1) that support interrupts.
    53     *  The CTM timers are shared between the two M3 cores.
    54     *  Core 0 uses CTM timer 0 and Core 1 uses timer 1.
    55     *  Each core then supports 2 timers.
    56     *  Timer 0 is the core's SysTick timer
    57     *  and Timer 1 is the core's CTM timer.
    58     *  Both timers are clocked at the CPU clock rate, nominally 200MHz.
    59     *  Timer 0 (the SysTick timer) has only 24 bits of period resolution
    60     *  (up to 83ms).
    61     *  Timer 1 (the CTM timer) supports a full 32 bit period
    62     *  (up to 21 seconds).
    63     *
    64     *  @p(html)
    65     *  <h3> Calling Context </h3>
    66     *  <table border="1" cellpadding="3">
    67     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    68     *
    69     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    70     *    <!--                                                                                                                 -->
    71     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    77     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    78     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    79     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    80     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    81     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    82     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    83     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    84     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    85     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    86     *    <tr><td colspan="6"> Definitions: <br />
    87     *       <ul>
    88     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    89     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    90     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    91     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    92     *           <ul>
    93     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    94     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    95     *             <li> During main().</li>
    96     *             <li> During BIOS.startupFxns.</li>
    97     *           </ul>
    98     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    99     *           <ul>
   100     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   101     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
   102     *           </ul>
   103     *       </ul>
   104     *    </td></tr>
   105     *
   106     *  </table>
   107     *  @p
   108     */
   109    @InstanceFinalize       /* To cleanup */
   110    @InstanceInitError      /* To report unavailability of timer */
   111    @ModuleStartup          /* to configure static timers */
   112
   113    module Timer inherits ti.sysbios.interfaces.ITimer
   114    {
   115        /*! Max value of Timer period for PeriodType_COUNTS*/
   116        const UInt MAX_PERIOD = 0xffffffff;
   117
   118        /*!
   119         *  Number of timer peripherals on chip
   120         *
   121         *  Only 2 are available to each core.
   122         */
   123        const Int NUM_TIMER_DEVICES = 2;
   124
   125        /*! Timer clock divider wrt cpu clock */
   126        const Int TIMER_CLOCK_DIVIDER = 1;
   127
   128        /*! @_nodoc
   129         *  Min instructions to use in trigger().
   130         */
   131        const Int MIN_SWEEP_PERIOD = 1;
   132
   133        /*! @_nodoc */
   134        @XmlDtd
   135        metaonly struct BasicView {
   136            Ptr         halTimerHandle;
   137            String      label;
   138            UInt        id;
   139            String      device;
   140            String      startMode;
   141            String      runMode;
   142            UInt        period;
   143            String      periodType;
   144            UInt        intNum;
   145            String      tickFxn[];
   146            UArg        arg;
   147            String      extFreq;
   148            String      hwiHandle;
   149        };
   150
   151
   152        /*! @_nodoc */
   153        metaonly struct ModuleView {
   154            String      availMask;      /* available 32-bit timer halves */
   155        }
   156
   157        /*! @_nodoc */
   158        metaonly struct DeviceView {
   159            UInt        id;
   160            String      device;
   161            String      devAddr;
   162            UInt        intNum;
   163            String      runMode;
   164            UInt        period;
   165            UInt        currCount;
   166            UInt        remainingCount;
   167        };
   168
   169        /*! @_nodoc */
   170        @Facet
   171        metaonly config ViewInfo.Instance rovViewInfo =
   172            ViewInfo.create({
   173                viewMap: [
   174                [
   175                    'Basic',
   176                    {
   177                        type: ViewInfo.INSTANCE,
   178                        viewInitFxn: 'viewInitBasic',
   179                        structName: 'BasicView'
   180                    }
   181                ],
   182                [
   183                    'Device',
   184                    {
   185                        type: ViewInfo.INSTANCE,
   186                        viewInitFxn: 'viewInitDevice',
   187                        structName: 'DeviceView'
   188                    }
   189                ],
   190                [
   191                    'Module',
   192                    {
   193                        type: ViewInfo.MODULE,
   194                        viewInitFxn: 'viewInitModule',
   195                        structName: 'ModuleView'
   196                    }
   197                ],
   198                ]
   199            });
   200
   201        /*!
   202         *  Error raised when timer id specified is not supported.
   203         */
   204        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   205
   206        /*!
   207         *  Error raised when timer requested is in use
   208         */
   209        config Error.Id E_notAvailable  =
   210            {msg: "E_notAvailable: Timer not available %d"};
   211
   212        /*!
   213         *  Error raised when period requested is not supported
   214         */
   215        config Error.Id E_cannotSupport  =
   216            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   217
   218        /*!
   219         *  ======== anyMask ========
   220         *  Available mask to be used when select = Timer_ANY
   221         */
   222        config UInt anyMask = 0x3;
   223
   224        /*!
   225         *  ======== getHandle ========
   226         *  Get Handle associated with a timer id.
   227         *
   228         *  @param(id)      timer Id.
   229         *  @b(returns)     timer Handle
   230         */
   231        @DirectCall
   232        Handle getHandle(UInt id);
   233
   234        /*!
   235         *  ======== oneShotStub ========
   236         *  @_nodoc
   237         *  SysTick timer does not support one shot mode. This stub stops timer
   238         *  and clears the pending timer interrupt.
   239         *
   240         *  @param(arg)     Timer object.
   241         */
   242        @DirectCall
   243        Void oneShotStub(UArg arg);
   244
   245        /*!
   246         *  ======== periodicStub ========
   247         *  @_nodoc
   248         *  SysTick timer interrupt must be acknowledged. This stub acknowledges timer
   249         *
   250         *  @param(arg)     Timer object.
   251         */
   252        @DirectCall
   253        Void periodicStub(UArg arg);
   254
   255    instance:
   256
   257        /*! Hwi Params for Hwi Object. Default is null. */
   258        config Hwi.Params *hwiParams = null;
   259
   260        /*!
   261         *  ======== reconfig ========
   262         *  Used to modify static timer instances at runtime.
   263         *
   264         *  @param(timerParams)     timer Params
   265         *  @param(tickFxn)         function that runs when timer expires
   266         */
   267        @DirectCall
   268        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   269
   270
   271    internal:   /* not for client use */
   272
   273        /*!
   274         *  ======== noStartupNeeded ========
   275         *  Flag used to prevent misc code from being brought in
   276         *  un-necessarily
   277         */
   278        config UInt startupNeeded = false;
   279
   280        struct Instance_State {
   281            Bool            staticInst;
   282            Int             id;
   283            Int             ctmid;          /* CTM counter ID */
   284            RunMode         runMode;
   285            StartMode       startMode;
   286            UInt            period;
   287            PeriodType      periodType;
   288            UInt            intNum;
   289            UArg            arg;
   290            Hwi.FuncPtr     tickFxn;
   291            Types.FreqHz    extFreq;        /* external frequency in Hz */
   292            Hwi.Handle      hwi;
   293        }
   294
   295        struct Module_State {
   296            UInt            availMask;      /* available peripherals */
   297            Handle          handles[NUM_TIMER_DEVICES];
   298                                            /* array of handles based on id */
   299        }
   300    }
   301
   302    /*
   303     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:21; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   304
   305     */
   306


module ti.sysbios.family.arm.ducati.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.ducati;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    /*!
    42     *  ======== TimestampProvider ========
    43     *  Ducati Cortex M3 TimestampProvider delegate for use
    44     *  with {@link xdc.runtime.Timestamp}
    45     *
    46     *  The timestamp counters used in Ducati are CTM counters 2,3,4,5.
    47     *  Each core uses two counters in chained mode to achieve 64 bits.
    48     *  Core 0 uses counters 2,3.
    49     *  Core 1 uses counters 4,5.
    50     *  Which ever core is started first will start both sets of counters
    51     *  synchronously so that both cores effectively share a common timestamp.
    52     *  By default, the CTM counters are clocked at 2 times the CPU clock.
    53     *
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    59     *
    60     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    61     *    <!--                                                                                                                 -->
    62     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *
    66     *  </table>
    67     *  @p
    68     */
    69
    70    @ModuleStartup          /* To get Clock Timer Handle */
    71
    72    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    73    {
    74
    75        /*! @_nodoc */
    76        metaonly struct ModuleView {
    77            String      timestamp;
    78        }
    79
    80        @Facet
    81        metaonly config ViewInfo.Instance rovViewInfo =
    82            ViewInfo.create({
    83                viewMap: [
    84                [
    85                    'Module',
    86                    {
    87                        type: ViewInfo.MODULE,
    88                        viewInitFxn: 'viewInitModule',
    89                        structName: 'ModuleView'
    90                    }
    91                ],
    92                ]
    93            });
    94
    95        /*!
    96         * Counter Input Select. The default value of 0 selects the
    97         * 2x CPU clock as the clock source for the timestamp counters.
    98         *
    99         * See Table 28-22 of the OMAP4430 TRM for details of the
   100         * various events that can be counted.
   101         */
   102        config UInt8 inpsel = 0;
   103    }
   104    /*
   105     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:22; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   106
   107     */
   108


module ti.sysbios.family.arm.ducati.Wugen

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Wugen.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.ducati;
    39
    40    /*!
    41     *  ======== Wugen ========
    42     *  Wugen Module
    43     *
    44     *  Unconstrained Functions
    45     *  All functions
    46     *
    47     *  @p(html)
    48     *  <h3> Calling Context </h3>
    49     *  <table border="1" cellpadding="3">
    50     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    51     *
    52     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    53     *    <!--                                                                                                                 -->
    54     *    <tr><td> {@link #disableInterrupt}</td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    55     *    <tr><td> {@link #enableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    56     *    <tr><td colspan="6"> Definitions: <br />
    57     *       <ul>
    58     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    59     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    60     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    61     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    62     *           <ul>
    63     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    64     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    65     *             <li> During main().</li>
    66     *             <li> During BIOS.startupFxns.</li>
    67     *           </ul>
    68     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    69     *           <ul>
    70     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    71     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    72     *           </ul>
    73     *       </ul>
    74     *    </td></tr>
    75     *
    76     *  </table>
    77     *  @p
    78     */
    79
    80    @ModuleStartup
    81
    82    module Wugen
    83    {
    84        /*!
    85         *  ======== disableInterrupt ========
    86         *  Disables the specified interrupt in the WUGEN
    87         *
    88         *  @param(intNum)  the interrupt number
    89         */
    90        Void disableInterrupt(UInt intNum);
    91
    92        /*!
    93         *  ======== enableInterrupt ========
    94         *  Enables the specified interrupt in the WUGEN
    95         *
    96         *  @param(intNum)  the interrupt number
    97         */
    98        Void enableInterrupt(UInt intNum);
    99    }
   100    /*
   101     *  @(#) ti.sysbios.family.arm.ducati; 2, 0, 0, 0,244; 6-15-2011 16:24:22; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   102
   103     */
   104


module ti.sysbios.family.arm.ducati.dm8148.IntMux

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== IntMux.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.ducati.dm8148;
    38
    39    import xdc.runtime.Assert;
    40    import xdc.runtime.Error;
    41
    42    import ti.sysbios.interfaces.IHwi;
    43
    44    /*!
    45     *  ======== IntMux ========
    46     *  IntMux Module
    47     *
    48     *  Below is an example of how to override the default mapping of
    49     *  interrupt 42 so that it is sourced by I2CINT2 rather than its
    50     *  default mapping to I2CINT1:
    51     *
    52     *  @p(code)
    53     *  #include <ti/sysbios/family/arm/m3/Hwi.h>
    54     *  #include <ti/sysbios/family/arm/ducati/dm8148/IntMux.h>
    55     *
    56     *  Void myI2CINT2Handler(UArg arg)
    57     *  {
    58     *      System_printf("I2CINT2 arg = %d\n", (UInt)arg);
    59     *  }
    60     *
    61     *  Int main(Int argc, Char* argv[])
    62     *  {
    63     *      Hwi_Params params;
    64     *
    65     *      Hwi_Params_init(&params);
    66     *
    67     *      // set IntMux 19 to event number 4 (I2CINT2)
    68     *      IntMux_setEvent(19, 4);
    69     *
    70     *      // create a corresponding interrupt handler
    71     *      // notice that Ducati interrupt number 42 corresponds to IntMux 19
    72     *
    73     *      params.arg = 42; // pass the Int number to the handler for demo
    74     *
    75     *      Hwi_create(42, myI2CINT2Handler, &params, NULL);
    76     *
    77     *      BIOS_start();
    78     *
    79     *      return (0);
    80     *  }
    81     *  @p
    82     *
    83     *  Here is how you would define the same interrupt handler statically
    84     *  in a configuration script:
    85     *
    86     *  @p(code)
    87     *  var Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
    88     *  var IntMux = xdc.useModule('ti.sysbios.family.arm.ducati.dm8148.IntMux');
    89     *
    90     *  IntMux.setEventMeta(19, 4);
    91     *
    92     *  var hwiParams = new Hwi.Params();
    93     *  hwiParams.arg = 42;
    94     *  Program.global.staticHwi = Hwi.create(42, '&myI2CINT2Handler', hwiParams);
    95     *  @p
    96     *
    97     *  @p(html)
    98     *  <h3> Calling Context </h3>
    99     *  <table border="1" cellpadding="3">
   100     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   101     *
   102     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   103     *    <!--                                                                                                                 -->
   104     *    <tr><td> {@link #setEvent}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   105     *    <tr><td colspan="6"> Definitions: <br />
   106     *       <ul>
   107     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   108     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   109     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   110     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   111     *           <ul>
   112     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
   113     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   114     *             <li> During main().</li>
   115     *             <li> During BIOS.startupFxns.</li>
   116     *           </ul>
   117     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   118     *           <ul>
   119     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   120     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
   121     *           </ul>
   122     *       </ul>
   123     *    </td></tr>
   124     *
   125     *  </table>
   126     *  @p
   127     */
   128
   129    module IntMux
   130    {
   131
   132        /*!
   133         *  Assert if interrupt number > 56
   134         */
   135        config Assert.Id A_badIntNum = {
   136            msg: "A_badIntNum: intNum must be <= 56"
   137        };
   138
   139        /*!
   140         *  Assert if event number > 47
   141         */
   142        config Assert.Id A_badEventNum = {
   143            msg: "A_badIntNum: eventNum must be <= 47"
   144        };
   145
   146        /*!
   147         *  Address of "DUCATI_INTMUX_0_3" register
   148         */
   149        config Ptr intMuxBaseAddr = 0x48140F54;
   150
   151
   152        /*!
   153         *  ======== setEventMeta ========
   154         *  Set the event number associated with an interrupt.
   155         *
   156         *  Statically sets the event number associated with
   157         *  an interrupt in the Ducati Interrupt Mux as described
   158         *  in section 5.9.2 of the Centaurus Architecture Spec.
   159         *
   160         *  @param(intNum)    The intMux number (0-56)
   161         *  @param(eventNum)  The event number (0-47)
   162         */
   163        metaonly Void setEventMeta(UInt intMuxNum, UInt eventNum);
   164
   165        /*!
   166         *  ======== setEvent ========
   167         *  Set the event number associated with an interrupt.
   168         *
   169         *  Dynamically sets the event number associated with
   170         *  an interrupt in the Ducati Interrupt Mux as described
   171         *  in section 5.9.2 of the Centaurus Architecture Spec.
   172         *
   173         *  @param(intNum)    The intMux number (0-56)
   174         *  @param(eventNum)  The event number (0-47)
   175         */
   176        @DirectCall
   177        Void setEvent(UInt intMuxNum, UInt eventNum);
   178
   179    internal:
   180
   181        /*
   182         *  ======== initIntMux ========
   183         */
   184        Void initIntMux();
   185
   186        config UInt8 intMux[57];   // table of INTMUX events
   187    }
   188    /*
   189     *  @(#) ti.sysbios.family.arm.ducati.dm8148; 2, 0, 0, 0,79; 6-15-2011 16:24:22; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   190
   191     */
   192


package ti.sysbios.family.arm.ducati.dm8148

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.family.arm.ducati.dm8148 ========
    39     *  Contains dm8148 Hwi helper module
    40     */
    41    package ti.sysbios.family.arm.ducati.dm8148 [2,0,0,0] {
    42        module IntMux;
    43    }
    44    /*
    45     *  @(#) ti.sysbios.family.arm.ducati.dm8148; 2, 0, 0, 0,79; 6-15-2011 16:24:22; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    46
    47     */
    48


package ti.sysbios.family.arm.ducati.omap4430

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.family.arm.ducati.omap4430 ========
    39     *  Contains specifications for the Ducati, on OMAP4430.
    40     *
    41     */
    42    package ti.sysbios.family.arm.ducati.omap4430 [1,0,0,0] {
    43        module Power;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.ducati.omap4430; 1, 0, 0, 0,110; 6-15-2011 16:24:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


module ti.sysbios.family.arm.ducati.omap4430.Power

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Power.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.ducati.omap4430;
    39
    40    import ti.sysbios.family.arm.ducati.GateDualCore;
    41
    42    /*!
    43     *  ======== Power ========
    44     *  Power support for Ducati on OMAP4430.
    45     */
    46    module Power
    47    {
    48        /*! Suspend arguments structure. */
    49        struct SuspendArgs {
    50            Bool pmMasterCore;     /*! Master core for suspend/resume? */
    51            Bool rendezvousResume; /*! Rendezvous before resume? */
    52            Int dmaChannel;        /*! SDMA channel for L2 RAM save; -1=CPU copy */
    53            UInt intMask31_0;     /*! Mask of interrupts (31-0) able to wake WFI */
    54            UInt intMask63_32;    /*! Mask of interrupts (63-32) able to wake WFI */
    55            UInt intMask79_64;    /*! Mask of interrupts (79-64) able to wake WFI */
    56        };
    57
    58        /*! Physical address of L2 RAM */
    59        const Ptr L2RAM = 0x55020000;
    60
    61        /*! Base address of SDMA registers */
    62        config Ptr sdmaRegs = 0x4A056000;
    63
    64        /*! Rendezvous Gate index */
    65        config UInt rendezvousGateIndex = 1;
    66
    67        /*! Idle the CPU when threads blocked waiting for an interrupt? */
    68        config Bool idle = false;
    69
    70        /*! Segment to load Power's shared reset code and data */
    71        metaonly config String loadSegment = "EXT_SHARED_RAM";
    72
    73        /*!
    74         *  ======== idleCPU ========
    75         *  Function used to automatically idle the CPU in the Idle loop.
    76         *
    77         *  When the 'idle' configuration parameter is set, this function will
    78         *  be added to the list of Idle loop functions.  When called from the
    79         *  Idle loop, it will invoke the wait for interrupt (WFI) instruction,
    80         *  to idle the CPU until the next interrupt occurs.
    81         */
    82        @DirectCall
    83        Void idleCPU();
    84
    85        /*!
    86         *  ======== suspend ========
    87         *  Function used for suspend/resume of the M3 cores.
    88         *
    89         *  Precondition and usage constraints:
    90         *
    91         *  1) Before this function is called the application must disable all
    92         *     interrupts that are not desired to wake the CPU from WFI while
    93         *     waiting for the core domain to go off.
    94         *
    95         *  2) For those interrupts that are desired to wake the CPU from WFI (for
    96         *     example, the mailbox interrupt), these interrupts cannot be generated
    97         *     until the Power_suspend API has reached the point of executing WFI.
    98         *     If the interrupts happen early, while this API is saving context,
    99         *     the resulting context may be stale, and the application may not
   100         *     resume correctly.  Two global flags (one for each M3 core) are
   101         *     assert immediately before invoking WFI; the wakeup interrupts
   102         *     should not be asserted until these flags are asserted (non-zero):
   103         *          ti_sysbios_family_arm_ducati_omap4430_readyIdleCore0
   104         *          ti_sysbios_family_arm_ducati_omap4430_readyIdleCore1
   105         */
   106        @DirectCall
   107        UInt suspend(SuspendArgs * args);
   108
   109    internal:
   110
   111        struct Struct8 {
   112            UInt32 a0;
   113            UInt32 a1;
   114            UInt32 a2;
   115            UInt32 a3;
   116            UInt32 a4;
   117            UInt32 a5;
   118            UInt32 a6;
   119            UInt32 a7;
   120        }
   121
   122        struct Struct10 {
   123            UInt32 a0;
   124            UInt32 a1;
   125            UInt32 a2;
   126            UInt32 a3;
   127            UInt32 a4;
   128            UInt32 a5;
   129            UInt32 a6;
   130            UInt32 a7;
   131            UInt32 a8;
   132            UInt32 a9;
   133        }
   134
   135        struct TablePIDS {
   136            UInt32 PID1;
   137            UInt32 PID2;
   138        }
   139
   140        struct IPRxRegs {
   141            UInt32 IPR0;
   142            UInt32 IPR1;
   143            UInt32 IPR2;
   144            UInt32 IPR3;
   145            UInt32 IPR4;
   146            UInt32 IPR5;
   147            UInt32 IPR6;
   148            UInt32 IPR7;
   149            UInt32 IPR8;
   150            UInt32 IPR9;
   151            UInt32 IPR10;
   152            UInt32 IPR11;
   153            UInt32 IPR12;
   154            UInt32 IPR13;
   155            UInt32 IPR14;
   156            UInt32 IPR15;
   157        }
   158
   159        struct CfgRegs {
   160            UInt32 VTOR;
   161            UInt32 AIRCR;
   162            UInt32 SCR;
   163            UInt32 CCR;
   164            UInt32 SHPR0;
   165            UInt32 SHPR4;
   166            UInt32 SHPR8;
   167            UInt32 SHCSR;
   168        }
   169
   170        struct NVICContext {
   171            UInt32 AUXCTRL;
   172            UInt32 STCSR;
   173            UInt32 STRVR;
   174            UInt32 ISER0;
   175            UInt32 ISER1;
   176            IPRxRegs iprRegs;
   177            CfgRegs cfgRegs;
   178        }
   179
   180        struct ContextAMMU {
   181            UInt32 largeAddr[4];
   182            UInt32 largeXlteAddr[4];
   183            UInt32 largePolicy[4];
   184            UInt32 medAddr[2];
   185            UInt32 medXlteAddr[2];
   186            UInt32 medPolicy[2];
   187            Struct10 smallAddr;
   188            Struct10 smallXlteAddr;
   189            Struct10 smallPolicy;
   190            UInt32 mmuConfig;
   191        }
   192
   193        struct ContextCTM {
   194            UInt32 CNTL;
   195            UInt32 STMCNTL;
   196            UInt32 STMMSTID;
   197            UInt32 STMINTVL;
   198            UInt32 STMSEL0;
   199            UInt32 TINTVLR0;
   200            UInt32 TINTVLR1;
   201            UInt32 GNBL0;
   202            Struct8 control;
   203        }
   204
   205        struct CpuRegs {
   206            UInt32 R4;
   207            UInt32 R5;
   208            UInt32 R6;
   209            UInt32 R7;
   210            UInt32 R8;
   211            UInt32 R9;
   212            UInt32 R10;
   213            UInt32 R11;
   214            UInt32 LR;
   215            UInt32 CONTROL;
   216            UInt32 BASEPRI;
   217            UInt32 MSP;
   218            UInt32 pSP;
   219        }
   220
   221        struct PrivateContext {
   222            CpuRegs privateCPU;
   223            NVICContext privateNVIC;
   224            TablePIDS privatePIDS;
   225        }
   226
   227        struct UnicacheConfig {
   228            UInt32 L1_CONFIG;
   229            UInt32 L1_OCP;
   230        }
   231
   232        struct SubsystemContext {
   233            UnicacheConfig cacheConfig;
   234            ContextAMMU ammuConfig;
   235            ContextCTM ctmConfig;
   236        }
   237
   238        struct DucatiContext {
   239            PrivateContext masterContext;
   240            PrivateContext slaveContext;
   241            SubsystemContext ssContext;
   242        }
   243
   244        struct SdmaRegs {
   245            volatile UInt32 CCR;
   246            UInt32 CLNK;
   247            UInt32 CICR;
   248            UInt32 CSR;
   249            UInt32 CSDP;
   250            UInt32 CEN;
   251            UInt32 CFN;
   252            UInt32 CSSA;
   253            UInt32 CDSA;
   254            UInt32 CSEI;
   255            UInt32 CSFI;
   256            UInt32 CDEI;
   257            UInt32 CDFI;
   258        }
   259
   260        /*! Rendezvous Gate handle */
   261        config GateDualCore.Handle rendezvousGate;
   262
   263        /*!
   264         *  ======== resetFxn ========
   265         *  Function used for resume upon reset of M3 cores.
   266         */
   267        Void resetFxn();
   268
   269        /*!
   270         *  ======== saveCpuRegs ========
   271         *  Function used to save parent-preserved CPU register context, assert
   272         *  ready to idle flag, and invoke WFI.
   273         */
   274        UInt32 saveCpuRegs(Ptr saveAddress, Ptr readyFlag);
   275
   276    }
   277
   278    /*
   279     *  @(#) ti.sysbios.family.arm.ducati.omap4430; 1, 0, 0, 0,110; 6-15-2011 16:24:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   280
   281     */
   282


module ti.sysbios.family.arm.exc.Exception

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Exception.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.exc;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Error;
    42
    43    import ti.sysbios.BIOS;
    44
    45    /*!
    46     *  ======== Exception ========
    47     *  Exception Module
    48     *
    49     *  The Exception module is a basic ARM exception handler.
    50     *  No attempt is made to return from an exception as these are
    51     *  generally fatal in nature.
    52     *
    53     *  When used, the Exception module will override the default
    54     *  exception handlers provided by the current Hwi module.
    55     */
    56
    57    @ModuleStartup          /* generates call to Exception_Module_startup at startup */
    58    module Exception
    59    {
    60        /*! Exception hook function type definition. */
    61        typedef Void (*ExceptionHookFuncPtr)(ExcContext *);
    62
    63        /* Exception types */
    64        enum Type {
    65            Type_Supervisor = 0x13,         /*! Supervisor (SWI). */
    66            Type_PreAbort   = 0x17,         /*! Abort exception. */
    67            Type_DataAbort  = 0x18,         /*! Abort exception. */
    68            Type_UndefInst  = 0x1b          /*! Undefined instruction exception. */
    69        };
    70
    71        /*!
    72         *  Exception Context - Register contents at the time of an exception.
    73         */
    74        struct ExcContext {
    75            /* Thread Context */
    76            BIOS.ThreadType threadType; /* Type of thread executing at */
    77                                        /* the time the exception occurred */
    78            Ptr     threadHandle;       /* Handle to thread executing at */
    79                                        /* the time the exception occurred */
    80            Ptr     threadStack;        /* Address of stack contents of thread */
    81                                        /* executing at the time the exception */
    82                                        /* occurred */
    83            SizeT   threadStackSize;    /* size of thread stack */
    84
    85            Type    type;
    86
    87            /* Internal Registers */
    88            Ptr     r0;
    89            Ptr     r1;
    90            Ptr     r2;
    91            Ptr     r3;
    92            Ptr     r4;
    93            Ptr     r5;
    94            Ptr     r6;
    95            Ptr     r7;
    96            Ptr     r8;
    97            Ptr     r9;
    98            Ptr     r10;
    99            Ptr     r11;
   100            Ptr     r12;
   101            Ptr     sp;
   102            Ptr     lr;
   103            Ptr     pc;
   104            Ptr     psr;
   105        }
   106
   107        @Facet
   108        metaonly config ViewInfo.Instance rovViewInfo =
   109            ViewInfo.create({
   110                viewMap: [
   111                    ['Basic',
   112                        {
   113                            type: ViewInfo.TREE,
   114                            viewInitFxn: 'viewInitBasic',
   115                            structName: 'ExcContext'
   116                        }
   117                    ]
   118                ]
   119            });
   120
   121        /*! Error raised when a SWI exception occurs */
   122        config Error.Id E_swi = {
   123            msg: "E_swi: pc = 0x%08x, lr = 0x%08x."
   124        };
   125
   126        /*! Error raised when an prefetch abort exception occurs */
   127        config Error.Id E_prefetchAbort = {
   128            msg: "E_prefetchAbort: pc = 0x%08x, lr = 0x%08x."
   129        };
   130
   131        /*! Error raised when an data abort exception occurs */
   132        config Error.Id E_dataAbort = {
   133            msg: "E_dataAbort: pc = 0x%08x, lr = 0x%08x."
   134        };
   135
   136        /*! Error raised when an undefined instruction exception occurs */
   137        config Error.Id E_undefinedInstruction = {
   138            msg: "E_undefinedInstruction: pc = 0x%08x, lr = 0x%08x."
   139        };
   140
   141        /*!
   142         *  Enable full exception decoding, default is true.
   143         *
   144         *  When enabled, the exception handler will fully
   145         *  decode an exception and dump the registers to the
   146         *  system console.
   147         *
   148         *  When set to false, only an Error is printed on the console.
   149         *
   150         *  In either case, the full exception context is always
   151         *  saved and visible with ROV.
   152         */
   153        config Bool enableDecode = true;
   154
   155        /*!
   156         *  Exception stack pointer. Default = null.
   157         *  (Indicates that stack is to be created using
   158         *  staticPlace()
   159         */
   160        config Ptr excStack = null;
   161
   162        /*!
   163         * Exception stack size in MAUs.
   164         * Default is 128 bytes.
   165         */
   166        metaonly config SizeT excStackSize = 128;
   167
   168        /*!
   169         *  Memory section used for Exception stack
   170         *  Default is null.
   171         */
   172        metaonly config String excStackSection = null;
   173
   174        /*!
   175         *  User Exception Context Buffer Address
   176         *
   177         *  By default, when an exception occurs, an {@link #ExcContext}
   178         *  structure is allocated on the ISR stack and filled in within the
   179         *  exception handler.
   180         *
   181         *  If {@link #excContextBuffer} is initialized by the user, the
   182         *  {@link #ExcContext} structure will be placed at that address instead.
   183         *
   184         *  The buffer must be large enough to contain an {@link #ExcContext}
   185         *  structure.
   186         */
   187        metaonly config Ptr excContextBuffer;
   188
   189        /*!
   190         *  User Exception Stack Buffer Address
   191         *
   192         *  By default, when an exception occurs, a pointer to the base address
   193         *  of the stack being used by the thread causing the exception is placed
   194         *
   195         *  If {@link #excStackBuffer} is initialized by the user, the
   196         *  stack contents of the thread causing the exception will be
   197         *  copied to that address instead.
   198         *
   199         *  The buffer must be large enough to contain the largest task stack or ISR
   200         *  stack defined in the application.
   201         */
   202        metaonly config Ptr excStackBuffer;
   203
   204        /*!
   205         *  User Exception hook function.
   206         *
   207         *  Called just after exception context has been initialized.
   208         */
   209        config ExceptionHookFuncPtr excHookFunc = null;
   210
   211    internal:   /* not for client use */
   212
   213        /* assembly code mode registers setup */
   214        Void init();
   215
   216        /*!
   217         *  ======== excHandlerAsm ========
   218         *  asm code common exception handler
   219         */
   220        Void excHandlerAsm();
   221
   222        /*!
   223         *  ======== excHandlerDataAsm ========
   224         *  asm code Data Abort exception handler
   225         */
   226        Void excHandlerDataAsm();
   227
   228        /*!
   229         *  ======== excHandler ========
   230         *  C function exception Handler
   231         */
   232        Void excHandler(UInt *excStack, UInt lr);
   233
   234        /*!
   235         *  ======== excDumpContext ========
   236         */
   237        Void excDumpContext(UInt pc);
   238
   239        struct Module_State {
   240            Bool        excActive;          // TRUE if an exception has occurred
   241            ExcContext  *excContext;        // Exception context
   242            Ptr         excStackBuffer;     // where to copy thread's stack
   243            Char        excStack[];         // buffer used for exception stack
   244            SizeT       excStackSize;
   245        };
   246    }
   247    /*
   248     *  @(#) ti.sysbios.family.arm.exc; 2, 0, 0, 0,72; 6-15-2011 16:24:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   249
   250     */
   251


package ti.sysbios.family.arm.exc

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.exc ========
    40     *  Contains the ARM Exception handler used by all non-M3 ARM targets.
    41     */
    42    package ti.sysbios.family.arm.exc [2,0,0,0] {
    43        module Exception;
    44    }
    45    /*
    46     *  @(#) ti.sysbios.family.arm.exc; 2, 0, 0, 0,72; 6-15-2011 16:24:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    47
    48     */
    49


package ti.sysbios.family.arm.f28m35x

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *
    36     *  The link below provides SYS/BIOS C28x register usage information:
    37     *
    38     *      {@link ./doc-files/c28regconv.html SYS/BIOS C28x Register Usage}
    39     *
    40     *! Open Issues:
    41     *  @p(blist)
    42     *      - System_printf() issue. Args need to be cast as UInt16
    43     *      - PLL not set ot 150MHz. Who whould do this? Gel OK?
    44     *      - Disable watchdog. Gel OK?
    45     *      - Hwi needs to be revisited wrt PIE
    46     *      - Task stack should be in lower memory. How to ensure?
    47     *      - Testcases need x28 specific config to build
    48     *      - UArg data type is different in SYS/BIOS 6 compared to DSP/BIOS 5.20.
    49     *      Old was Void *, New is intptr_t. Old was treated by codegen
    50     *      as a pointer and passed in XAR regs. New is treated as 32 bit
    51     *      data and passed in ACC. Effects Task_glue().
    52     *  @p
    53     */
    54
    55    /*!
    56     *  ======== ti.sysbios.family.c28 ========
    57     *  Contains specifications for the C28 specific SYS/BIOS functions.
    58     *
    59     */
    60    package ti.sysbios.family.arm.f28m35x [2,0,0,0]{
    61        module TimestampProvider;
    62    }
    63    /*
    64     *  @(#) ti.sysbios.family.arm.f28m35x; 2, 0, 0, 0,8; 6-15-2011 16:24:30; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    65
    66     */
    67


module ti.sysbios.family.arm.f28m35x.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.f28m35x;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     *
    76     */
    77
    78
    79    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    80    {
    81
    82    internal:
    83
    84        const UInt32 MIPCCOUNTERL = 0x400FB718;
    85        const UInt32 MIPCCOUNTERH = 0x400FB71C;
    86
    87    }
    88
    89    /*
    90     *  @(#) ti.sysbios.family.arm.f28m35x; 2, 0, 0, 0,8; 6-15-2011 16:24:30; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    91
    92     */
    93


package ti.sysbios.family.arm.lm3

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *  Stellaris LM3SXXX target-specific modules
    36     *
    37     */
    38
    39    requires ti.sysbios.interfaces;
    40
    41    /*!
    42     *  ======== ti.sysbios.family.arm.lm3 ========
    43     *  Contains specifications for the Stellaris LM3S family of device-specific SYS/BIOS functions.
    44     *
    45     */
    46    package ti.sysbios.family.arm.lm3 [2,0,0,0] {
    47        module TimestampProvider;
    48        module Timer;
    49    }
    50    /*
    51     *  @(#) ti.sysbios.family.arm.lm3; 2, 0, 0, 0,172; 6-15-2011 16:24:32; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    52
    53     */
    54


module ti.sysbios.family.arm.lm3.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.lm3;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.family.arm.m3.Hwi;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Luminary Micro LM3 Timer Peripheral Driver
    50     *
    51     *  @p(html)
    52     *  <h3> Calling Context </h3>
    53     *  <table border="1" cellpadding="3">
    54     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    55     *
    56     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    57     *    <!--                                                                                                                 -->
    58     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    59     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    60     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    61     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    62     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    63     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    64     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td colspan="6"> Definitions: <br />
    74     *       <ul>
    75     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    76     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    77     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    78     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    79     *           <ul>
    80     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    81     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    82     *             <li> During main().</li>
    83     *             <li> During BIOS.startupFxns.</li>
    84     *           </ul>
    85     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    86     *           <ul>
    87     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    88     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    89     *           </ul>
    90     *       </ul>
    91     *    </td></tr>
    92     *
    93     *  </table>
    94     *  @p
    95     */
    96    @InstanceFinalize       /* To cleanup */
    97    @InstanceInitError      /* To report unavailability of timer */
    98    @ModuleStartup          /* to configure static timers */
    99
   100    module Timer inherits ti.sysbios.interfaces.ITimer
   101    {
   102        /*! Max value of Timer period for PeriodType_COUNTS*/
   103        const UInt MAX_PERIOD = 0xffffffff;
   104
   105        /*! Timer clock divider wrt cpu clock */
   106        const Int TIMER_CLOCK_DIVIDER = 1;
   107
   108        /*! @_nodoc
   109         *  Min instructions to use in trigger().
   110         */
   111        const Int MIN_SWEEP_PERIOD = 1;
   112
   113        /*! @_nodoc */
   114        @XmlDtd
   115        metaonly struct BasicView {
   116            Ptr         halTimerHandle;
   117            String      label;
   118            UInt        id;
   119            String      device;
   120            String      startMode;
   121            String      runMode;
   122            UInt        period;
   123            String      periodType;
   124            UInt        intNum;
   125            String      tickFxn[];
   126            UArg        arg;
   127            String      extFreq;
   128            String      hwiHandle;
   129        };
   130
   131
   132        /*! @_nodoc */
   133        metaonly struct ModuleView {
   134            String      availMask;      /* available 32-bit timer halves */
   135        }
   136
   137        /*! @_nodoc */
   138        metaonly struct DeviceView {
   139            UInt        id;
   140            String      device;
   141            String      devAddr;
   142            UInt        intNum;
   143            String      runMode;
   144            UInt        period;
   145            UInt        currCount;
   146            UInt        remainingCount;
   147            String      state;
   148        };
   149
   150        /*! @_nodoc */
   151        @Facet
   152        metaonly config ViewInfo.Instance rovViewInfo =
   153            ViewInfo.create({
   154                viewMap: [
   155                [
   156                    'Basic',
   157                    {
   158                        type: ViewInfo.INSTANCE,
   159                        viewInitFxn: 'viewInitBasic',
   160                        structName: 'BasicView'
   161                    }
   162                ],
   163                [
   164                    'Device',
   165                    {
   166                        type: ViewInfo.INSTANCE,
   167                        viewInitFxn: 'viewInitDevice',
   168                        structName: 'DeviceView'
   169                    }
   170                ],
   171                [
   172                    'Module',
   173                    {
   174                        type: ViewInfo.MODULE,
   175                        viewInitFxn: 'viewInitModule',
   176                        structName: 'ModuleView'
   177                    }
   178                ],
   179                ]
   180            });
   181
   182        /*!
   183         *  Error raised when timer id specified is not supported.
   184         */
   185        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   186
   187        /*!
   188         *  Error raised when timer requested is in use
   189         */
   190        config Error.Id E_notAvailable  =
   191            {msg: "E_notAvailable: Timer not available %d"};
   192
   193        /*!
   194         *  Error raised when period requested is not supported
   195         */
   196        config Error.Id E_cannotSupport  =
   197            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   198
   199        /*!
   200         *  ======== anyMask ========
   201         *  Available mask to be used when select = Timer_ANY
   202         */
   203        config UInt anyMask = 0x3;
   204
   205        /*!
   206         *  ======== getHandle ========
   207         *  Get Handle associated with a timer id.
   208         *
   209         *  @param(id)      timer Id.
   210         *  @b(returns)     timer Handle
   211         */
   212        @DirectCall
   213        Handle getHandle(UInt id);
   214
   215        /*!
   216         *  ======== isrStub ========
   217         *  @_nodoc
   218         *  Timer interrupts must be acknowledged
   219         *
   220         *  @param(arg)     Timer object.
   221         */
   222        @DirectCall
   223        Void isrStub(UArg arg);
   224
   225    instance:
   226
   227        /*! Hwi Params for Hwi Object. Default is null. */
   228        config Hwi.Params *hwiParams = null;
   229
   230        /*!
   231         *  ======== reconfig ========
   232         *  Used to modify static timer instances at runtime.
   233         *
   234         *  @param(timerParams)     timer Params
   235         *  @param(tickFxn)         function that runs when timer expires
   236         */
   237        @DirectCall
   238        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   239
   240
   241    internal:   /* not for client use */
   242
   243        /*
   244         *  ======== noStartupNeeded ========
   245         *  Flag used to prevent misc code from being brought in
   246         *  un-necessarily
   247         */
   248        config UInt startupNeeded = false;
   249
   250        /*! Information about timer */
   251        struct TimerDevice {
   252            UInt intNum;
   253            Ptr  baseAddr;
   254        };
   255
   256        /*!
   257         *  ======== numTimerDevices ========
   258         *  The number of logical timers on a device.
   259         */
   260        config Int numTimerDevices;
   261
   262        /*!
   263         *  ======== WRALLOW ========
   264         *  Write protection register for critical registers;
   265         */
   266        config Ptr WRALLOW = null;
   267
   268        /*
   269         *  ======== enableTimers ========
   270         *  enable timer register access
   271         *  called as a Startup.firstFxnw
   272         */
   273        Void enableTimers();
   274
   275        struct Instance_State {
   276            Bool            staticInst;
   277            Int             id;
   278            RunMode         runMode;
   279            StartMode       startMode;
   280            UInt            period;
   281            PeriodType      periodType;
   282            UInt            intNum;
   283            UArg            arg;
   284            Hwi.FuncPtr     tickFxn;
   285            Types.FreqHz    extFreq;        /* external frequency in Hz */
   286            Hwi.Handle      hwi;
   287        }
   288
   289        struct Module_State {
   290            UInt            availMask;      /* available peripherals */
   291            TimerDevice     device[];       /* timer device information */
   292            Handle          handles[];      /* array of handles based on id */
   293        }
   294    }
   295
   296    /*
   297     *  @(#) ti.sysbios.family.arm.lm3; 2, 0, 0, 0,172; 6-15-2011 16:24:31; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   298
   299     */
   300


module ti.sysbios.family.arm.lm3.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.lm3;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  Implements ITimestampProvider
    43     *
    44     *  Cortex M3 TimestampProvider delegate for use
    45     *  with {@link xdc.runtime.Timestamp}.
    46     *
    47     *  The SysTick timer is used as the timestamp source.
    48     *
    49     *  @p(html)
    50     *  <h3> Calling Context </h3>
    51     *  <table border="1" cellpadding="3">
    52     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    53     *
    54     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    55     *    <!--                                                                                                                 -->
    56     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td colspan="6"> Definitions: <br />
    60     *       <ul>
    61     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    62     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    63     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    64     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    65     *           <ul>
    66     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    67     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    68     *             <li> During main().</li>
    69     *             <li> During BIOS.startupFxns.</li>
    70     *           </ul>
    71     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    72     *           <ul>
    73     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    74     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    75     *           </ul>
    76     *       </ul>
    77     *    </td></tr>
    78     *  </table>
    79     *  @p
    80     */
    81
    82    @ModuleStartup
    83
    84    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    85    {
    86        /*!
    87         *  Set this parameter when you want TimestampProvider to use
    88         *  the same timer as the Clock module.
    89         *
    90         *  This parameter overrides the {@link #timerId} setting.
    91         */
    92        config Bool useClockTimer = false;
    93
    94        /*!
    95         *  TimestampProvider timer id.
    96         *
    97         *  When not using the Clock timer, TimestampProvider will
    98         *  create an {@link Timer} using this timer id.
    99         */
   100        config UInt timerId = Timer.ANY;
   101
   102        /*!@_nodoc
   103         *  Internal use. Function that starts timer before main
   104         */
   105        @DirectCall
   106        Void startTimer();
   107
   108        /*!@_nodoc
   109         *  Internal use. Timer rollover interrupt handler.
   110         */
   111        @DirectCall
   112        Void rolloverFunc(UArg unused);
   113
   114    internal:   /* not for client use */
   115
   116        struct Module_State {
   117            Timer.Handle    timer;          /* timer instance used */
   118            volatile UInt32 hi;             /* upper 32 bits */
   119        }
   120    }
   121    /*
   122     *  @(#) ti.sysbios.family.arm.lm3; 2, 0, 0, 0,172; 6-15-2011 16:24:32; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   123
   124     */
   125


module ti.sysbios.family.arm.m3.Exception

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Exception.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.m3;
    38
    39
    40    /*!
    41     *  ======== Exception ========
    42     *  (Deprecated!) Exception Module
    43     *
    44     *  Do not use this module!
    45     *
    46     *  The functionality of the Exception module has been fully integrated
    47     *  into the {@link Hwi} module.
    48     *
    49     *  The Exception module is a basic Cortex M3 exception handler.
    50     *  No attempt is made to return from an exception as these are
    51     *  generally fatal in nature.
    52     *
    53     *  When used, the Exception module will override the default
    54     *  exception handlers provided by the {@link Hwi} module.
    55     *  This can be done by adding the following to your configuration
    56     *  script:
    57     *
    58     *  @p(code)
    59     *  Exception = xdc.useModule('ti.sysbios.family.m3.Exception');
    60     *  @p
    61     */
    62
    63    metaonly module Exception
    64    {
    65
    66        /*!
    67         *  If true, use System_printf() to dump exception context.
    68         */
    69        config Bool doPrint = false;
    70    }
    71    /*
    72     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:36; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    73
    74     */
    75


module ti.sysbios.family.arm.m3.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32
    33    /*
    34     *  ======== Hwi.xdc ========
    35     *
    36     */
    37    package ti.sysbios.family.arm.m3;
    38
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Diags;
    41    import xdc.runtime.Log;
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Error;
    44
    45    import ti.sysbios.BIOS;
    46    import ti.sysbios.interfaces.IHwi;
    47
    48    /*!
    49     *  ======== Hwi ========
    50     *  Cortex M3 Hardware Interrupt Manager
    51     *
    52     *  The Cortex M3's Nested Vectored Interrupt Controller (NVIC)
    53     *  supports up to 256 interrupts/exceptions. In practice, most
    54     *  devices support much fewer (ie the Stellaris family of devices
    55     *  have only 80 total interrupts defined).
    56     *
    57     *  SYS/BIOS Interrupt IDs or interrupt numbers correspond
    58     *  to an interrupt's position in the interrupt vector table.
    59     *
    60     *  ID 0 corresponds to vector 0 which is used by the NVIC
    61     *  to hold the initial (reset) stack pointer value.
    62     *
    63     *  ID 1 corresponds to vector 1 which is the reset vector (ie _c_int00)
    64     *
    65     *  IDs 2-14 are hardwired to exceptions.
    66     *
    67     *  ID 15 is the SysTick timer interrupt.
    68     *
    69     *  ID's 16-255 are mapped to the NVIC's user interrupts 0-239
    70     *  which are tied to platform specific interrupt sources.
    71     *
    72     *  The M3 Hwi module supports "zero latency" interrupts.
    73     *  Interrupts configured with priority greater (in priority,
    74     *  lower in number) than {@link #disablePriority}
    75     *  are NOT disabled by {@link #disable}.
    76     *
    77     *  Zero latency interrupts are not handled by the SYS/BIOS interrupt
    78     *  dispatcher. Instead, they are vectored to directly.
    79     *  As such, and because they are not masked by {@link #disable},
    80     *  these interrupt handlers are severely restricted in terms of the
    81     *  SYS/BIOS APIs they can invoke and THREAD SAFETY MUST BE CAREFULLY
    82     *  CONSIDERED!
    83     *
    84     *  Due to the M3's native automatic stacking of saved-by-caller C
    85     *  context on the way to an ISR, zero latency interrupt handlers
    86     *  are implemented using regular C functions (ie no 'interrupt'
    87     *  keyword is required).
    88     *
    89     *  Zero latency interrupts are distinguished from regular dispatched
    90     *  interrupts at create time by their priority being greater than
    91     *  {@link #disablePriority}.
    92     *
    93     *  Note that since zero latency interrupts don't use the dispatcher,
    94     *  the {@link ti.sysbios.interfaces.IHwi#arg arg} parameter is not
    95     *  functional.
    96     *
    97     *  @a(Interrupt Masking Options)
    98     *
    99     *  The NVIC interrupt controller is designed for priority based
   100     *  interrupts.
   101     *
   102     *  No support is provided for anything but {@link #MaskingOption_LOWER}.
   103     *
   104     *  @a(Interrupt Priorities)
   105     *
   106     *  In general, the NVIC supports priority values of 0 thru 255.
   107     *
   108     *  In practice valid priorities values are device dependent and their
   109     *  nesting behaviors depend on the {@link #priGroup} setting.
   110     *
   111     *  Priority 0 is the highest priority and by default is
   112     *  reserved for zero latency interrupts
   113     *  (see {@link #disablePriority}).
   114     *
   115     *  See the Cortex M3 architecture reference manual for details
   116     *  on the behavior of interrupt priorities and their relationship
   117     *  to the {@link #priGroup} setting.
   118     *
   119     *  @a(Interrupt Vector Tables)
   120     *  Stellaris devices:
   121     *
   122     *  By default, two vector tables are created for Stellaris devices:
   123     *
   124     *  A 16 entry boot vector table is placed at address 0x00000000 in
   125     *  FLASH.
   126     *
   127     *  An 80 entry vector table is placed at address 0x20000000 in RAM.
   128     *
   129     *  The FLASH boot vector table contains the reset vector and exception
   130     *  handler vectors used until the RAM based vector table is initialized.
   131     *
   132     *  The RAM vector table contains the 16 exception vectors as well as all
   133     *  the 64 user interrupt vectors.
   134     *
   135     *  During system startup, the NVIC Vector Table Offset Registor is
   136     *  intialized to point to this vector table after the table has been
   137     *  initialized.
   138     *
   139     *  @a( )
   140     *  Dual M3 Core ('Ducati') devices:
   141     *
   142     *  By default, Ducati core 0 places its runtime vector table at address
   143     *  0x00000400 and core 1 places its runtime vector table at address
   144     *  0x00000800.
   145     *
   146     *  Additionally, a boot vector table is placed at address
   147     *  0x00000000 which is shared by both cores.
   148     *
   149     *  The boot reset vector function determines which core it is being
   150     *  executed on and jumps to the reset vector contained in its corresponding
   151     *  runtime vector table.
   152     *
   153     *  The generation and placement of these vector tables is made
   154     *  automatically when the
   155     *  {@link ti.sysbios.family.arm.ducati.Core} module is used.
   156     *
   157     *  Although STRONGLY discouraged, this default behavior can be overridden
   158     *  by explicitly setting the
   159     *  {@link #resetVectorAddress Hwi.resetVectorAddress} and
   160     *  {@link #vectorTableAddress Hwi.vectorTableAddress} config parameters.
   161     *
   162     *  @a(Restrictions)
   163     *  When used within a dual M3 core (Ducati) arrangement, care must be
   164     *  taken when initializing this shared resource.
   165     *  The "Shared Resources" note provided
   166     *  in the {@link ti.sysbios.family.arm.ducati ducati} package discusses
   167     *  the management of the various hardware and software resources
   168     *  shared by the two M3 cores.
   169     *  @a
   170     *
   171     *  @p(html)
   172     *  <h3> Calling Context </h3>
   173     *  <table border="1" cellpadding="3">
   174     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   175     *
   176     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   177     *    <!--                                                                                                                 -->
   178     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   179     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   180     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   181     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   182     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   183     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   184     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   185     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   186     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   187     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   188     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   189     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   190     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   191     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   192     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   193     *    <tr><td colspan="6"> Definitions: <br />
   194     *       <ul>
   195     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   196     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   197     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   198     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   199     *           <ul>
   200     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   201     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   202     *             <li> During main().</li>
   203     *             <li> During BIOS.startupFxns.</li>
   204     *           </ul>
   205     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   206     *           <ul>
   207     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   208     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   209     *           </ul>
   210     *       </ul>
   211     *    </td></tr>
   212     *
   213     *  </table>
   214     *  @p
   215     */
   216
   217
   218    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   219    @ModuleStartup      /* generate a call to startup function */
   220
   221    module Hwi inherits ti.sysbios.interfaces.IHwi
   222    {
   223        // -------- Module Constants --------
   224
   225        /*!
   226         *  The Cortex M3 NVIC supports up to 256 interrupts/exceptions.
   227         *
   228         *  The actual number supported is device specific and provided by
   229         *  the catalog device specification.
   230         */
   231        readonly config Int NUM_INTERRUPTS;
   232
   233        /*!
   234         *  The Cortex M3 NVIC supports up to 256 interrupt priorities.
   235         *
   236         *  The actual number supported is device specific and provided by
   237         *  the catalog device specification.
   238         */
   239        readonly config Int NUM_PRIORITIES;
   240
   241        // -------- Module Types --------
   242
   243        /*! Hwi vector function type definition. */
   244        typedef Void (*VectorFuncPtr)(void);
   245
   246        /*! Exception hook function type definition. */
   247        typedef Void (*ExceptionHookFuncPtr)(ExcContext *);
   248
   249        /*! NVIC Configuration Control Register (CCR). */
   250        struct CCR {
   251            Bits8 STKALIGN;         /*! Auto stack alignment in exception */
   252            Bits8 BFHFNMIGN;        /*! All faults ignore BUS Faults */
   253            Bits8 DIV_0_TRP;        /*! Trap on divide be zero */
   254            Bits8 UNALIGN_TRP;      /*! Trap on all unaligned accesses */
   255            Bits8 USERSETMPEND;     /*! Allow user to trigger interrupts */
   256            Bits8 NONEBASETHRDENA;  /*! Allow entering thread mode anytime */
   257        };
   258
   259        /*! @_nodoc
   260         * Nested Vectored Interrupt Controller.
   261         */
   262        struct NVIC {
   263            UInt32 RES_00;       /*! 0xE000E000 reserved */
   264            UInt32 ICTR;         /*! 0xE000E004 Interrupt Control Type */
   265            UInt32 RES_08;       /*! 0xE000E008 reserved */
   266            UInt32 RES_0C;       /*! 0xE000E00C reserved */
   267            UInt32 STCSR;        /*! 0xE000E010 SysTick Control & Status Register */
   268            UInt32 STRVR;        /*! 0xE000E014 SysTick Reload Value Register */
   269            UInt32 STCVR;        /*! 0xE000E018 SysTick Current Value Register */
   270            UInt32 STCALIB;      /*! 0xE000E01C SysTick Calibration Value Register */
   271            UInt32 RES_20 [56];  /*! 0xE000E020-0xE000E0FC reserved */
   272            UInt32 ISER [8];     /*! 0xE000E100-0xE000E11C Interrupt Set Enable Registers */
   273            UInt32 RES_120 [24]; /*! 0xE000E120-0xE000E17C reserved */
   274            UInt32 ICER [8];     /*! 0xE000E180-0xE000E19C Interrupt Clear Enable Registers */
   275            UInt32 RES_1A0 [24]; /*! 0xE000E1A0-0xE000E1FC reserved */
   276            UInt32 ISPR [8];     /*! 0xE000E200-0xE000E21C Interrupt Set Pending Registers */
   277            UInt32 RES_220 [24]; /*! 0xE000E220-0xE000E7C reserved */
   278            UInt32 ICPR [8];     /*! 0xE000E280-0xE000E29C Interrupt Clear Pending Registers */
   279            UInt32 RES_2A0 [24]; /*! 0xE000E2A0-0xE000E2FC reserved */
   280            UInt32 IABR [8];     /*! 0xE000E300-0xE000E31C Interrupt Active Bit Registers */
   281            UInt32 RES_320 [56]; /*! 0xE000E320-0xE000E3FC reserved */
   282            UInt8  IPR [240];    /*! 0xE000E400-0xE000E4EF Interrupt Priority Registers */
   283            UInt32 RES_4F0 [516];/*! 0xE000E4F0-0xE000ECFC reserved */
   284            UInt32 CPUIDBR;      /*! 0xE000ED00 CPUID Base Register */
   285            UInt32 ICSR;         /*! 0xE000ED04 Interrupt Control State Register */
   286            UInt32 VTOR;         /*! 0xE000ED08 Vector Table Offset Register */
   287            UInt32 AIRCR;        /*! 0xE000ED0C Application Interrupt/Reset Control Register */
   288            UInt32 SCR;          /*! 0xE000ED10 System Control Register */
   289            UInt32 CCR;          /*! 0xE000ED14 Configuration Control Register */
   290            UInt8  SHPR[12];     /*! 0xE000ED18 System Handlers 4-15 Priority Registers */
   291            UInt32 SHCSR;        /*! 0xE000ED24 System Handler Control & State Register */
   292            UInt8  MMFSR;        /*! 0xE000ED28 Memory Manage Fault Status Register */
   293            UInt8  BFSR;         /*! 0xE000ED29 Bus Fault Status Register */
   294            UInt16 UFSR;         /*! 0xE000ED2A Usage Fault Status Register */
   295            UInt32 HFSR;         /*! 0xE000ED2C Hard Fault Status Register */
   296            UInt32 DFSR;         /*! 0xE000ED30 Debug Fault Status Register */
   297            UInt32 MMAR;         /*! 0xE000ED34 Memory Manager Address Register */
   298            UInt32 BFAR;         /*! 0xE000ED38 Bus Fault Address Register */
   299            UInt32 AFSR;         /*! 0xE000ED3C Auxiliary Fault Status Register */
   300            UInt32 PFR0;         /*! 0xE000ED40 Processor Feature Register */
   301            UInt32 PFR1;         /*! 0xE000ED44 Processor Feature Register */
   302            UInt32 DFR0;         /*! 0xE000ED48 Debug Feature Register */
   303            UInt32 AFR0;         /*! 0xE000ED4C Auxiliary Feature Register */
   304            UInt32 MMFR0;        /*! 0xE000ED50 Memory Model Fault Register0 */
   305            UInt32 MMFR1;        /*! 0xE000ED54 Memory Model Fault Register1 */
   306            UInt32 MMFR2;        /*! 0xE000ED58 Memory Model Fault Register2 */
   307            UInt32 MMFR3;        /*! 0xE000ED5C Memory Model Fault Register3 */
   308            UInt32 ISAR0;        /*! 0xE000ED60 ISA Feature Register0 */
   309            UInt32 ISAR1;        /*! 0xE000ED64 ISA Feature Register1 */
   310            UInt32 ISAR2;        /*! 0xE000ED68 ISA Feature Register2 */
   311            UInt32 ISAR3;        /*! 0xE000ED6C ISA Feature Register3 */
   312            UInt32 ISAR4;        /*! 0xE000ED70 ISA Feature Register4 */
   313            UInt32 RES_D74[99];  /*! 0xE000ED74-0xE000EEFC reserved */
   314            UInt32 STI;          /*! 0xE000EF00 Software Trigger Interrupt Register */
   315            UInt32 PID4;         /*! 0xE000EFD0 Peripheral ID Register4 */
   316            UInt32 PID5;         /*! 0xE000EFD4 Peripheral ID Register5 */
   317            UInt32 PID6;         /*! 0xE000EFD8 Peripheral ID Register6 */
   318            UInt32 PID7;         /*! 0xE000EFDC Peripheral ID Register7 */
   319            UInt32 PID0;         /*! 0xE000EFE0 Peripheral ID Register0 */
   320            UInt32 PID1;         /*! 0xE000EFE4 Peripheral ID Register1 */
   321            UInt32 PID2;         /*! 0xE000EFE8 Peripheral ID Register2 */
   322            UInt32 PID3;         /*! 0xE000EFEC Peripheral ID Register3 */
   323            UInt32 CID0;         /*! 0xE000EFF0 Component ID Register0 */
   324            UInt32 CID1;         /*! 0xE000EFF4 Component ID Register1 */
   325            UInt32 CID2;         /*! 0xE000EFF8 Component ID Register2 */
   326            UInt32 CID3;         /*! 0xE000EFFC Component ID Register3 */
   327        }
   328
   329        /*!
   330         * Physical Nested Vectored Interrupt Controller Device.
   331         * Short name is "Hwi_nvic"
   332         * Long name is "ti_sysbios_family_arm_m3_Hwi_nvic"
   333         */
   334        extern volatile NVIC nvic;
   335
   336        /*!
   337         *  Exception Context - Register contents at the time of an exception.
   338         */
   339        struct ExcContext {
   340            /* Thread Context */
   341            BIOS.ThreadType threadType; /* Type of thread executing at */
   342                                        /* the time the exception occurred */
   343            Ptr     threadHandle;       /* Handle to thread executing at */
   344                                        /* the time the exception occurred */
   345            Ptr     threadStack;        /* Address of stack contents of thread */
   346                                        /* executing at the time the exception */
   347                                        /* occurred */
   348            SizeT   threadStackSize;    /* size of thread stack */
   349
   350            /* Internal Registers */
   351            Ptr     r0;
   352            Ptr     r1;
   353            Ptr     r2;
   354            Ptr     r3;
   355            Ptr     r4;
   356            Ptr     r5;
   357            Ptr     r6;
   358            Ptr     r7;
   359            Ptr     r8;
   360            Ptr     r9;
   361            Ptr     r10;
   362            Ptr     r11;
   363            Ptr     r12;
   364            Ptr     sp;
   365            Ptr     lr;
   366            Ptr     pc;
   367            Ptr     psr;
   368
   369            /* NVIC registers */
   370            Ptr     ICSR;
   371            Ptr     MMFSR;
   372            Ptr     BFSR;
   373            Ptr     UFSR;
   374            Ptr     HFSR;
   375            Ptr     DFSR;
   376            Ptr     MMAR;
   377            Ptr     BFAR;
   378            Ptr     AFSR;
   379        }
   380
   381        /*! @_nodoc */
   382        metaonly struct BasicView {
   383            Ptr         halHwiHandle;
   384            String      label;
   385            Int         intNum;
   386            Int         priority;
   387            Int         group;
   388            Int         subPriority;
   389            String      fxn;
   390            UArg        arg;
   391        };
   392
   393        /*! @_nodoc */
   394        metaonly struct DetailedView {
   395            Ptr         halHwiHandle;
   396            String      label;
   397            Int         intNum;
   398            Int         priority;
   399            Int         group;
   400            Int         subPriority;
   401            String      fxn;
   402            UArg        arg;
   403            Ptr         irp;
   404            String      status;
   405        };
   406
   407        /*! @_nodoc */
   408        metaonly struct ModuleView {
   409            String      options[4];
   410            String      activeInterrupt;
   411            String      pendingInterrupt;
   412            String      exception;
   413            SizeT       hwiStackPeak;
   414            SizeT       hwiStackSize;
   415            Ptr         hwiStackBase;
   416        };
   417
   418        /*! @_nodoc */
   419        @Facet
   420        metaonly config ViewInfo.Instance rovViewInfo =
   421            ViewInfo.create({
   422                viewMap: [
   423                    ['Basic',
   424                        {
   425                            type: ViewInfo.INSTANCE,
   426                            viewInitFxn: 'viewInitBasic',
   427                            structName: 'BasicView'
   428                        }
   429                    ],
   430                    ['Detailed',
   431                        {
   432                            type: ViewInfo.INSTANCE,
   433                            viewInitFxn: 'viewInitDetailed',
   434                            structName: 'DetailedView'
   435                        }
   436                    ],
   437                    ['Module',
   438                        {
   439                            type: ViewInfo.MODULE,
   440                            viewInitFxn: 'viewInitModule',
   441                            structName: 'ModuleView'
   442                        }
   443                    ],
   444                    ['Exception',
   445                        {
   446                            type: ViewInfo.TREE,
   447                            viewInitFxn: 'viewInitException',
   448                            structName: 'ExcContext'
   449                        }
   450                    ]
   451                ]
   452            });
   453
   454        // -------- Module Parameters --------
   455
   456        // Logs
   457
   458        /*!
   459         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   460         */
   461        config Log.Event LM_begin = {
   462            mask: Diags.USER1 | Diags.USER2,
   463            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   464        };
   465
   466        /*!
   467         *  Issued just after return from Hwi function (with interrupts disabled)
   468         */
   469        config Log.Event LD_end = {
   470            mask: Diags.USER2,
   471            msg: "LD_end: hwi: 0x%x"
   472        };
   473
   474        // Asserts
   475
   476        /*! Assert when bad maskSetting parameter provided */
   477        config Assert.Id A_unsupportedMaskingOption = {
   478            msg: "A_unsupportedMaskingOption: unsupported maskSetting."
   479        };
   480
   481        // Errors
   482
   483        /*!
   484         *  Error raised when Hwi is already defined
   485         */
   486        config Error.Id E_alreadyDefined = {
   487            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   488        };
   489
   490        /*!
   491         *  Error raised when an exception occurs
   492         */
   493        config Error.Id E_exception = {
   494            msg: "E_exception: id = %d, pc = %08x.\nTo see more exception detail, set ti.sysbios.family.arm.m3.Hwi.enableException = true or,\nexamine the Exception view for the ti.sysbios.family.arm.m3.Hwi module using ROV."
   495        };
   496
   497        /*!
   498         *  Error raised when an uninitialized interrupt occurs
   499         */
   500        config Error.Id E_noIsr = {
   501            msg: "E_noIsr: id = %d, pc = %08x"
   502        };
   503
   504        /*!
   505         *  Error raised when NMI exception occurs
   506         */
   507        config Error.Id E_NMI = {
   508            msg: "E_NMI: %s"
   509        };
   510
   511        /*!
   512         *  Error raised when hard fault exception occurs
   513         */
   514        config Error.Id E_hardFault = {
   515            msg: "E_hardFault: %s"
   516        };
   517
   518        /*!
   519         *  Error raised when memory fault exception occurs
   520         */
   521        config Error.Id E_memFault = {
   522            msg: "E_memFault: %s"
   523        };
   524
   525        /*!
   526         *  Error raised when bus fault exception occurs
   527         */
   528        config Error.Id E_busFault = {
   529            msg: "E_busFault: %s"
   530        };
   531
   532        /*!
   533         *  Error raised when usage fault exception occurs
   534         */
   535        config Error.Id E_usageFault = {
   536            msg: "E_usageFault: %s"
   537        };
   538
   539        /*!
   540         *  Error raised when svCall exception occurs
   541         */
   542        config Error.Id E_svCall = {
   543            msg: "E_svCall: svNum = %d"
   544        };
   545
   546        /*!
   547         *  Error raised when debugMon exception occurs
   548         */
   549        config Error.Id E_debugMon = {
   550            msg: "E_debugMon: %s"
   551        };
   552
   553        /*!
   554         *  Error raised when reserved exception occurs
   555         */
   556        config Error.Id E_reserved = {
   557            msg: "E_reserved: %s %d"
   558        };
   559
   560        // configs
   561
   562        /*!
   563         *  Location of the Interrupt Vector Table
   564         *
   565         *  This parameter allows the user to override the default placement
   566         *  of the interrupt vector table. The NVIC's Vector Table Offset
   567         *  Register (VTOR) is also programmed to this value.
   568         *
   569         *  By default, the interrupt vector table will be placed at
   570         *  address 0x00000000.
   571         *
   572         *  Some systems require the vector table to be placed at an address
   573         *  other than 0 but still need a copy of the two M3 boot vectors
   574         *  (SP and reset PC), located there. To achieve this, a separate
   575         *  parameter {@link #resetVectorAdress} is provided. If the
   576         *  resetVectorAddress has a different value then the vectorTableAddress
   577         *  then a separate 2 vector table is generated and placed at that
   578         *  address.
   579         *
   580         *  The vector table must be placed at an address at or lower than
   581         *  0x3FFFFC00 and must be aligned on an even 64 word boundary.
   582         */
   583        metaonly config Ptr vectorTableAddress = 0x00000000;
   584
   585        /*!
   586         *  Alternate reset vector address. Default is 0x00000000
   587         *
   588         *  if initialized by the user then an additional reset vector
   589         *  is created and placed in the ".resetVecs" section.
   590         *  To place the .resetVecs section into a specific memory section,
   591         *  add the following command to your config script:
   592         *  @p(code)
   593         *  Program.sectMap[".resetVecs"] = YourMemorySection;
   594         *  @p
   595         */
   596        metaonly config Ptr resetVectorAddress = 0x00000000;
   597
   598        /*! Reset Handler. Default is c_int00 */
   599        metaonly config VectorFuncPtr resetFunc;
   600
   601        /*! NMI Handler. Default is set to an internal exception handler */
   602        metaonly config VectorFuncPtr nmiFunc;
   603
   604        /*! Hard Fault Handler. Default is set to an internal exception handler */
   605        metaonly config VectorFuncPtr hardFaultFunc;
   606
   607        /*! Hard Mem Handler. Default is set to an internal exception handler */
   608        metaonly config VectorFuncPtr memFaultFunc;
   609
   610        /*! Bus Fault Handler. Default is set to an internal exception handler */
   611        metaonly config VectorFuncPtr busFaultFunc;
   612
   613        /*! Usage Fault Handler. Default is set to an internal exception handler */
   614        metaonly config VectorFuncPtr usageFaultFunc;
   615
   616        /*! SVCall Handler. Default is set to an internal exception handler */
   617        metaonly config VectorFuncPtr svCallFunc;
   618
   619        /*! Debug Mon Handler. Default is set to an internal exception handler */
   620        metaonly config VectorFuncPtr debugMonFunc;
   621
   622        /*! Reserved Exception Handler. Default is set to an internal exception handler */
   623        metaonly config VectorFuncPtr reservedFunc;
   624
   625        /*! Uninitialized ISR Handler. Default is set to an internal exception handler */
   626        metaonly config VectorFuncPtr nullIsrFunc;
   627
   628        /*!
   629         *  Enable full exception decoding
   630         *
   631         *  When this is enabled, the exception handler will fully
   632         *  decode an exception and dump the registers to the
   633         *  system console.
   634         */
   635        metaonly config Bool enableException = true;
   636
   637        /*!
   638         *  User Exception Context Buffer Address
   639         *
   640         *  By default, when an exception occurs, an {@link #ExcContext}
   641         *  structure is allocated on the ISR stack and filled in within the
   642         *  exception handler.
   643         *
   644         *  If {@link #excContextBuffer} is initialized by the user, the
   645         *  {@link #ExcContext} structure will be placed at that address instead.
   646         *
   647         *  The buffer must be large enough to contain an {@link #ExcContext}
   648         *  structure.
   649         */
   650        metaonly config Ptr excContextBuffer;
   651
   652        /*!
   653         *  User Exception Stack Buffer Address
   654         *
   655         *  By default, when an exception occurs, a pointer to the base address
   656         *  of the stack being used by the thread causing the exception is placed
   657         *
   658         *  If {@link #excStackBuffer} is initialized by the user, the
   659         *  stack contents of the thread causing the exception will be
   660         *  copied to that address instead.
   661         *
   662         *  The buffer must be large enough to contain the largest task stack
   663         *  or ISR stack defined in the application.
   664         */
   665        metaonly config Ptr excStackBuffer;
   666
   667
   668        /*!
   669         *  User Exception hook function.
   670         *
   671         *  Called just after the exception context has been initialized.
   672         *
   673         *  This function will be run on the ISR stack.
   674         *
   675         *  This function must run to completion.
   676         *
   677         *  It is called without any Task or Swi scheduling protection
   678         *  and therefore can not call any functions that may cause a Swi or Task
   679         *  scheduling operation (Swi_post(), Semaphore_post(), Event_post(), etc).
   680         */
   681        config ExceptionHookFuncPtr excHookFunc = null;
   682
   683        /*!
   684         *  NVIC CCR register settings
   685         *
   686         *  These setting are written to Hwi_nvic.CCR at startup time.
   687         *
   688         *  See the Cortex M3 architecture reference manual for details
   689         *  on the meanings of these parameters.
   690         */
   691        metaonly config CCR nvicCCR = {
   692            STKALIGN: 1,
   693            BFHFNMIGN: 0,
   694            DIV_0_TRP: 0,
   695            UNALIGN_TRP: 0,
   696            USERSETMPEND: 0,
   697            NONEBASETHRDENA: 0
   698        };
   699
   700        /*!
   701         *  The priority that BASEPRI is set to by Hwi_disable().
   702         *
   703         *  All interrupts configured with equal or less priority (equal or
   704         *  higher number) than disablePriority are disabled by Hwi_disable.
   705         *  Interrupts configured with higher priority (smaller number) than
   706         *  disablePriority are non-maskable (ie zero-latency).
   707         *
   708         *  The default setting is the second highest interrupt priority
   709         *  defined for the device. This results in priority 0 (and all
   710         *  other values in the same priority group) being
   711         *  the non-maskable interrupt priority. All other priorities
   712         *  are disabled with Hwi_disable().
   713         */
   714        config UInt disablePriority;
   715
   716        /*!
   717         *  The PRIGROUP setting. Default is 0.
   718         *
   719         *  This value will be written to the PRIGROUP field
   720         *  within the NVIC's Application Interrupt and Reset Control
   721         *  Register (Hwi_nvic.AIRCR). It defines how the 8 bit priority
   722         *  values are interpreted by the hardware.
   723         *
   724         *  Valid settings are 0-7.
   725         *
   726         *  The default setting of 0 causes bits 7-1 of an interrupt's
   727         *  priority value to be used to as a pre-emption priority, and bit 0
   728         *  is used to determine which of two simultaneous interrupts with
   729         *  the same pre-emption priority will be serviced first.
   730         */
   731        config UInt priGroup = 0;
   732
   733        /*!
   734         *  non-dispatched interrupt object.
   735         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   736         */
   737        metaonly struct NonDispatchedInterrupt {
   738            Int             intNum;
   739            VectorFuncPtr   vfxn;
   740            UInt            priority;
   741            Bool            enableInt;
   742        };
   743
   744        /*!
   745         *  non-dispatched interrupt array.
   746         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   747         */
   748        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   749
   750        // -------- Module Functions --------
   751
   752        /*!
   753         *  ======== disable ========
   754         */
   755        @Macro
   756        override UInt disable();
   757
   758        /*!
   759         *  ======== enable ========
   760         */
   761        @Macro
   762        override UInt enable();
   763
   764        /*!
   765         *  ======== restore ========
   766         */
   767        @Macro
   768        override Void restore(UInt key);
   769
   770        /*!
   771         *  ======== disableInterrupt ========
   772         */
   773        @DirectCall
   774        override UInt disableInterrupt(UInt intNum);
   775
   776        /*!
   777         *  ======== enableInterrupt ========
   778         */
   779        @DirectCall
   780        override UInt enableInterrupt(UInt intNum);
   781
   782        /*!
   783         *  ======== restore ========
   784         */
   785        @DirectCall
   786        override Void restoreInterrupt(UInt intNum, UInt key);
   787
   788        /*!
   789         *  ======== inUseMeta ========
   790         *  @_nodoc
   791         *  Check for Hwi already in use.
   792         *  For internal SYS/BIOS use only.
   793         *  Should be called prior to any internal Hwi.create().
   794         *
   795         *  @param(intNum)  interrupt number
   796         */
   797        metaonly Bool inUseMeta(UInt intNum);
   798
   799        /*!
   800         *  @_nodoc
   801         *  ======== plug ========
   802         *  Plug a non dispatched interrupt vector with an ISR address.
   803         *
   804         *  @param(intNum)  interrupt number
   805         *  @param(fxn)     pointer to ISR function
   806         */
   807        @DirectCall
   808        Void plug(UInt intNum, VectorFuncPtr fxn);
   809
   810        /*!
   811         *  ======== getHandle ========
   812         *  Returns Hwi_handle associated with intNum
   813         *
   814         *  @param(intNum)  interrupt number
   815         */
   816        @DirectCall
   817        Handle getHandle(UInt intNum);
   818
   819        /*!
   820         *  ======== setPriority ========
   821         *  Set an interrupt's relative priority.
   822         *
   823         *  Valid priorities are 0 - 255. 0 is highest priority.
   824         *
   825         *  @param(intNum)      ID of interrupt
   826         *  @param(priority)    priority
   827         */
   828        @DirectCall
   829        Void setPriority(UInt intNum, UInt priority);
   830
   831        /*!
   832         *  ======== excSetBuffers ========
   833         *  Set the exception context and stack buffer pointers
   834         *
   835         *  @param(excContextBuffer)        Address to place ExcContext
   836         *  @param(excStackBuffer)          Address to place ExcStack
   837         */
   838        @DirectCall
   839        Void excSetBuffers(Ptr excContextBuffer, Ptr excStackBuffer);
   840
   841        /*! @_nodoc
   842         *  ======== allowInterrupts ========
   843         *  WA 1.1 function to briefly enable interrupts
   844         */
   845        @DirectCall
   846        Void allowInterrupts_wa1_1();
   847
   848    instance:
   849
   850        /*!
   851         *  Interrupt priority.
   852         *  The default is 255 which is the lowest priority.
   853         *
   854         *  Priority 0 is the highest priority and by default is
   855         *  reserved for zero latency interrupts
   856         *  (see {@link #disablePriority}).
   857         *
   858         *  Valid priorities values are device dependent and their
   859         *  nesting behaviors depend on the {@link #priGroup} setting.
   860         *
   861         *  See the Cortex M3 architecture reference manual for details
   862         *  on the meanings of these parameters.
   863         */
   864        override config Int priority = 255;
   865
   866        /*!
   867         * Interrupt Masking Option. Only MaskingOption_LOWER is supported.
   868         *
   869         * The NVIC interrupt controller is designed for priority based
   870         * interrupts. No support is provided for anything but
   871         * Hwi.MaskingOption_LOWER.
   872         */
   873        override config IHwi.MaskingOption maskSetting = IHwi.MaskingOption_LOWER;
   874
   875        /*!
   876         *  ======== reconfig ========
   877         *  Reconfigure a dispatched interrupt.
   878         */
   879        @DirectCall
   880        Void reconfig(FuncPtr fxn, const Params *params);
   881
   882    internal:   /* not for client use */
   883
   884        /*
   885         *  The omap4430 ES1 devices have a nasty bug in the unicache
   886         *  that locks the bus up when an interrupt occurs at a specific
   887         *  time during an internal cache operation.
   888         *  The flag below, when set to true, activates special
   889         *  code in the Hwi module to work around this bug.
   890         *  "WA1_1" comes from "WorkAround 1.1" from a list of potential
   891         *  solutions to the problem developed by the design team.
   892         */
   893        metaonly config Bool enableWA1_1 = false;
   894
   895        /*
   896         * Swi and Task module function pointers.
   897         * Used to decouple Hwi from Swi and Task when
   898         * dispatcherSwiSupport or
   899         * dispatcherTaskSupport is false.
   900         */
   901        config UInt (*swiDisable)();
   902        config Void (*swiRestoreHwi)(UInt);
   903        config UInt (*taskDisable)();
   904        config Void (*taskRestoreHwi)(UInt);
   905
   906        /* initial Hwi_nvic.CCR value */
   907        config UInt32 ccr;
   908
   909        /*!
   910         *  const array to hold all HookSet objects.
   911         */
   912        config HookSet hooks[length] = [];
   913
   914
   915        /* WA 1.1 function to briefly enable interrupts */
   916        Void beginHook_wa1_1(IHwi.Handle hwi);
   917
   918        /*!
   919         *  ======== initVTOR ========
   920         *  Initialize the Vector Table Offset Register
   921         *  This function is plugged as a Startup.firstFxn
   922         *  to set up vector table as early as possible
   923         */
   924        Void initVTOR();
   925
   926        /*!
   927         *  ======== excHandlerAsm ========
   928         *  asm code exception handler
   929         */
   930        Void excHandlerAsm();
   931
   932        /*!
   933         *  ======== excHandler ========
   934         *  exception Handler routes to
   935         *  either min or max exception handler
   936         */
   937        Void excHandler(UInt *excStack, UInt lr);
   938
   939        /*!
   940         *  ======== excHandlerMin ========
   941         *  Minimal Exception Handler
   942         */
   943        Void excHandlerMin(UInt *excStack, UInt lr);
   944
   945        /*!
   946         *  ======== excHandlerMax ========
   947         *  Full Featured Exception Handler
   948         */
   949        Void excHandlerMax(UInt *excStack, UInt lr);
   950
   951        /*! Hwi exception handler function type definition. */
   952        typedef Void (*ExcHandlerFuncPtr)(UInt *, UInt);
   953
   954        config ExcHandlerFuncPtr excHandlerFunc = excHandlerMin;
   955
   956        /*!
   957         *  ======== excFillContext ========
   958         */
   959        Void excFillContext();
   960
   961        /*!
   962         *  ======== excNmi ========
   963         */
   964        Void excNmi(UInt *excStack);
   965
   966        /*!
   967         *  ======== excHardFault ========
   968         */
   969        Void excHardFault(UInt *excStack);
   970
   971        /*!
   972         *  ======== excMemFault ========
   973         */
   974        Void excMemFault(UInt *excStack);
   975
   976        /*!
   977         *  ======== excBusFault ========
   978         */
   979        Void excBusFault(UInt *excStack);
   980
   981        /*!
   982         *  ======== excUsageFault ========
   983         */
   984        Void excUsageFault(UInt *excStack);
   985
   986        /*!
   987         *  ======== excSvCall ========
   988         */
   989        Void excSvCall(UInt *excStack);
   990
   991        /*!
   992         *  ======== excDebugMon ========
   993         */
   994        Void excDebugMon(UInt *excStack);
   995
   996        /*!
   997         *  ======== excReserved ========
   998         */
   999        Void excReserved(UInt *excStack, UInt excNum);
  1000
  1001        /*!
  1002         *  ======== excNoIsr ========
  1003         */
  1004        Void excNoIsr(UInt *excStack, UInt excNum);
  1005
  1006        /*!
  1007         *  ======== excDumpRegs ========
  1008         */
  1009        Void excDumpRegs(UInt lr);
  1010
  1011        /*!
  1012         *  ======== pendSV ========
  1013         * Used by dispatcher
  1014         */
  1015        Void pendSV();
  1016
  1017        /*!
  1018         *  ======== init ========
  1019         * set up Hwi stack
  1020         */
  1021        Void init();
  1022
  1023        /*! Hwi vector function type definition. */
  1024        typedef Void (*HandlerFuncPtr)(Handle, UInt);
  1025
  1026        /* Low Level Interrupt Dispatcher Wrapper */
  1027        Void dispatch();
  1028
  1029        /* "Top Half" of Interrupt Dispatcher */
  1030        UInt dispatchC(Irp irp);
  1031
  1032        /* "Bottom Half" of Interrupt Dispatcher */
  1033        Void doSwiTaskRestore(UInt tskKey);
  1034
  1035        /*! Meta World Only Hwi Configuration Object. */
  1036        metaonly struct InterruptObj {
  1037            String name;            /* symbol used for vector table entry */
  1038            Bool used;              /* Interrupt already defined? */
  1039            Bool useDispatcher;     /* Should dispatcher handle this Int? */
  1040            UInt priority;          /* used to determine FIQ/IRQ type */
  1041            FuncPtr fxn;            /* Dispatched ISR function */
  1042            VectorFuncPtr vfxn;     /* vector table func Ptr. */
  1043        };
  1044
  1045        /*!
  1046         * Meta-only array of interrupt objects.
  1047         * This meta-only array of Hwi config objects is initialized
  1048         * in Hwi.xs:module$meta$init().
  1049         */
  1050        metaonly config InterruptObj interrupt[];
  1051
  1052        struct Instance_State {
  1053            UArg            arg;            // Argument to Hwi function.
  1054            FuncPtr         fxn;            // Hwi function.
  1055            Int             intNum;         // Interrupt number
  1056            Irp             irp;            // current IRP
  1057            Ptr             hookEnv[];
  1058        };
  1059
  1060        struct Module_State {
  1061            Bits16      enables;            // Bit 15 = SysTick IE,
  1062                                            // Bit 0 = WA1.1
  1063            Bits32      iser[8];            // Initial Interrupt Set Enable Reg values
  1064            UInt8       priorities[];       // table of interrupt priorities
  1065            Char        *taskSP;            // Temporary storage of interrupted
  1066                                            // Task's SP during ISR execution
  1067            Bool        excActive;          // TRUE if an exception has occurred
  1068            ExcContext  *excContext;        // Exception context
  1069            Ptr         excStack;           // Exception thread stack
  1070
  1071            /* ROM */
  1072            Ptr         isrStack;           // Points to isrStack address
  1073            Ptr         isrStackBase;       // = __TI_STACK_BASE
  1074            SizeT       isrStackSize;       // = Program.stack
  1075            Ptr         vectorTableBase;    // Points to base of vector table
  1076            Handle      dispatchTable[];    // dispatch table
  1077        };
  1078    }
  1079    /*
  1080     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:37; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
  1081
  1082     */
  1083


package ti.sysbios.family.arm.m3

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.arm.m3 ========
    40     *  Contains specifications for the m3 family/device-specific SYS/BIOS functions.
    41     *
    42     *  The link below provides SYS/BIOS M3 register usage information:
    43     *
    44     *      {@link ./doc-files/m3regconv.html SYS/BIOS M3 Register Usage}
    45     *
    46     */
    47    package ti.sysbios.family.arm.m3 [2,0,0,0] {
    48        module Clobber;
    49        module Exception;
    50        module Hwi;
    51        module IntrinsicsSupport;
    52        module TaskSupport;
    53        module Timer;
    54        module TimestampProvider;
    55    }
    56    /*
    57     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:39; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    58
    59     */
    60


module ti.sysbios.family.arm.m3.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.m3;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  M3 Task Support Module.
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*! default Task stack size. */
    46        override readonly config SizeT defaultStackSize = 2048;
    47
    48        /*! required stack alignment (in MAUs). */
    49        override readonly config UInt stackAlignment = 8;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.arm.m3.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arm.m3;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.ITimer;
    45
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Cortex M3 Timer Peripherals Manager.
    50     *
    51     *  The Cortex M3 Timer Manager utilizes the M3's internal NVIC SysTick Timer.
    52     *  The SysTick timer is clocked at the CPU clock rate, nominally 200MHz.
    53     *  The SysTick timer has only 24 bits of period resolution and is therefore
    54     *  limited to a maximum period of 83ms.
    55     *
    56     *
    57     *  @p(html)
    58     *  <h3> Calling Context </h3>
    59     *  <table border="1" cellpadding="3">
    60     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    61     *
    62     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    63     *    <!--                                                                                                                 -->
    64     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    77     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    78     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    79     *    <tr><td colspan="6"> Definitions: <br />
    80     *       <ul>
    81     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    82     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    83     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    84     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    85     *           <ul>
    86     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    87     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    88     *             <li> During main().</li>
    89     *             <li> During BIOS.startupFxns.</li>
    90     *           </ul>
    91     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    92     *           <ul>
    93     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    94     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    95     *           </ul>
    96     *       </ul>
    97     *    </td></tr>
    98     *
    99     *  </table>
   100     *  @p
   101     */
   102    @InstanceFinalize       /* To cleanup */
   103    @InstanceInitError      /* To report unavailability of timer */
   104    @ModuleStartup          /* to configure static timers */
   105
   106    module Timer inherits ti.sysbios.interfaces.ITimer
   107    {
   108        /*! Max value of Timer period for PeriodType_COUNTS */
   109        const UInt MAX_PERIOD = 0x00ffffff;
   110
   111        /*! Number of timer peripherals on chip */
   112        const Int NUM_TIMER_DEVICES = 1;
   113
   114        /*! Timer clock divider wrt cpu clock */
   115        const Int TIMER_CLOCK_DIVIDER = 1;
   116
   117        /*! @_nodoc
   118         *  Min instructions to use in trigger().
   119         */
   120        const Int MIN_SWEEP_PERIOD = 1;
   121
   122        /*! @_nodoc */
   123        @XmlDtd
   124        metaonly struct BasicView {
   125            Ptr         halTimerHandle;
   126            String      label;
   127            UInt        id;
   128            String      device;
   129            String      startMode;
   130            String      runMode;
   131            UInt        period;
   132            String      periodType;
   133            UInt        intNum;
   134            String      tickFxn[];
   135            UArg        arg;
   136            String      extFreq;
   137            String      hwiHandle;
   138        };
   139
   140
   141        /*! @_nodoc */
   142        metaonly struct ModuleView {
   143            String      availMask;
   144            UInt        tickCount;
   145        }
   146
   147        /*! @_nodoc */
   148        metaonly struct DeviceView {
   149            UInt        id;
   150            String      device;
   151            String      devAddr;
   152            UInt        intNum;
   153            String      runMode;
   154            UInt        period;
   155            UInt        currCount;
   156            UInt        remainingCount;
   157        };
   158
   159        /*! @_nodoc */
   160        @Facet
   161        metaonly config ViewInfo.Instance rovViewInfo =
   162            ViewInfo.create({
   163                viewMap: [
   164                [
   165                    'Basic',
   166                    {
   167                        type: ViewInfo.INSTANCE,
   168                        viewInitFxn: 'viewInitBasic',
   169                        structName: 'BasicView'
   170                    }
   171                ],
   172                [
   173                    'Device',
   174                    {
   175                        type: ViewInfo.INSTANCE,
   176                        viewInitFxn: 'viewInitDevice',
   177                        structName: 'DeviceView'
   178                    }
   179                ],
   180                [
   181                    'Module',
   182                    {
   183                        type: ViewInfo.MODULE,
   184                        viewInitFxn: 'viewInitModule',
   185                        structName: 'ModuleView'
   186                    }
   187                ],
   188                ]
   189            });
   190        /*!
   191
   192         *  Error raised when timer id specified is not supported.
   193         */
   194        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   195
   196        /*!
   197         *  Error raised when timer requested is in use
   198         */
   199        config Error.Id E_notAvailable  =
   200            {msg: "E_notAvailable: Timer not available %d"};
   201
   202        /*!
   203         *  Error raised when period requested is not supported
   204         */
   205        config Error.Id E_cannotSupport  =
   206            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   207
   208        /*!
   209         *  ======== anyMask ========
   210         *  Available mask to be used when select = Timer_ANY
   211         */
   212        config UInt anyMask = 0x1;
   213
   214        /*!
   215         *  ======== getHandle ========
   216         *  @_nodoc
   217         *  Used by TimestampProvider module to get hold of timer handle.
   218         *
   219         *  @param(id)      timer Id.
   220         */
   221        @DirectCall
   222        Handle getHandle(UInt id);
   223
   224        /*!
   225         *  ======== getTickCount ========
   226         *  @_nodoc
   227         *  Used by TimestampProvider.
   228         */
   229        @DirectCall
   230        UInt32 getTickCount();
   231
   232    instance:
   233
   234        /*! Hwi Params for Hwi Object. Default is null. */
   235        config Hwi.Params *hwiParams = null;
   236
   237        /*!
   238         *  ======== reconfig ========
   239         *  Used to modify static timer instances at runtime.
   240         *
   241         *  @param(timerParams)     timer Params
   242         *  @param(tickFxn)         function that runs when timer expires
   243         */
   244        @DirectCall
   245        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   246
   247
   248    internal:   /* not for client use */
   249
   250        /*!
   251         *  ======== oneShotStub ========
   252         *  SysTick timer does not support one shot mode. This stub stops timer
   253         *  and clears the pending timer interrupt.
   254         *
   255         *  @param(arg)     Timer object.
   256         */
   257        Void oneShotStub(UArg arg);
   258
   259        /*!
   260         *  ======== periodicStub ========
   261         *  SysTick timer interrupt must be acknowledged. This stub acknowledges timer
   262         *
   263         *  @param(arg)     Timer object.
   264         */
   265        Void periodicStub(UArg arg);
   266
   267        /*!
   268         *  ======== noStartupNeeded ========
   269         *  Flag used to prevent misc code from being brought in
   270         *  un-necessarily
   271         */
   272        config UInt startupNeeded = false;
   273
   274        struct Instance_State {
   275            Bool            staticInst;
   276            Int             id;
   277            RunMode         runMode;
   278            StartMode       startMode;
   279            UInt            period;
   280            PeriodType      periodType;
   281            UInt            intNum;
   282            UArg            arg;
   283            Hwi.FuncPtr     tickFxn;
   284            Types.FreqHz    extFreq;        /* external frequency in Hz */
   285            Hwi.Handle      hwi;
   286        }
   287
   288        struct Module_State {
   289            volatile UInt   tickCount;      /* SysTick Rollover counter */
   290            UInt            availMask;      /* available peripherals */
   291            Handle          handle;         /* NVIC timer handle */
   292        }
   293    }
   294
   295    /*
   296     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   297
   298     */
   299


module ti.sysbios.family.arm.m3.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.m3;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  Implements ITimestampProvider
    43     *
    44     *  Cortex M3 TimestampProvider delegate for use
    45     *  with {@link xdc.runtime.Timestamp}.
    46     *
    47     *  The SysTick timer is used as the timestamp source.
    48     *
    49     *  @p(html)
    50     *  <h3> Calling Context </h3>
    51     *  <table border="1" cellpadding="3">
    52     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    53     *
    54     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    55     *    <!--                                                                                                                 -->
    56     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *
    60     *  </table>
    61     *  @p
    62     */
    63
    64    @ModuleStartup
    65
    66    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    67    {
    68        /*
    69         *  By default, TimestampProvider assumes the SysTick timer is
    70         *  configured elsewhere (ie by the Clock module).
    71         *  Set this parameter to true if TimestampProvider is the only user
    72         *  of the SysTick timer.
    73         */
    74        config Bool configTimer = false;
    75
    76        /*!@_nodoc
    77         *  Internal use. Function that starts timer before main
    78         */
    79        @DirectCall
    80        Void startTimer();
    81
    82        /*!@_nodoc
    83         *  Internal use. Timer rollover interrupt handler.
    84         */
    85        @DirectCall
    86        Void rolloverFunc(UArg unused);
    87
    88    internal:   /* not for client use */
    89
    90        struct Module_State {
    91            Timer.Handle    timer;          /* timer instance used */
    92        }
    93    }
    94    /*
    95     *  @(#) ti.sysbios.family.arm.m3; 2, 0, 0, 0,238; 6-15-2011 16:24:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    96
    97     */
    98


C6000 DSP/BIOS Register Usage

C6x Register Usage

Cortex M3 DSP/BIOS Register Usage

This document provides a table describing the various Cortex M3 targets register conventions in terms of preservation across multi-threaded context switching and preconditions.

Overview

In a multi-threaded application using DSP/BIOS, it is necessary to know which registers can or cannot be modified. Furthermore, users need to understand which registers need to be saved/restored across a function call or an interrupt.

The following definitions describe the various possible register handling behaviors:

  • Scratch register. These registers are saved/restored by the Hwi dispatcher with temporary register bit masks.
  • Preserved register. These registers are saved/restored during a Task context switch.
  • Initialized register. These registers are set to a particular value during Hwi processing and restored to their incoming value upon exiting from the interrupt routine.
  • Read-Only register. These registers may be read but must not be modified.
  • Global register. These registers are shared across all threads in the system. To make a temporary change, save the register, make the change, and then restore it.
  • Other. These registers do not fit into one of the categories above.

Register Conventions

Table 1 Register and Status Bit Handling

Register

Status Bit

Register or Status Bit Name

Type

Notes

R0-R3, R12

General purpose registers

Scratch

R4-R11

General purpose registers

Preserved

R13 (SP_process)

Process Stack pointer

Preserved

R13 (SP_main)

Main Stack pointer

Other

?Set to top of ISR stack buffer at startup. Auto switched to in Hwi threads. Manually switched to in Swi threads.

R14 (LR)

Link Register

Preserved

xPSR

Program Status Register

N,Z,C,V

Condition Codes

Scratch

Q

Overflow

Scratch

ICI

Interrupt-continuable instruction

Read-Only

IT

IF-Then bits

Read-Only

T

Thumb

Other

Always set

ISRNUM

ISR Number

Read-Only

?

CONTROL

Control Register

Other

Used to manually force main/process stack switching

PRIMASK

Configurable Exception Mask Register

Other

Untouched

FAULTMASK

Fault Prioirty Set Register

Other

Untouched

BASEPRI

Base Priority Register

Other

Hwi_enable/disable/restore manipulate this register to manage maskable interrupts

Notes:

.


module ti.sysbios.family.arm.tms570.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arm.tms570;
    37
    38    import xdc.runtime.Diags;
    39    import xdc.runtime.Error;
    40    import xdc.runtime.Log;
    41    import xdc.rov.ViewInfo;
    42
    43    /*!
    44     *  ======== Hwi ========
    45     *  Hardware Interrupt Support Module.
    46     *
    47     *  This Hwi module provides TMS570 (VIM) specific implementations of the
    48     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    49     *
    50     *  Additional ARM device-specific APIs are also provided.
    51     *
    52     *  @a(NOTE)
    53     *  In this Hwi module implementation, the instance config parameter value
    54     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    55     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    56     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    57     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    58     *  silently converted to {@link #MaskingOption_SELF}.
    59     *
    60     *  @p(html)
    61     *  <h3> Calling Context </h3>
    62     *  <table border="1" cellpadding="3">
    63     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    64     *
    65     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    66     *    <!--                                                                                                                 -->
    67     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #disableREQMASKSET0}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #disableREQMASKSET1}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #disableFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #disableIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enableREQMASKSET0}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #enableREQMASKSET1}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #enableFIQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #enableIRQ}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #getHandle}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    83     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    84     *    <tr><td> {@link #restoreREQMASKSET0}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #restoreREQMASKSET1}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #restoreFIQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    87     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    88     *    <tr><td> {@link #restoreIRQ}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    89     *    <tr><td> {@link #setPriority}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td colspan="6"> Definitions: <br />
    98     *       <ul>
    99     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   100     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   101     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   102     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   103     *           <ul>
   104     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   105     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   106     *             <li> During main().</li>
   107     *             <li> During BIOS.startupFxns.</li>
   108     *           </ul>
   109     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   110     *           <ul>
   111     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   112     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   113     *           </ul>
   114     *       </ul>
   115     *    </td></tr>
   116     *
   117     *
   118     *  </table>
   119     *  @p
   120     */
   121
   122    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   123    @ModuleStartup          /* generates call to Hwi_Module_startup at startup */
   124
   125    module Hwi inherits ti.sysbios.interfaces.IHwi
   126    {
   127
   128        // -------- Module Constants --------
   129
   130        /*! The TMS570 ARM Interrupt Controller supports 64 interrupts. */
   131        const Int NUM_INTERRUPTS = 64;
   132
   133        // -------- Module Types --------
   134
   135        /*! Hwi vector function type definition. */
   136        typedef Void (*VectorFuncPtr)(void);
   137
   138        /*! @_nodoc Hwi plug function type definition. */
   139        typedef Void (*PlugFuncPtr)(void);
   140
   141        /*! Interrupt type. IRQ or FIQ */
   142        enum Type {
   143            Type_IRQ,               /*! IRQ interrupt. */
   144            Type_FIQ                /*! FIQ interrupt. */
   145        };
   146
   147        /*!
   148         * ARM Interrupt Controller.
   149         */
   150        struct VIM {
   151            UInt32 PARFLG;          /*! 0xFDEC VIM RAM Parity Flag Register */
   152            UInt32 PARCTL;          /*! 0xFDF0 VIM RAM Parity Control Register */
   153            UInt32 ADDERR;          /*! 0xFDF4 Address Parity Error Register */
   154            UInt32 FBPARERR;        /*! 0xFDF8 Fallback Parity Error Register */
   155            UInt32 RESFC;           /*! 0xFDFC reserved */
   156
   157            UInt32 IRQINDEX;        /*! 0x0000 current IRQ id */
   158            UInt32 FIQINDEX;        /*! 0x0004 current FIQ id */
   159            UInt32 RES08[2];        /*! 0x0008 reserved */
   160
   161            UInt32 FIRQPR[4];       /*! 0x0010-0x001C FIQ/IRQ Program Control Registers */
   162            UInt32 INTREQ[4];       /*! 0x0020-0x002C Pending Interrupt Request Registers */
   163
   164            UInt32 REQENASET[4];    /*! 0x0030-0x003C Interrupt (Enable) Mask Set Registers */
   165            UInt32 REQENACLR[4];    /*! 0x0040-0x004C Interrupt (Enable) Mask Clear Registers */
   166
   167            UInt32 WAKEENASET[4];   /*! 0x0050-0x005C Wake Mask Set Registers */
   168            UInt32 WAKEENACLR[4];   /*! 0x0060-0x006C Wake Mask Clear Registers */
   169
   170            UInt32 IRQVECREG;       /*! 0x0070 IRQ vector */
   171            UInt32 FIQVECREG;       /*! 0x0074 FIQ vector */
   172
   173            UInt32 CAPEVT;          /*! 0x0078 Capture Event Register */
   174            UInt32 RES7C[1];        /*! 0x007C reserved */
   175
   176            UInt8 CHANMAP[128];     /*! 0x0080-0x00FF Channel Map (Priority) Registers */
   177        };
   178
   179        /*!
   180         * Physical Vectored Interrupt Manager (VIM) Device.
   181         * Short name is "Hwi_vim"
   182         * Long name is "ti_sysbios_family_arm_tms570_Hwi_vim"
   183         */
   184        extern volatile VIM vim;
   185
   186        /*! @_nodoc */
   187        metaonly struct BasicView {
   188            Ptr         halHwiHandle;
   189            String      label;
   190            Int         intNum;
   191            Int         priority;
   192            String      fxn;
   193            UArg        arg;
   194            Ptr         irp;
   195            String      status;
   196        };
   197
   198        /*! @_nodoc */
   199        metaonly struct ModuleView {
   200            String      options[4];
   201            SizeT       hwiStackPeak;
   202            SizeT       hwiStackSize;
   203            Ptr         hwiStackBase;
   204        };
   205
   206        /*! @_nodoc */
   207        @Facet
   208        metaonly config ViewInfo.Instance rovViewInfo =
   209            ViewInfo.create({
   210                viewMap: [
   211                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   212                    ['Module', {type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
   213                ]
   214            });
   215
   216        // -------- Module Parameters --------
   217
   218        /*! Reset Handler. Default is c_int00 */
   219        metaonly config VectorFuncPtr resetFunc;
   220
   221        /*! Undefined instruction exception handler. Default is self loop */
   222        metaonly config VectorFuncPtr undefinedInstFunc;
   223
   224        /*! SWI Handler. Default is internal SWI handler */
   225        metaonly config VectorFuncPtr swiFunc;
   226
   227        /*! Prefetch abort exception handler. Default is self loop */
   228        metaonly config VectorFuncPtr prefetchAbortFunc;
   229
   230        /*! Data abort exception handler. Default is self loop */
   231        metaonly config VectorFuncPtr dataAbortFunc;
   232
   233        /*! Reserved exception handler. Default is self loop */
   234        metaonly config VectorFuncPtr reservedFunc;
   235
   236        /*! IRQ interrupt handler. Default is internal IRQ dispatcher */
   237        metaonly config VectorFuncPtr irqFunc;
   238
   239        /*! FIQ interrupt handler. Default is internal FIQ dispatcher */
   240        metaonly config VectorFuncPtr fiqFunc;
   241
   242        /*!
   243         *  FIQ stack pointer. Default = null.
   244         *  (Indicates that stack is to be created using
   245         *  staticPlace()
   246         */
   247        config Ptr fiqStack = null;
   248
   249        /*!
   250         *  FIQ stack size in MAUs.
   251         *  Default is 1024 bytes.
   252         */
   253        metaonly config SizeT fiqStackSize = 1024;
   254
   255        /*!
   256         *  Memory section used for FIQ stack
   257         *  Default is null.
   258         */
   259        metaonly config String fiqStackSection = null;
   260
   261        /*!
   262         *  Error raised when Hwi is already defined
   263         */
   264        config Error.Id E_alreadyDefined = {
   265            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   266        };
   267
   268        /*!
   269         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   270         */
   271        config Log.Event LM_begin = {
   272            mask: Diags.USER1 | Diags.USER2,
   273            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   274        };
   275
   276        /*!
   277         *  Issued just after return from Hwi function (with interrupts disabled)
   278         */
   279        config Log.Event LD_end = {
   280            mask: Diags.USER2,
   281            msg: "LD_end: hwi: 0x%x"
   282        };
   283
   284
   285        // -------- Module Functions --------
   286
   287        /*!
   288         *  ======== disable ========
   289         */
   290        @Macro
   291        override UInt disable();
   292
   293        /*!
   294         *  ======== enable ========
   295         */
   296        @Macro
   297        override UInt enable();
   298
   299        /*!
   300         *  ======== restore ========
   301         */
   302        @Macro
   303        override Void restore(UInt key);
   304
   305        /*!
   306         *  ======== inUseMeta ========
   307         *  @_nodoc
   308         *  Check for Hwi already in use.
   309         *  For internal SYS/BIOS use only.
   310         *  Should be called prior to any internal Hwi.create().
   311         *
   312         *  @param(intNum)  interrupt number
   313         */
   314        metaonly Bool inUseMeta(UInt intNum);
   315
   316        /*!
   317         *  ======== getHandle ========
   318         *  Returns pointer to Hwi instance object.
   319         *
   320         *  @param(intNum)  interrupt number
   321         */
   322        @DirectCall
   323        Object *getHandle(UInt intNum);
   324
   325        /*!
   326         *  ======== enableFIQ ========
   327         *  Enable FIQ interrupts.
   328         *
   329         *  @b(returns)     previous FIQ interrupt enable/disable state
   330         */
   331        @DirectCall
   332        UInt enableFIQ();
   333
   334        /*!
   335         *  ======== disableFIQ ========
   336         *  Disable FIQ interrupts.
   337         *
   338         *  @b(returns)     previous FIQ interrupt enable/disable state
   339         */
   340        @DirectCall
   341        UInt disableFIQ();
   342
   343        /*!
   344         *  ======== restoreFIQ ========
   345         *  Restore FIQ interrupts.
   346         *
   347         *  @param(key)     enable/disable state to restore
   348         */
   349        @DirectCall
   350        Void restoreFIQ(UInt key);
   351
   352        /*!
   353         *  ======== enableIRQ ========
   354         *  Enable IRQ interrupts.
   355         *
   356         *  @param(key)     enable/disable state to restore
   357         */
   358        @DirectCall
   359        UInt enableIRQ();
   360
   361        /*!
   362         *  ======== disableIRQ ========
   363         *  Disable IRQ interrupts.
   364         *
   365         *  @b(returns)     previous IRQ interrupt enable/disable state
   366         */
   367        @DirectCall
   368        UInt disableIRQ();
   369
   370        /*!
   371         *  ======== restoreIRQ ========
   372         *  Restore IRQ interrupts.
   373         *
   374         *  @param(key)     enable/disable state to restore
   375         */
   376        @DirectCall
   377        Void restoreIRQ(UInt key);
   378
   379        /*!
   380         *  ======== setPriority ========
   381         *  Set an interrupt's relative priority.
   382         *
   383         *  @param(intNum)      ID of interrupt
   384         *  @param(priority)    priority (0-63)
   385         */
   386        @DirectCall
   387        Void setPriority(UInt intNum, UInt priority);
   388
   389        /*!
   390         *  ======== setType ========
   391         *  Set an interrupt's type (FIQ/IRQ).
   392         *
   393         *  Not an instance function so that it can be used
   394         *  with non-dispatched interrupts.
   395         *
   396         *  @param(intNum)      ID of interrupt
   397         *  @param(type)        type = FIQ/IRQ
   398         */
   399        @DirectCall
   400        Void setType(UInt intNum, Type type);
   401
   402    instance:
   403
   404        /*! disableMask0. default is derived from MaskingOption_SELF maskSetting. */
   405        config Bits32 disableMask0 = 0;
   406
   407        /*! disableMask1. default is derived from MaskingOption_SELF maskSetting. */
   408        config Bits32 disableMask1 = 0;
   409
   410        /*! restoreMask0. default is derived from MaskingOption_SELF maskSetting. */
   411        config Bits32 restoreMask0 = 0;
   412
   413        /*! restoreMask1. default is derived from MaskingOption_SELF maskSetting. */
   414        config Bits32 restoreMask1 = 0;
   415
   416        /*! wakeEnable. default is true. */
   417        config Bool wakeEnable = true;
   418
   419        /*! Interrupt type (IRQ/FIQ. Default is IRQ. */
   420        config Type type = Type_IRQ;
   421
   422        /*!
   423         *  ======== reconfig ========
   424         *  Reconfigure a dispatched interrupt.
   425         */
   426        @DirectCall
   427        Void reconfig(FuncPtr fxn, const Params *params);
   428
   429    internal:   /* not for client use */
   430
   431        /*
   432         * Swi and Task module function pointers.
   433         * Used to decouple Hwi from Swi and Task when
   434         * dispatcherSwiSupport or
   435         * dispatcherTaskSupport is false.
   436         */
   437        config UInt (*swiDisable)();
   438        config Void (*swiRestoreHwi)(UInt);
   439        config UInt (*taskDisable)();
   440        config Void (*taskRestoreHwi)(UInt);
   441
   442        /* assembly code mode registers setup */
   443        Void init();
   444
   445        /* Interrupt Dispatcher assembly code wrapper */
   446        Void dispatchIRQ();
   447
   448        /* IRQ Interrupt Dispatcher */
   449        Void dispatchIRQC(Irp irp);
   450
   451        /* default FIQ Interrupt Dispatcher */
   452        Void dispatchFIQC();
   453
   454        /*!
   455         *  ======== plug ========
   456         *  Plug an interrupt vector with an ISR address.
   457         *
   458         *  @param(intNum)  interrupt number
   459         *  @param(fxn)     pointer to ISR function
   460         */
   461        Void plug(UInt intNum, PlugFuncPtr fxn);
   462
   463        /*!
   464         *  const array to hold all HookSet objects.
   465         */
   466        config HookSet hooks[length] = [];
   467
   468        /*! Meta World Only Hwi Configuration Object. */
   469        metaonly struct InterruptObj {
   470            Bool used;              /* Interrupt already defined? */
   471            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   472            FuncPtr fxn;            /* Dispatched ISR function */
   473        };
   474
   475        /*!
   476         * Meta-only array of interrupt objects.
   477         * This meta-only array of Hwi config objects is initialized
   478         * in Hwi.xs:module$meta$init().
   479         */
   480        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   481
   482        struct Instance_State {
   483            Type        type;           // Interrupt Type
   484            UInt        priority;       // Interrupt Priority
   485            Bits32      disableMask0;   // REQENASET0 disable mask
   486            Bits32      disableMask1;   // REQENASET1 disable mask
   487            Bits32      restoreMask0;   // REQENASET0 restore mask
   488            Bits32      restoreMask1;   // REQENASET1 restore mask
   489            UArg        arg;            // Argument to Hwi function.
   490            FuncPtr     fxn;            // Hwi function.
   491            Int         intNum;         // Interrupt number
   492            Irp         irp;            // current IRP
   493            Ptr         hookEnv[];
   494        };
   495
   496        struct Module_State {
   497            VIM         *vim;
   498            Bits32      req0Mask;       // Initial REQENASET0 mask
   499            Bits32      req1Mask;       // Initial REQENASET1 mask
   500            UInt        irp;            // temporary irp storage for IRQ handler
   501            Char        *taskSP;        // temporary storage of interrupted
   502                                        // Task's SP during ISR execution
   503
   504            /* ROM */
   505            Char        *isrStack;      // Points to isrStack address
   506            Ptr         isrStackBase;   // _stack
   507            Ptr         isrStackSize;   // _STACK_SIZE
   508            Char        fiqStack[];     // buffer used for FIQ stack
   509            SizeT       fiqStackSize;
   510            UInt        *vimRam;        // VIM RAM
   511            Handle      dispatchTable[NUM_INTERRUPTS];
   512                                        // dispatch table
   513        };
   514    }
   515
   516    /*
   517     *  @(#) ti.sysbios.family.arm.tms570; 2, 0, 0, 0,237; 6-15-2011 16:24:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   518
   519     */
   520


package ti.sysbios.family.arm.tms570

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *  tms570 target-specific modules
    36     *
    37     */
    38
    39    requires ti.sysbios.interfaces;
    40
    41    /*!
    42     *  ======== ti.sysbios.family.tms570 ========
    43     *  Contains specifications for the tms570 family of device-specific SYS/BIOS functions.
    44     *
    45     */
    46    package ti.sysbios.family.arm.tms570 [2,0,0,0] {
    47        module Hwi;
    48        module TimestampProvider;
    49        module Timer;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arm.tms570; 2, 0, 0, 0,237; 6-15-2011 16:24:42; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.arm.tms570.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.tms570;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Types;
    44    import ti.sysbios.interfaces.ITimer;
    45    /*!
    46     *  ======== Timer ========
    47     *  Timer Peripherals Manager for arm_tms570 family.
    48     *
    49     *  @p(html)
    50     *  <h3> Calling Context </h3>
    51     *  <table border="1" cellpadding="3">
    52     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    53     *
    54     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    55     *    <!--                                                                                                                 -->
    56     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    61     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #getCount}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    68     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    71     *    <tr><td colspan="6"> Definitions: <br />
    72     *       <ul>
    73     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    74     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    75     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    76     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    77     *           <ul>
    78     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    79     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    80     *             <li> During main().</li>
    81     *             <li> During BIOS.startupFxns.</li>
    82     *           </ul>
    83     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    84     *           <ul>
    85     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    86     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    87     *           </ul>
    88     *       </ul>
    89     *    </td></tr>
    90     *
    91     *  </table>
    92     *  @p
    93     *
    94     */
    95    @InstanceFinalize       /* To cleanup */
    96    @InstanceInitError      /* To report unavailability of timer */
    97    @ModuleStartup          /* to configure static timers */
    98
    99    module Timer inherits ti.sysbios.interfaces.ITimer
   100    {
   101        /*! Max value of Timer period for PeriodType_COUNTS*/
   102        const UInt MAX_PERIOD = 0xffffffff;
   103
   104        /*! Number of timer peripherals on chip */
   105        const Int NUM_TIMER_DEVICES = 2;
   106
   107        /*! @_nodoc
   108         *  Min instructions to use in trigger().
   109         */
   110        const Int MIN_SWEEP_PERIOD = 8;
   111
   112        /*! Timer Configuration struct.
   113         *
   114         *  @field(cos)     When true timer stops counting during emulation halt.
   115         *                  When false timer continues to count during emulation
   116         *                  halt.
   117         */
   118        struct Control {
   119            Bool cos;      /*! 0=stop in debug mode; 1=continue in debug mode */
   120        };
   121
   122        /*! @_nodoc */
   123        @XmlDtd
   124        metaonly struct BasicView {
   125            Ptr         halTimerHandle;
   126            String      label;
   127            UInt        id;
   128            String      startMode;
   129            String      runMode;
   130            UInt        period;
   131            String      periodType;
   132            UInt        intNum;
   133            String      tickFxn[];
   134            UArg        arg;
   135            String      extFreq;
   136            UInt32      accuTicks;
   137            String      hwiHandle;
   138        };
   139
   140        /*! @_nodoc */
   141        metaonly struct DeviceView {
   142            UInt        id;
   143            String      device;
   144            String      devAddr;
   145            UInt        intNum;
   146            String      runMode;
   147            UInt        period;
   148            UInt        currCount;
   149            UInt        remainingCount;
   150            String      state;
   151        };
   152
   153        /*! @_nodoc */
   154        metaonly struct ModuleView {
   155            String      availMask;      /* available 32-bit timer halves */
   156        }
   157
   158        /*! @_nodoc */
   159        @Facet
   160        metaonly config ViewInfo.Instance rovViewInfo =
   161            ViewInfo.create({
   162                viewMap: [
   163                [
   164                    'Basic',
   165                    {
   166                        type: ViewInfo.INSTANCE,
   167                        viewInitFxn: 'viewInitBasic',
   168                        structName: 'BasicView'
   169                    }
   170                ],
   171                [
   172                    'Device',
   173                    {
   174                        type: ViewInfo.INSTANCE,
   175                        viewInitFxn: 'viewInitDevice',
   176                        structName: 'DeviceView'
   177                    }
   178                ],
   179                [
   180                    'Module',
   181                    {
   182                        type: ViewInfo.MODULE,
   183                        viewInitFxn: 'viewInitModule',
   184                        structName: 'ModuleView'
   185                    }
   186                ],
   187                ]
   188            });
   189
   190        /*!
   191         *  Error raised when timer id specified is not supported.
   192         */
   193        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   194
   195        /*!
   196         *  Error raised when timer requested is in use
   197         */
   198        config Error.Id E_notAvailable  =
   199            {msg: "E_notAvailable: Timer not available %d"};
   200
   201        /*!
   202         *  Error raised when Hwi Params has mask where self is turned on.
   203         *
   204         *  This is not allowed because the timers on this platform do not
   205         *  support one-shot mode and a stub is used to stop it.
   206         *  Another timer interrupt cannot go off when the ISR is running.
   207         */
   208        config Error.Id E_invalidHwiMask  =
   209            {msg: "E_InvalidMask: Mask in hwiParams cannot enable self"};
   210
   211        /*!
   212         *  Error raised when period requested is not supported
   213         */
   214        config Error.Id E_cannotSupport  =
   215            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   216
   217        /*!
   218         *  ======== anyMask ========
   219         *  Available mask to be used when select = Timer_ANY
   220         */
   221        config UInt anyMask = 0x3;
   222
   223        /*!
   224         *  ======== oneShotStub ========
   225         *  @_nodoc
   226         *  RTI timer does not support one shot mode. This stub stops timer
   227         *  and disables its interrupt.
   228         *
   229         *  @param(arg)     Timer Handle.
   230         */
   231        Void oneShotStub(UArg arg);
   232
   233        /*!
   234         *  ======== periodicStub ========
   235         *  @_nodoc
   236         *  When accuTicks = true, this stub does the tick accumulation.
   237         *
   238         *  @param(arg)     Timer Handle.
   239         */
   240        Void periodicStub(UArg arg);
   241
   242        /*!
   243         *  ======== getHandle ========
   244         *  @_nodoc
   245         *  Used by TimestampProvider module to get hold of timer handle used by
   246         *  Clock.
   247         *
   248         *  @param(id)      timer Id.
   249         */
   250        Handle getHandle(UInt id);
   251
   252    instance:
   253
   254
   255        /*! Control register configuration. Default cos=0. */
   256        config Control controlRegInit = {cos: 0};
   257
   258        /*! Hwi Params for Hwi Object. Default is null.*/
   259        config Hwi.Params *hwiParams = null;
   260
   261        /*! Hwi intNum to be used by Timer. */
   262        config Int intNum = -1;
   263
   264        /*!
   265         *  ======== reconfig ========
   266         *  Used to modify static timer instances at runtime.
   267         *
   268         *  @param(timerParams)     timer Params
   269         *  @param(tickFxn)         functions that runs when timer expires.
   270         */
   271        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   272
   273        /*!
   274         *  ======== getAccuTicks ========
   275         *  @_nodoc
   276         *  returns accumulated ticks. Used by TimestampProvider.
   277         *
   278         *  @b(returns)     get accumulated ticks
   279         */
   280        UInt32 getAccuTicks();
   281
   282        /*!
   283         *  ======== ackInterrupt ========
   284         *  clear the current timer interrupt flag
   285         */
   286        Void ackInterrupt();
   287
   288    internal:   /* not for client use */
   289
   290        /*!
   291         *  ======== noStartupNeeded ========
   292         *  Flag used to prevent misc code from being brought in
   293         *  un-necessarily
   294         */
   295        config UInt startupNeeded = false;
   296
   297        struct Instance_State {
   298            Bool                    staticInst;
   299            Int                     id;
   300            UInt                    controlRegInit;
   301            ITimer.RunMode          runMode;
   302            ITimer.StartMode        startMode;
   303            UInt                    period;
   304            ITimer.PeriodType       periodType;
   305            UInt                    intNum;
   306            UArg                    arg;
   307            Hwi.FuncPtr             tickFxn;
   308            Types.FreqHz            extFreq;
   309            volatile UInt32         accuTicks;
   310            Hwi.Handle              hwi;
   311        }
   312
   313        struct Module_State {
   314            UInt            availMask;      /* available peripherals */
   315            Handle          handles[NUM_TIMER_DEVICES];
   316                                            /* array of handles based on id */
   317        }
   318    }
   319    /*
   320     *  @(#) ti.sysbios.family.arm.tms570; 2, 0, 0, 0,237; 6-15-2011 16:24:42; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   321
   322     */
   323


module ti.sysbios.family.arm.tms570.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.arm.tms570;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     */
    76
    77    @ModuleStartup          /* To get Clock Timer Handle */
    78
    79    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    80    {
    81        /*! @_nodoc */
    82        @XmlDtd
    83        metaonly struct Module_View {
    84        };
    85
    86    internal:   /* not for client use */
    87
    88        UInt32 getCCNT32();
    89        UInt32 getOverflowCCNT();
    90        Void initCCNT();
    91
    92        struct Module_State {
    93            UInt32          upper32Bits;    /* upper 32 bits of counter */
    94        }
    95    }
    96    /*
    97     *  @(#) ti.sysbios.family.arm.tms570; 2, 0, 0, 0,237; 6-15-2011 16:24:42; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    98
    99     */
   100


module ti.sysbios.family.arp32.CTM

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== CTM.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arp32;
    38
    39    /*!
    40     *  ======== CTM ========
    41     *  Counter Timer Module Device Definitions.
    42     *
    43     *  For Ducati SYS/BIOS applications,
    44     *  Counter/timer 0 is assigned to core 0's Timer 0 interrupt 18
    45     *  Counter/timer 1 is assigned to core 1's Timer 0 interrupt 22
    46     *  Counters 2/3 are assigned to core 0's TimestampProvider
    47     *  Counters 4/5 are assigned to core 1's TimestampProvider
    48     *  Counters 6,7 are for application use.
    49     *
    50     *  Counters 2/3 and 4/5 are in chained mode and started simultaneously
    51     *  by core 0 so that both cores timestamps are in sync with each other
    52     *  AND both chained timers have independent SHADOW registers to guarantee
    53     *  64bit counter reading coherency.
    54     */
    55
    56    module CTM
    57    {
    58        /*!
    59         *  Counter Timer Module
    60         *  Physical Base address is 0x55080400
    61         *  Auto-configured virtual Base address is 0x40000400
    62         */
    63        struct CTM {
    64            UInt32 CTCNTL;          /*! 0x0000 */
    65            UInt32 RES_04 [7];      /*! 0x0004 - 0x0020 */
    66            UInt32 CTSTMCNTL;       /*! 0x0020 */
    67            UInt32 CTSTMMSTID;      /*! 0x0024 */
    68            UInt32 CTSTMINTVL;      /*! 0x0028 */
    69            UInt32 CTSTMSEL0;       /*! 0x002C */
    70            UInt32 CTSTMSEL1;       /*! 0x0030 */
    71            UInt32 RES_34 [3];      /*! 0x0034 - 0x0040 */
    72            UInt32 TINTVLR[8];      /*! 0x0040 - 0x0060 */
    73            UInt32 RES_60 [7];      /*! 0x0060 - 0x007C */
    74            UInt32 CTNUMDBG;        /*! 0x007C */
    75            UInt32 CTDBGSGL [8];    /*! 0x0080 - 0x00A0 */
    76            UInt32 RES_A0 [20];     /*! 0x00A0 - 0x00F0 */
    77            UInt32 CTGNBL [2];      /*! 0x00F0 - 0x00F8 */
    78            UInt32 CTGRST [2];      /*! 0x00F8 - 0x0100 */
    79            UInt32 CTCR [32];       /*! 0x0100 - 0x0180 */
    80            UInt32 CTCNTR [32];     /*! 0x0180 - 0x0200 */
    81        }
    82
    83        /*!
    84         * Physical CTM Device.
    85         * Short name is "CTM_ctm"
    86         * Long name is "ti_sysbios_family_arp32.CTM_ctm"
    87         */
    88        extern volatile CTM ctm;
    89    }
    90
    91    /*
    92     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:46; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    93
    94     */
    95


module ti.sysbios.family.arp32.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37    import xdc.rov.ViewInfo;
    38
    39    import xdc.runtime.Diags;
    40    import xdc.runtime.Log;
    41    import xdc.runtime.Assert;
    42    import xdc.runtime.Error;
    43
    44    /*!
    45     *  ======== Hwi ========
    46     *  ARP32 Hardware Interrupt Support Module.
    47     *
    48     *  This Hwi module provides ARP32 family-specific implementations of the
    49     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    50     *
    51     *  Additional ARP32 device-specific APIs are also provided.
    52     *
    53     *  @a(NOTE)
    54     *  In this Hwi module implementation, the instance config parameter value
    55     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    56     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    57     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    58     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    59     *  silently converted to {@link #MaskingOption_SELF}.
    60     *
    61     *  @p(html)
    62     *  <h3> Calling Context </h3>
    63     *  <table border="1" cellpadding="3">
    64     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    65     *
    66     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    67     *    <!--                                                                                                                 -->
    68     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #disableIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #enableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    78     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td> {@link #restoreIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td colspan="6"> Definitions: <br />
    89     *       <ul>
    90     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    91     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    92     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    93     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    94     *           <ul>
    95     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    96     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    97     *             <li> During main().</li>
    98     *             <li> During BIOS.startupFxns.</li>
    99     *           </ul>
   100     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   101     *           <ul>
   102     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   103     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   104     *           </ul>
   105     *       </ul>
   106     *    </td></tr>
   107     *
   108     *  </table>
   109     *  @p
   110     *
   111     */
   112
   113    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   114    @ModuleStartup         /* generate a call to Hwi_init at startup */
   115
   116    module Hwi inherits ti.sysbios.interfaces.IHwi
   117    {
   118        // -------- Module Constants --------
   119
   120        /*! ARP32 supports 8 interrupts. */
   121        const Int NUM_INTERRUPTS = 8;
   122
   123        // -------- Module Types --------
   124
   125        /*! @_nodoc Hwi plug function type definition. */
   126        typedef Void (*PlugFuncPtr)(void);
   127
   128        /*!
   129         *  ======== BasicView ========
   130         *  @_nodoc
   131         */
   132        metaonly struct BasicView {
   133            Ptr         halHwiHandle;
   134            String      label;
   135            UInt        intNum;
   136            String      fxn;
   137            UArg        arg;           // Argument to Hwi function.
   138            Ptr         irp;
   139            String      disableMask;   // Interrupts to mask during ISR.
   140            String      restoreMask;   // Interrupts to restore after ISR.
   141        };
   142
   143        /*!
   144         *  ======== ModuleView ========
   145         *  @_nodoc
   146         */
   147        metaonly struct ModuleView {
   148            String      options[4];
   149            SizeT       hwiStackPeak;
   150            SizeT       hwiStackSize;
   151            Ptr         hwiStackBase;
   152        };
   153
   154        /*!
   155         *  ======== rovViewInfo ========
   156         *  @_nodoc
   157         */
   158        @Facet
   159        metaonly config ViewInfo.Instance rovViewInfo =
   160            ViewInfo.create({
   161                viewMap: [
   162                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   163                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   164                ]
   165            });
   166
   167        // -------- Module Parameters --------
   168
   169        /*!
   170         *  non-dispatched interrupt object.
   171         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   172         */
   173        metaonly struct NonDispatchedInterrupt {
   174            Int             intNum;
   175            PlugFuncPtr     fxn;            /*! "Hwi_plug'd" ISR function. */
   176            Bool            enableInt;
   177        };
   178
   179        /*!
   180         *  non-dispatched interrupt array.
   181         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   182         */
   183        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   184
   185        /*!
   186         *  Alternate reset vector address. Default is undefined.
   187         *
   188         *  if initialized by the user then an additional reset vector
   189         *  is created and placed in the ".resetVector" section.
   190         *  To place the .resetVector section into a specific memory section,
   191         *  add the following command to your config script:
   192         *  @p(code)
   193         *  Program.sectMap[".resetVector"] = YourMemorySection;
   194         *  @p
   195         */
   196        metaonly config Ptr resetVectorAddress;
   197
   198        /*!
   199         *  Error raised when Hwi is already defined
   200         */
   201        config Error.Id E_alreadyDefined = {
   202            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   203        };
   204
   205        /*!
   206         *  Error raised when a Hwi function that has not been implemented
   207         *  for the arp32 has been called
   208         */
   209        config Error.Id E_notImplemented = {
   210            msg: "E_notImplemented: Function not implemented: %s"
   211        };
   212
   213        /*!
   214         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   215         */
   216        config Log.Event LM_begin = {
   217            mask: Diags.USER1 | Diags.USER2,
   218            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   219        };
   220
   221        /*!
   222         *  Issued just after return from Hwi function (with interrupts disabled)
   223         */
   224        config Log.Event LD_end = {
   225            mask: Diags.USER2,
   226            msg: "LD_end: hwi: 0x%x"
   227        };
   228
   229        // -------- Module Functions --------
   230
   231        /*!
   232         *  ======== disable ========
   233         */
   234        @Macro
   235        override UInt disable();
   236
   237        /*!
   238         *  ======== enable ========
   239         */
   240        @Macro
   241        override UInt enable();
   242
   243        /*!
   244         *  ======== restore ========
   245         */
   246        @Macro
   247        override Void restore(UInt key);
   248
   249        /*! Stub to be plugged for dsp-eve interrupts */
   250        Void selfLoop(UArg arg);
   251
   252        /*!
   253         *  ======== inUseMeta ========
   254         *  @_nodoc
   255         *  Check for Hwi already in use.
   256         *  For internal SYS/BIOS use only.
   257         *  Should be called prior to any internal Hwi.create().
   258         *
   259         *  @param(intNum)  interrupt number
   260         */
   261        metaonly Bool inUseMeta(UInt intNum);
   262
   263        /*!
   264         *  ======== plugMeta ========
   265         *  Statically plug an interrupt vector with an ISR address.
   266         *
   267         *  @param(intNum)  interrupt number
   268         *  @param(fxn)     pointer to ISR function
   269         */
   270        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   271
   272        /*!
   273         *  ======== getHandle ========
   274         *  Returns Hwi_handle associated with interrupt number
   275         *
   276         *  @param(intNum)  interrupt number
   277         *  @b(returns)     handle associated with intNum
   278         */
   279        Handle getHandle(UInt intNum);
   280
   281        /*!
   282         *  ======== disableIER ========
   283         *  Disable certain maskable interrupts.
   284         *
   285         *  Atomically disables specific interrupts by clearing the bits
   286         *  specified by mask in the Interrupt Enable Register (IER).
   287         *
   288         *  The IER bits to be cleared should be set to 1 in the mask.
   289         *
   290         *  @param(mask)    bitmask of interrupts to disable
   291         *  @b(returns)     previous IER settings bitmask
   292         */
   293        Bits16 disableIER(Bits16 mask);
   294
   295        /*!
   296         *  ======== enableIER ========
   297         *  Enable certain maskable interrupts.
   298         *
   299         *  Atomically enables specific interrupts by setting the bits
   300         *  specified by mask in the Interrupt Enable Register (IER).
   301         *
   302         *  The IER bits to be set should be set to 1 in the mask.
   303         *
   304         *  @param(mask)    bitmask of interrupts to enable
   305         *  @b(returns)     previous IER settings bitmask
   306         */
   307        Bits16 enableIER(Bits16 mask);
   308
   309        /*!
   310         *  ======== restoreIER ========
   311         *  Restore maskable interrupts to the state they were in
   312         *  when either disableIER() or enableIER() was called.
   313         *
   314         *  Atomically writes the given mask to the IER register. Typically used
   315         *  to restore the IER register to the state returned from a call to
   316         *  either {@link #disableIER()} or {@link #enableIER()}.
   317         *
   318         *  @param(mask)    bitmask of interrupts to restore
   319         *  @b(returns)     previous IER settings bitmask
   320         */
   321        Bits16 restoreIER(Bits16 mask);
   322
   323    instance:
   324
   325        /*!
   326         *  Dispatcher auto-nesting interrupt disable mask.
   327         *
   328         *  When the dispatcher's auto interrupt nesting support feature
   329         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   330         *  this mask defines which IER bits are disabled prior to invoking
   331         *  the user's ISR function with GIE = 1.
   332         *
   333         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   334         *  prior to invoking the ISR.
   335         *
   336         *  The value of this mask is normally auto-calculated based on the
   337         *  value of the maskSetting. However, manual setting of this
   338         *  mask is enabled by setting the maskSetting to
   339         *  {@link #MaskingOption MaskingOption_BITMASK}.
   340         *
   341         *  The default value is derived from the
   342         *  {@link #MaskingOption MaskingOption_SELF}
   343         *  maskSetting.
   344         */
   345        config Bits16 disableMask = 0;
   346
   347        /*!
   348         *  Dispatcher auto-nesting interrupt restore mask.
   349         *
   350         *  When the dispatcher's auto interrupt nesting support feature
   351         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   352         *  this mask defines which IER bits are restored to their previous
   353         *  setting upon return from the user's ISR function.
   354         *
   355         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   356         *
   357         *  The value of this mask is normally auto-calculated based on the
   358         *  value of the maskSetting. However, manual setting of this
   359         *  mask is enabled by setting the maskSetting to
   360         *  {@link #MaskingOption MaskingOption_BITMASK}.
   361         *
   362         *  The default value is derived from the
   363         *  {@link #MaskingOption MaskingOption_SELF}
   364         *  maskSetting.
   365         */
   366        config Bits16 restoreMask = 0;
   367
   368        /*!
   369         *  Interrupt priority. Not supported on this target.
   370         */
   371        override config Int priority = 0;
   372
   373        /*!
   374         *  ======== reconfig ========
   375         *  Reconfigures a dispatched interrupt.
   376         *
   377         *  This function reconfigures the dispatched interrupt so the
   378         *  specified function is called with the specified parameters.
   379         *
   380         *  @param(fxn)     pointer to ISR function
   381         *  @param(params)  pointer to Hwi parameter structure
   382         */
   383        Void reconfig(FuncPtr fxn, const Params *params);
   384
   385    internal:   /* not for client use */
   386
   387        /*
   388         * Swi and Task module function pointers.
   389         * Used to decouple Hwi from Swi and Task when
   390         * dispatcherSwiSupport or
   391         * dispatcherTaskSupport is false.
   392         */
   393        config UInt (*swiDisable)();
   394        config Void (*swiRestoreHwi)(UInt);
   395        config UInt (*taskDisable)();
   396        config Void (*taskRestoreHwi)(UInt);
   397
   398        /*!
   399         *  const array to hold all HookSet objects.
   400         */
   401        config HookSet hooks[length] = [];
   402
   403        /*
   404         *  ======== getIsrStackAddress ========
   405         *  Returns initial isrStack address.
   406         *  This API was developed solely for the Exception module
   407         *  to allow removal of the Hwi_link.xdt template definition
   408         *  of ti_sysbios_family_c64p_Hwi_isrStack which was not
   409         *  ROM-able
   410         */
   411        Char *getIsrStackAddress();
   412
   413        /* Interrupt Dispatcher */
   414        Void dispatchC(Int intNum);
   415
   416        /* unPlugged interrupt handler */
   417        Void unPluggedInterrupt();
   418        Void nmiInterrupt();
   419        Void swiInterrupt();
   420        Void undefInterrupt();
   421
   422        /* stubs which call the dispatcher and pass intnum */
   423        Void dispIsr3();
   424        Void dispIsr4();
   425        Void dispIsr5();
   426        Void dispIsr6();
   427
   428        /*! Meta World Only Hwi Configuration Object. */
   429        metaonly struct InterruptObj {
   430            String name;            /* symbol used for vector table entry */
   431            Bool used;              /* Interrupt already defined? */
   432            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   433            FuncPtr fxn;            /* Dispatched ISR function */
   434            PlugFuncPtr pfxn;       /* "Hwi_plug'd" ISR function. */
   435        };
   436
   437        /*!
   438         * Meta-only array of interrupt objects.
   439         * This meta-only array of Hwi config objects is initialized
   440         * in Hwi.xs:module$meta$init().
   441         */
   442        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   443
   444        struct Instance_State {
   445            Bits16      disableMask;    // Interrupts to mask during ISR.
   446            Bits16      restoreMask;    // Interrupts to restore after ISR.
   447            UArg        arg;            // Argument to Hwi function.
   448            FuncPtr     fxn;            // Hwi function.
   449            Irp         irp;            // current IRP
   450            Ptr         hookEnv[];
   451        };
   452
   453        struct Module_State {
   454            Bits16      ierMask;        // Initial IER mask
   455            Char        *taskSP;        // temporary storage of interrupted
   456                                        // Task's SP during ISR execution
   457            /* ROM */
   458            Char        *isrStack;      // Points to isrStack address
   459            Ptr             bss;        // bss address
   460
   461            Handle      dispatchTable[NUM_INTERRUPTS];
   462                                        // dispatch table
   463        };
   464    }
   465    /*
   466     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:46; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   467
   468     */
   469


package ti.sysbios.family.arp32

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.knl.tests ========
    39     *  Contains specifications for the unit tests of the SYS/BIOS kernel.
    40     *
    41     */
    42    package ti.sysbios.family.arp32 [2,0,0,0]{
    43        module Hwi;
    44        module TaskSupport;
    45        module Timer;
    46        module CTM;
    47        module TimestampProvider;
    48        module IntrinsicsSupport;
    49        module Settings;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.arp32.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.arp32;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  C64 target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.arp32.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== TaskSupport ========
    39     *  ARP32 Task Support Module.
    40     */
    41    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    42    {
    43        /*! default Task stack size. */
    44        override readonly config SizeT defaultStackSize = 1024;
    45
    46        /*! required stack alignment (in MAUs). */
    47        override readonly config UInt stackAlignment = 8;
    48    }
    49    /*
    50     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    51
    52     */
    53


module ti.sysbios.family.arp32.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.arp32;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.family.arp32.Hwi;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripherals Manager.
    50     *
    51     *  The timers used are the two CTM timers (0 and 1)
    52     *  that support interrupts.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    58     *
    59     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    60     *    <!--                                                                                                                 -->
    61     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    62     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    63     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    64     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99    @InstanceFinalize       /* To cleanup */
   100    @InstanceInitError      /* To report unavailability of timer */
   101    @ModuleStartup          /* to configure static timers */
   102
   103    module Timer inherits ti.sysbios.interfaces.ITimer
   104    {
   105        /*! Max value of Timer period for PeriodType_COUNTS*/
   106        const UInt MAX_PERIOD = 0xffffffff;
   107
   108        /*!
   109         *  Number of timer peripherals on chip
   110         *
   111         *  Only 2 are available to each core.
   112         */
   113        const Int NUM_TIMER_DEVICES = 2;
   114
   115        /*! Timer clock divider wrt cpu clock */
   116        const Int TIMER_CLOCK_DIVIDER = 1;
   117
   118        /*! @_nodoc
   119         *  Min instructions to use in trigger().
   120         */
   121        const Int MIN_SWEEP_PERIOD = 1;
   122
   123        /*! @_nodoc */
   124        @XmlDtd
   125        metaonly struct BasicView {
   126            Ptr         halTimerHandle;
   127            String      label;
   128            UInt        id;
   129            String      device;
   130            String      startMode;
   131            String      runMode;
   132            UInt        period;
   133            String      periodType;
   134            UInt        intNum;
   135            String      tickFxn[];
   136            UArg        arg;
   137            String      extFreq;
   138            String      hwiHandle;
   139        };
   140
   141
   142        /*! @_nodoc */
   143        metaonly struct ModuleView {
   144            String      availMask;      /* available 32-bit timer halves */
   145        }
   146
   147        /*! @_nodoc */
   148        metaonly struct DeviceView {
   149            UInt        id;
   150            String      device;
   151            String      devAddr;
   152            UInt        intNum;
   153            String      runMode;
   154            UInt        period;
   155            UInt        currCount;
   156            UInt        remainingCount;
   157        };
   158
   159        /*! @_nodoc */
   160        @Facet
   161        metaonly config ViewInfo.Instance rovViewInfo =
   162            ViewInfo.create({
   163                viewMap: [
   164                [
   165                    'Basic',
   166                    {
   167                        type: ViewInfo.INSTANCE,
   168                        viewInitFxn: 'viewInitBasic',
   169                        structName: 'BasicView'
   170                    }
   171                ],
   172                [
   173                    'Device',
   174                    {
   175                        type: ViewInfo.INSTANCE,
   176                        viewInitFxn: 'viewInitDevice',
   177                        structName: 'DeviceView'
   178                    }
   179                ],
   180                [
   181                    'Module',
   182                    {
   183                        type: ViewInfo.MODULE,
   184                        viewInitFxn: 'viewInitModule',
   185                        structName: 'ModuleView'
   186                    }
   187                ],
   188                ]
   189            });
   190
   191        /*!
   192         *  Error raised when timer id specified is not supported.
   193         */
   194        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   195
   196        /*!
   197         *  Error raised when timer requested is in use
   198         */
   199        config Error.Id E_notAvailable  =
   200                {msg: "E_notAvailable: Timer not available %d"};
   201
   202        /*!
   203         *  Error raised when period requested is not supported
   204         */
   205        config Error.Id E_cannotSupport  =
   206                {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   207
   208        /*!
   209         *  ======== anyMask ========
   210         *  Available mask to be used when select = Timer_ANY
   211         */
   212        config UInt anyMask = 0x3;
   213
   214        /*!
   215         *  ======== getHandle ========
   216         *  Get Handle associated with a timer id.
   217         *
   218         *  @param(id)      timer Id.
   219         *  @b(returns)     timer Handle
   220         */
   221        @DirectCall
   222        Handle getHandle(UInt id);
   223
   224    instance:
   225
   226        /*! Hwi Params for Hwi Object. Default is null. */
   227        config Hwi.Params *hwiParams = null;
   228
   229        /*!
   230         *  ======== reconfig ========
   231         *  Used to modify static timer instances at runtime.
   232         *
   233         *  @param(timerParams)     timer Params
   234         *  @param(tickFxn)         function that runs when timer expires
   235         */
   236        @DirectCall
   237        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   238
   239
   240    internal:   /* not for client use */
   241
   242        /*!
   243         *  ======== noStartupNeeded ========
   244         *  Flag used to prevent misc code from being brought in
   245         *  un-necessarily
   246         */
   247        config UInt startupNeeded = false;
   248
   249        struct Instance_State {
   250            Bool        staticInst;
   251            Int         id;
   252            Int         ctmid;          /* CTM counter ID */
   253            RunMode     runMode;
   254            StartMode   startMode;
   255            UInt        period;
   256            PeriodType  periodType;
   257            UInt        intNum;
   258            UArg        arg;
   259            Hwi.FuncPtr tickFxn;
   260            Types.FreqHz extFreq;       /* external frequency in Hz */
   261            Hwi.Handle  hwi;
   262        }
   263
   264        struct Module_State {
   265            UInt    availMask;                  /* available peripherals */
   266            UInt    *baseAddr;                  /* add this here to make it work */
   267            Handle  handles[NUM_TIMER_DEVICES]; /* array of handles based on id */
   268        }
   269    }
   270    /*
   271     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   272
   273     */
   274


module ti.sysbios.family.arp32.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    /*!
    39     *  ======== TimestampProvider ========
    40     *
    41     *  @p(html)
    42     *  <h3> Calling Context </h3>
    43     *  <table border="1" cellpadding="3">
    44     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    45     *
    46     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    47     *    <!--                                                                                                                 -->
    48     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    49     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    50     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *
    52     *  </table>
    53     *  @p
    54     */
    55
    56    @ModuleStartup          /* To get Clock Timer Handle */
    57
    58    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    59    {
    60    }
    61    /*
    62     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,21; 6-15-2011 16:24:47; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    63
    64     */
    65


module ti.sysbios.family.c28.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c28;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43    import xdc.runtime.Assert;
    44    import xdc.runtime.Error;
    45
    46    /*!
    47     *  ======== Hwi ========
    48     *  C28x Hardware Interrupt Manager
    49     *
    50     *  This Hwi module provides C28 family-specific implementations of the
    51     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    52     *
    53     *  Additional C28 device-specific APIs are also provided.
    54     *
    55     *  ISRs specified with Hwi_plug will not go through the dispatcher; the
    56     *  ISR function will be directly plugged into the vector table. Hwi_plug can
    57     *  be used for any ISR which does not call any SYS/BIOS APIs.
    58     *
    59     *  ISRs can be plugged or created statically in the configuration script or
    60     *  dynamically at runtime.
    61     *
    62     *  @p(html)
    63     *  <h3> PIE interrupts </h3>
    64     *  The peripheral interrupt expansion (PIE) block multiplexes 96 interrupts
    65     *  into 12 CPU interrupts. The PIE vector table includes entries for each of
    66     *  these 96 interrupts.  The relationship between the numbers corresponding
    67     *  to PIE interrupts and their groups (CPU interrupt) is as follows:
    68     *  PIEGROUPNUM = [(PIENUM - 32) / 8] + 1
    69     *
    70     *  <h4>PIE MUXed Peripheral Interrupt Vector Table</h4>
    71     *  The table below shows a mapping between the PIENUM (interrupt id) and the
    72     *  various PIE groups. INTX.Y represents the interrupt number for the PIE
    73     *  interrupt belonging to group X and group-specific id Y.
    74     *  <br><br>
    75     *  <table border="1" cellpadding="3">
    76     *  <tr><th>      </th><th>INTX.1</th><th>INTX.2</th><th>INTX.3</th><th>INTX.4</th><th>INTX.5</th><th>INTX.6</th><th>INTX.7</th><th>INTX.8</th></tr>
    77     *  <tr><th>INT1.Y</th><td>32</td><td>33</td><td>34</td><td>35</td><td>36</td><td>37</td><td>38</td><td>39</td></tr>
    78     *  <tr><th>INT2.Y</th><td>40</td><td>41</td><td>42</td><td>43</td><td>44</td><td>45</td><td>46</td><td>47</td></tr>
    79     *  <tr><th>INT3.Y</th><td>48</td><td>49</td><td>50</td><td>51</td><td>52</td><td>53</td><td>54</td><td>55</td></tr>
    80     *  <tr><th>INT4.Y</th><td>56</td><td>57</td><td>58</td><td>59</td><td>60</td><td>61</td><td>62</td><td>63</td></tr>
    81     *  <tr><th>INT5.Y</th><td>64</td><td>65</td><td>66</td><td>67</td><td>68</td><td>69</td><td>70</td><td>71</td></tr>
    82     *  <tr><th>INT6.Y</th><td>72</td><td>73</td><td>74</td><td>75</td><td>76</td><td>77</td><td>78</td><td>79</td></tr>
    83     *  <tr><th>INT7.Y</th><td>80</td><td>81</td><td>82</td><td>83</td><td>84</td><td>85</td><td>86</td><td>87</td></tr>
    84     *  <tr><th>INT8.Y</th><td>88</td><td>89</td><td>90</td><td>91</td><td>92</td><td>93</td><td>94</td><td>95</td></tr>
    85     *  <tr><th>INT9.Y</th><td>96</td><td>97</td><td>98</td><td>99</td><td>100</td><td>101</td><td>102</td><td>103</td></tr>
    86     *  <tr><th>INT10.Y</th><td>104</td><td>105</td><td>106</td><td>107</td><td>108</td><td>109</td><td>110</td><td>111</td></tr>
    87     *  <tr><th>INT11.Y</th><td>112</td><td>113</td><td>114</td><td>115</td><td>116</td><td>117</td><td>118</td><td>119</td></tr>
    88     *  <tr><th>INT12.Y</th><td>120</td><td>121</td><td>122</td><td>123</td><td>124</td><td>125</td><td>126</td><td>127</td></tr>
    89     *  </table>
    90     *  <br>
    91     *
    92     *  PIE interrupts must clear the CPU acknowledge bit for their respective PIE
    93     *  block before further interrupts from that block can occur. The SYS/BIOS 6
    94     *  dispatcher (used by interrupts created using {@link #create}) takes care of
    95     *  this, however this differs from DSP/BIOS 5, in which the application is
    96     *  expected to acknowledge the interrupt.
    97     *
    98     *  PIE interrupt ISRs plugged with {@link #plug}(which do not use the
    99     *  dispatcher), as well as legacy created PIE HWI instances, must
   100     *  acknowledge the interrupt manually before returning from the ISR.
   101     *
   102     *  The Hwi module supports zero latency operation.  CPU interrupts classified
   103     *  as zero latency are not disabled by the {@link #disable} call and are
   104     *  generally left enabled except when explicitly disabled using
   105     *  {@link #disableIER} or {@link #disablePIEIER}.  Refer to
   106     *  {@link #zeroLatencyIERMask} for using information.
   107     *
   108     *  The following configuration code can be used to plug the function
   109     *  'myHwi' into the vector table for PIE group 5, interrupt 1.  Using the above
   110     *  table, one can see that this corresponds to interrupt ID 64:
   111     *
   112     *  @p(code)
   113     *      Program.global.hwi5 = Hwi.create(64, '&myHwi');
   114     *  @p
   115     *
   116     *  @a(NOTE)
   117     *  In this Hwi module implementation, the instance config parameter value
   118     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
   119     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
   120     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
   121     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
   122     *  silently converted to {@link #MaskingOption_SELF}.
   123     *
   124     *  @p(html)
   125     *  <h3> Calling Context </h3>
   126     *  <table border="1" cellpadding="3">
   127     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   128     *
   129     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   130     *    <!--                                                                                                                 -->
   131     *    <tr><td> {@link #clearInterrupt}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   132     *    <tr><td> {@link #disable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   133     *    <tr><td> {@link #disableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   134     *    <tr><td> {@link #disableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   135     *    <tr><td> {@link #disablePIEIER}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   136     *    <tr><td> {@link #enable}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   137     *    <tr><td> {@link #enableIER}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   138     *    <tr><td> {@link #enableInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   139     *    <tr><td> {@link #enablePIEIER}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   140     *    <tr><td> {@link #getHandle}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   141     *    <tr><td> {@link #getIFR}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   142     *    <tr><td> {@link #getIntrReturnAddr} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   143     *    <tr><td> {@link #Params_init}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   144     *    <tr><td> {@link #pieEnabled}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   145     *    <tr><td> {@link #plug}              </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   146     *    <tr><td> {@link #restore}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   147     *    <tr><td> {@link #restoreIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   148     *    <tr><td> {@link #restoreInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   149     *    <tr><td> {@link #ack}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   150     *    <tr><td> {@link #create}            </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   151     *    <tr><td> {@link #construct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   152     *    <tr><td> {@link #delete}            </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   153     *    <tr><td> {@link #destruct}          </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   154     *    <tr><td> {@link #getHookContext}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   155     *    <tr><td> {@link #reconfig}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   156     *    <tr><td> {@link #setFunc}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   157     *    <tr><td> {@link #setHookContext}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   158     *    <tr><td colspan="6"> Definitions: <br />
   159     *       <ul>
   160     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   161     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   162     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   163     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   164     *           <ul>
   165     *             <li> In your module startup after this module is started (e.g.
   166                        Hwi_Module_startupDone() returns TRUE). </li>
   167     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   168     *             <li> During main().</li>
   169     *             <li> During BIOS.startupFxns.</li>
   170     *           </ul>
   171     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   172     *           <ul>
   173     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   174     *             <li> In your module startup before this module is started
   175                        (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   176     *           </ul>
   177     *       </ul>
   178     *    </td></tr>
   179     *
   180     *
   181     *  </table>
   182     *  @p
   183     *
   184     */
   185
   186    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   187    @ModuleStartup          /* generate a call to Hwi_init at startup */
   188
   189    module Hwi inherits ti.sysbios.interfaces.IHwi
   190    {
   191
   192        // -------- Module Constants --------
   193
   194        /*! C28 supports 32 interrupts. */
   195        const Int NUM_INTERRUPTS = 32;
   196        /*! C28 supports 96 PIE interrupts */
   197        const Int NUM_INTERRUPTS_PIE = 96;
   198        const Int NUM_INTERRUPTS_ALL = NUM_INTERRUPTS + NUM_INTERRUPTS_PIE;
   199
   200        // -------- Module Types --------
   201
   202        /*! Hwi plug function type definition, which doesn't take an arg. */
   203        typedef Void (*PlugFuncPtr)(void);
   204
   205        /*! @_nodoc */
   206        metaonly struct BasicView {
   207            Ptr         halHwiHandle;
   208            String      label;
   209            Int         intNum;
   210            String      fxn;
   211            UArg        arg;
   212            Ptr         irp;
   213            String      disableMask;   /* Interrupts to mask during ISR.   */
   214            String      restoreMask;   /* Interrupts to restore after ISR. */
   215        };
   216
   217        /*! @_nodoc */
   218        metaonly struct ModuleView {
   219            String      options[4];
   220            SizeT       hwiStackPeak;
   221            SizeT       hwiStackSize;
   222            Ptr         hwiStackBase;
   223            String      globalEnable;
   224            String      shadowIER;
   225        };
   226
   227        /*! @_nodoc */
   228        @Facet
   229        metaonly config ViewInfo.Instance rovViewInfo =
   230            ViewInfo.create({
   231                viewMap: [
   232                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   233                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   234                ]
   235            });
   236
   237        /*!
   238         *  Assert raised when an invalid interrupt number is passed to a Hwi call
   239         */
   240        config Assert.Id A_badIntNum = {
   241            msg: "A_badIntNum: Invalid interrupt number"
   242        };
   243
   244        /*!
   245         *  Assert raised when an invalid argument has been passed to a function
   246         */
   247        config Assert.Id A_invalidArg = {
   248            msg: "A_invalidArg: Invalid argument"
   249        };
   250
   251        /*!
   252         *  Assert raised when there is a conflict with the zero latency IER mask
   253         *
   254         *  This assert is raised when trying to create a Hwi with an intNum that
   255         *  conflicts with the supplied zero latency IER mask.
   256         */
   257        config Assert.Id A_zeroLatencyConflict = {
   258            msg: "A_zeroLatencyConflict: Conflict with zero latency IER mask"
   259        };
   260
   261        /*!
   262         *  Error raised when an unplugged interrupt is flagged
   263         */
   264        config Error.Id E_unpluggedInterrupt = {
   265            msg: "E_unpluggedInterrupt: Unplugged interrupt flagged: intr# %d"
   266        };
   267
   268        /*!
   269         *  Error raised when Hwi is already defined
   270         */
   271        config Error.Id E_alreadyDefined = {
   272            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   273        };
   274
   275
   276        // -------- Module Configuration --------
   277
   278        /*!
   279         *  ======== NonDispatchedInterrupt ========
   280         *  Non-dispatched interrupt object
   281         *
   282         *  Provided so that XGCONF users can easily plug non-dispatched interrupts
   283         *
   284         *  @field(intNum)      Interrupt number
   285         *  @field(fxn)         Non-dispatched interrupt service routine (ISR)
   286         *  @field(enableInt)   Enable the interrupt after plugging the vector
   287         */
   288        metaonly struct NonDispatchedInterrupt {
   289            Int             intNum;
   290            PlugFuncPtr     fxn;
   291            Bool            enableInt;
   292        };
   293
   294        /*!
   295         *  ======== nonDispatchedInterrupts ========
   296         *  Non-dispatched interrupt array.
   297         *
   298         *  Provided so that XGCONF users can easily plug non-dispatched interrupts
   299         */
   300        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   301
   302        /*!
   303         *  ======== zeroLatencyIERMask ========
   304         *  Zero Latency IER Mask
   305         *
   306         *  CPU interrupts specified in this mask (which corresponds to the 16-bit
   307         *  IER register) will never be disabled.  This means that the
   308         *  {@link #disable}, {@link #enable}, and {@link #restore} calls leave the
   309         *  zero latency CPU interrupts enabled after being called.  Zero latency
   310         *  operation may be used to ensure minimal interrupt-to-ISR time for
   311         *  non-BIOS interrupt handlers in applications that demand low latency.
   312         *
   313         *  It is important to note that zero latency and non-zero latency PIE
   314         *  interrupts may not share a common PIE group. The entire PIE group whose
   315         *  bit is set in the zeroLatencyIERMask will be treated as zero latency.
   316         *
   317         *  Enabling zero latency mode (specifying a non-zero zeroLatencyIERMask)
   318         *  generates alternate (and slower) code used to disable, enable and
   319         *  restore interrupts.  This alternate code will maintain a shadow copy
   320         *  of interrupt state (IER register and global interrupt state). {@link
   321         *  #disableIER}, {@link #enableIER} and {@link #restoreIER} will update
   322         *  both the IER register and its shadow.  The {@link #disable} call
   323         *  will copy the zero latency IER mask (supplied here) into the IER
   324         *  register.  The {@link #enable} call will copy the contents of the
   325         *  shadow IER register into the actual register. The {@link #restore}
   326         *  call may either disable or enable the non-zero-latency interrupts.
   327         *
   328         *  It is important to be aware of the performance penalty associated with
   329         *  using zero latency interrupts before using this feature.
   330         *
   331         *  Example:
   332         *
   333         *  @p(code)
   334         *  var Hwi = xdc.useModule('ti.sysbios.family.c28.Hwi');
   335         *  Hwi.zeroLatencyIERMask = 0x0010;
   336         *
   337         *  // PIE group 5 classified as zero latency
   338         *  @p
   339         *
   340         */
   341        config Bits16 zeroLatencyIERMask = 0x0;
   342
   343        /*!
   344         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   345         */
   346        config Log.Event LM_begin = {
   347            mask: Diags.USER1 | Diags.USER2,
   348            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   349        };
   350
   351        /*!
   352         *  Issued just after return from Hwi function (with interrupts disabled)
   353         */
   354        config Log.Event LD_end = {
   355            mask: Diags.USER2,
   356            msg: "LD_end: hwi: 0x%x"
   357        };
   358
   359        // -------- Module Functions --------
   360
   361        /*!
   362         *  ======== disable ========
   363         */
   364        @Macro
   365        override UInt disable();
   366
   367        /*!
   368         *  ======== enable ========
   369         */
   370        @Macro
   371        override UInt enable();
   372
   373        /*!
   374         *  ======== restore ========
   375         */
   376        @Macro
   377        override Void restore(UInt key);
   378
   379        /*!
   380         *  ======== inUseMeta ========
   381         *  @_nodoc
   382         *  Check for Hwi already in use.
   383         *  For internal SYS/BIOS use only.
   384         *  Should be called prior to any internal Hwi.create().
   385         *
   386         *  @param(intNum)  interrupt number
   387         */
   388        metaonly Bool inUseMeta(UInt intNum);
   389
   390        /*!
   391         *  ======== plug ========
   392         *  Plug an interrupt vector with an ISR address.
   393         *
   394         *  plug hooks up the specified function as the branch target for a
   395         *  hardware interrupt (fielded by the CPU) at the vector address
   396         *  corresponding to intNum. plug does not enable the interrupt. Use
   397         *  Hwi_enableIER to enable specific interrupts.
   398         *
   399         *  This API can plug the full set of vectors supported by the PIE (0-127).
   400         *
   401         *  @param(intNum)  interrupt number
   402         *  @param(fxn)     pointer to ISR function
   403         */
   404        @DirectCall
   405        Void plug(UInt intNum, PlugFuncPtr fxn);
   406
   407        /*!
   408         *  ======== plugMeta ========
   409         *  Statically plug an interrupt vector with an ISR address.
   410         *
   411         *  @param(intNum)  Interrupt number
   412         *  @param(fxn)     Pointer to ISR function
   413         */
   414        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   415
   416        /*!
   417         *  ======== getHandle ========
   418         *  Returns Hwi handle associated with intNum
   419         *
   420         *  @param(intNum)  Interrupt number
   421         *
   422         *  @b(returns)     Hwi handle associated with intNum
   423         */
   424        @DirectCall
   425        Handle getHandle(UInt intNum);
   426
   427        /*!
   428         *  ======== disableInterrupt ========
   429         *  @Hwi The behavior of Hwi_disableInterrupt depends on whether the intNum
   430         *  is a PIE interrupt number.  If so, the appropriate bit in its group's
   431         *  PIEIER register is cleared.  Note that, unlike
   432         *  {@link #enableInterrupt}, disableInterrupt does not touch IER bits
   433         *  when operating upon a PIE interrupt number. If intNum is a non-PIE
   434         *  interrupt (1 <= intNum <= 14), then the corresponding bit in the IER
   435         *  register is cleared.
   436         *
   437         *  @Hwi The return value is a key whose value reflects the previous state of
   438         *  the PIEIER bit.
   439         */
   440        @DirectCall
   441        override UInt disableInterrupt(UInt intNum);
   442
   443        /*!
   444         *  ======== enableInterrupt ========
   445         *  @Hwi The behavior of enableInterrupt depends on whether the intNum
   446         *  is a PIE interrupt number.  If so, two operations are
   447         *  performed. The IER bit for intNum's PIE group is set and the
   448         *  appropriate bit in its group's PIEIER register is also set.  However,
   449         *  if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the
   450         *  corresponding bit in the IER register is set.
   451         *
   452         *  @Hwi The return value is a key whose value reflects the previous state of
   453         *  the PIEIER bit. Note that the key does not reflect
   454         *  the IER register's previous state even if its state is modified by this
   455         *  call.
   456         */
   457        @DirectCall
   458        override UInt enableInterrupt(UInt intNum);
   459
   460        /*!
   461         *  ======== restoreInterrupt ========
   462         *  @Hwi The behavior of restoreInterrupt depends on whether the intNum
   463         *  is a PIE interrupt number.  If so, the supplied key returned by an
   464         *  earlier call to {@link #disableInterrupt} and {@link #enableInterrupt}
   465         *  is used to restore the corresponding PIEIER bit to its state before
   466         *  the earlier call.
   467         *  However, if intNum is a non-PIE interrupt (1 <= intNum <= 14), then the
   468         *  corresponding bit in the IER register is restored using the key.
   469         */
   470        @DirectCall
   471        override Void restoreInterrupt(UInt intNum, UInt key);
   472
   473        /*!
   474         *  ======== clearInterrupt ========
   475         *  @Hwi The behavior of clearInterrupt depends on whether the intNum
   476         *  is a PIE interrupt number.  If so, the corresponding PIEIFR bit is
   477         *  cleared.  If not (1 <= intNum <= 14), the corresponding IFR bit is
   478         *  cleared.
   479         */
   480        @DirectCall
   481        override Void clearInterrupt(UInt intNum);
   482
   483        /*!
   484         *  ======== disableIER ========
   485         *  Disable certain maskable interrupts.
   486         *
   487         *  Atomically disables specific interrupts by clearing the bits
   488         *  specified by mask in the Interrupt Enable Register (IER).
   489         *
   490         *  The IER bits to be cleared should be set to 1 in the mask.
   491         *
   492         *  @param(mask)    bitmask of interrupts to disable
   493         *
   494         *  @b(returns)     previous IER settings bitmask
   495         */
   496        @DirectCall
   497        Bits16 disableIER(Bits16 mask);
   498
   499        /*!
   500         *  ======== enableIER ========
   501         *  Enable certain maskable interrupts.
   502         *
   503         *  Atomically enables specific interrupts by setting the bits
   504         *  specified by mask in the Interrupt Enable Register (IER).
   505         *
   506         *  The IER bits to be set should be set to 1 in the mask.
   507         *
   508         *  @param(mask)    Bitmask of interrupts to enable
   509         *
   510         *  @b(returns)     Previous IER settings bitmask
   511         */
   512        @DirectCall
   513        Bits16 enableIER(Bits16 mask);
   514
   515        /*!
   516         *  ======== restoreIER ========
   517         *  Restore maskable interrupts
   518         *
   519         *  Restores maskable interrupts to the state they were in
   520         *  when either disableIER() or enableIER() was called.
   521         *
   522         *  Atomically writes the given mask to the IER register. Typically used
   523         *  to restore the IER register to the state returned from a call to
   524         *  either {@link #disableIER()} or {@link #enableIER()}.
   525         *
   526         *  @param(mask)    Bitmask of interrupts to restore
   527         *
   528         *  @b(returns)     Previous IER settings bitmask
   529         */
   530        @DirectCall
   531        Bits16 restoreIER(Bits16 mask);
   532
   533        /*!
   534         *  ======== enablePIEIER ========
   535         *  Enable interrupts in a PIE group
   536         *
   537         *  Atomically enable PIE interrupts in a single PIE group
   538         *  according to supplied PIEIER bitmask
   539         *
   540         *  @param(groupNum)    PIE group number
   541         *  @param(pieMask)     PIEIER enable mask for group
   542         *
   543         *  @b(returns)         Previous PIEIER settings bitmask
   544         */
   545        @DirectCall
   546        Bits16 enablePIEIER(UInt groupNum, Bits16 pieMask);
   547
   548        /*!
   549         *  ======== disablePIEIER ========
   550         *  Disable interrupts in a PIE group
   551         *
   552         *  Atomically disable PIE interrupts in a single PIE group
   553         *  according to supplied PIEIER bitmask
   554         *
   555         *  @param(groupNum)    PIE group number
   556         *  @param(pieMask)     PIEIER disable mask for group
   557         *
   558         *  @b(returns)         Previous PIEIER settings bitmask
   559         */
   560        @DirectCall
   561        Bits16 disablePIEIER(UInt groupNum, Bits16 pieMask);
   562
   563        /*!
   564         *  ======== restorePIEIER ========
   565         *  Restores interrupts in a PIE group
   566         *
   567         *  Atomically restore PIE interrupts in a single PIE group
   568         *  according to supplied PIEIER bitmask
   569         *
   570         *  @param(groupNum)    PIE group number
   571         *  @param(pieMask)     PIEIER restore mask for group
   572         *
   573         *  @b(returns)         Previous PIEIER settings bitmask
   574         */
   575        @DirectCall
   576        Bits16 restorePIEIER(UInt groupNum, Bits16 pieMask);
   577
   578        /*!
   579         *  ======== getInterruptFlag ========
   580         *  @_nodoc
   581         *  Returns IFR/PIEIFR flag corresponding to a single interrupt number
   582         *
   583         *  If intNum >= 32, the PIEIFR bit corresponding to intNum is returned.
   584         *  If 1 <= intNum <= 14, the IFR bit corresponding to intNum is returned.
   585         *
   586         *  @param(intNum)      Interrupt number
   587         *
   588         *  @b(returns)         Nonzero if interrupt is flagged, zero otherwise
   589         */
   590        @DirectCall
   591        Bits16 getInterruptFlag(UInt intNum);
   592
   593        /*!
   594         *  ======== getIERMask ========
   595         *  @_nodoc
   596         *  Calculates IER mask based on an array of C28x interrupt vector IDs
   597         *
   598         *  For each vector id the supplied array, a bit in the generated IER mask
   599         *  is set.  If 1 <= intNum <= 14, the corresponding IER bit is set. If
   600         *  intNum >= 32, the IER mask bit corresponding to the PIE interrupt's
   601         *  group is set.
   602         *
   603         *  getIERMask may be used to generate a zero latency IER mask given
   604         *  an array of vector IDs.
   605         *
   606         *  @param(vecIds)      Array of vector IDs
   607         *
   608         *  @b(returns)         Calculated IER Mask
   609         */
   610        metaonly UInt getIERMask(UInt vecIds[]);
   611
   612    instance:
   613
   614        /*!
   615         *  Dispatcher auto-nesting interrupt disable mask.
   616         *
   617         *  When the dispatcher's auto interrupt nesting support feature
   618         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   619         *  this mask defines which IER bits are disabled prior to invoking
   620         *  the user's ISR function with GIE = 1.
   621         *
   622         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   623         *  prior to invoking the ISR.
   624         *
   625         *  The value of this mask is normally auto-calculated based on the
   626         *  value of the maskSetting. However, manual setting of this
   627         *  mask is enabled by setting the maskSetting to
   628         *  {@link #MaskingOption MaskingOption_BITMASK}.
   629         *
   630         *  The default value is derived from the
   631         *  {@link #MaskingOption MaskingOption_SELF}
   632         *  maskSetting.
   633         */
   634        config Bits16 disableMask = 0;
   635
   636        /*!
   637         *  Dispatcher auto-nesting interrupt restore mask.
   638         *
   639         *  When the dispatcher's auto interrupt nesting support feature
   640         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   641         *  this mask defines which IER bits are restored to their previous
   642         *  setting upon return from the user's ISR function.
   643         *
   644         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   645         *
   646         *  The value of this mask is normally auto-calculated based on the
   647         *  value of the maskSetting. However, manual setting of this
   648         *  mask is enabled by setting the maskSetting to
   649         *  {@link #MaskingOption MaskingOption_BITMASK}.
   650         *
   651         *  The default value is derived from the
   652         *  {@link #MaskingOption MaskingOption_SELF}
   653         *  maskSetting.
   654         */
   655        config Bits16 restoreMask = 0;
   656
   657        /*!
   658         *  Interrupt priority. Not supported on this target.
   659         */
   660        override config Int priority = 0;
   661
   662        /*!
   663         *  ======== reconfig ========
   664         *  Reconfigure a dispatched interrupt.
   665         */
   666        @DirectCall
   667        Void reconfig(FuncPtr fxn, const Params *params);
   668
   669        /*!
   670         *  Enable automatic acknowledgement of PIE interrupts by the Hwi interrupt
   671         *  dispatcher.
   672         */
   673        config Bool enableAck = true;
   674
   675    internal:   /* not for client use */
   676        /*
   677         * Swi and Task module function pointers.
   678         * Used to decouple Hwi from Swi and Task when
   679         * dispatcherSwiSupport or
   680         * dispatcherTaskSupport is false.
   681         */
   682        config UInt (*swiDisable)();
   683        config Void (*swiRestoreHwi)(UInt);
   684        config UInt (*taskDisable)();
   685        config Void (*taskRestoreHwi)(UInt);
   686
   687        /*
   688         *  The IFR cregister is write-only, so a special assembly function is
   689         *  needed to read the value of the IFR on the 28x.
   690         */
   691        Bits16 getIFR();
   692
   693        /* 'ack' interrupt in case of PIE */
   694        Void ack(Handle hwi);
   695
   696        /* Used to temporarily plug PIE vector table when clearing PIEIFR */
   697        Void interruptReturn();
   698
   699        /* Used in assert that no conflict exists between zero/non-zero latency */
   700        Bits16 getIERBit(UInt intNum);
   701
   702        /* Interrupt Dispatcher */
   703        Void dispatchC(Int intNum);
   704
   705        /* unplugged interrupt handler */
   706        Void unPluggedInterrupt();
   707
   708        /* const array to hold all HookSet objects. */
   709        config HookSet hooks[length] = [];
   710
   711        /* Meta World Only Hwi Configuration Object. */
   712        metaonly struct InterruptObj {
   713            String name;                /* symbol used for vector table entry   */
   714            Bool used;                  /* Interrupt already defined?           */
   715            Bool useDispatcher;         /* Should dispatcher handle this Int?   */
   716            FuncPtr fxn;                /* Dispatched ISR function              */
   717            PlugFuncPtr pfxn;           /* "Hwi_plug'd" ISR function.           */
   718        };
   719
   720        /* Used for statically fixing certain PIEIER addresses */
   721        const Ptr PIEIER1_ADDR = 0x000CE2;
   722
   723        /* Example string: '0x02a0' */
   724        metaonly config String zeroLatencyIERMaskStr;
   725        metaonly config String nonZeroLatencyIERMaskStr;
   726
   727        /*
   728         * Meta-only array of interrupt objects.
   729         * This meta-only array of Hwi config objects is initialized
   730         * in Hwi.xs:module$meta$init().
   731         */
   732        metaonly config InterruptObj interrupt[NUM_INTERRUPTS_ALL];
   733
   734        struct Instance_State {
   735            UInt        intNum;         /* interrupt number                     */
   736            Bool        enableInt;      /* enable interrupt during startup?     */
   737            Bool        enableAck;      /* should dispatcher ack the int?       */
   738            Bits16      disableMask;    /* Interrupts to mask during ISR.       */
   739            Bits16      restoreMask;    /* Interrupts to restore after ISR.     */
   740            Bits16      ierBitMask;     /* bit number in IER for the instance   */
   741            UArg        arg;            /* Argument to Hwi function.            */
   742            FuncPtr     fxn;            /* Hwi function.                        */
   743            Irp         irp;            /* for IRP tracking                     */
   744            Ptr         hookEnv[];
   745        };
   746
   747        struct Module_State {
   748            Bits16      ierMask;        /* Initial IER mask                     */
   749            Char        *isrStack;      /* Points to isrStack address           */
   750            Char        *taskSP;        /* temporary storage of Task's SP       */
   751            Handle      dispatchTable[];/* dispatch table                       */
   752            Irp         irp;            /* current IRP                          */
   753            Bool        globalEnable;   /* for zero latency only                */
   754            Bits16      shadowIER;      /* for zero latency only                */
   755        };
   756    }
   757    /*
   758     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:48; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   759
   760     */
   761


package ti.sysbios.family.c28

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *
    36     *  The link below provides SYS/BIOS C28x register usage information:
    37     *
    38     *      {@link ./doc-files/c28regconv.html SYS/BIOS C28x Register Usage}
    39     *
    40     *! Open Issues:
    41     *  @p(blist)
    42     *      - System_printf() issue. Args need to be cast as UInt16
    43     *      - PLL not set ot 150MHz. Who whould do this? Gel OK?
    44     *      - Disable watchdog. Gel OK?
    45     *      - Hwi needs to be revisited wrt PIE
    46     *      - Task stack should be in lower memory. How to ensure?
    47     *      - Testcases need x28 specific config to build
    48     *      - UArg data type is different in SYS/BIOS 6 compared to DSP/BIOS 5.20.
    49     *      Old was Void *, New is intptr_t. Old was treated by codegen
    50     *      as a pointer and passed in XAR regs. New is treated as 32 bit
    51     *      data and passed in ACC. Effects Task_glue().
    52     *  @p
    53     */
    54
    55    requires ti.sysbios.interfaces;
    56    //requires ti.sysbios.knl;
    57
    58    /*!
    59     *  ======== ti.sysbios.family.c28 ========
    60     *  Contains specifications for the C28 specific SYS/BIOS functions.
    61     *
    62     */
    63    package ti.sysbios.family.c28 [2,0,0,0]{
    64        module TimestampProvider;
    65        module Clobber;
    66        module Hwi;
    67        module Timer;
    68        module IntrinsicsSupport;
    69        module TaskSupport;
    70        module Settings;
    71    }
    72    /*
    73     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:50; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    74
    75     */
    76


module ti.sysbios.family.c28.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.c28;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  C28xx target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c28.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c28;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  28 Task Support Module
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*!
    46         *  Error raised when stack is not located on PAGE 0
    47         */
    48        config xdc.runtime.Error.Id E_invalidStack  =
    49            {msg: "Stack (%d) not located on PAGE 0 (stack must be located entirely below 0x10000)"};
    50
    51        /*! Default Task stack size (in MAUs) */
    52        override readonly config SizeT defaultStackSize = 256;
    53
    54        /*! Required stack alignment (in MAUs). */
    55        override readonly config UInt stackAlignment = 0;
    56    }
    57    /*
    58     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    59
    60     */
    61


module ti.sysbios.family.c28.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c28;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Assert;
    44    import xdc.runtime.Types;
    45    import ti.sysbios.interfaces.ITimer;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer peripherals manager for the c28 family.
    50     *
    51     *  @p(html)
    52     *  <h3> 28x Timers </h3>
    53     *  @p(blist)
    54     *  - The 28x has three 32-bit timers.
    55     *  - The 28x timer counts downward from 'period' to 0; however, Timer_getCount
    56     *    will count upward.
    57     *  - The 28x timer supports an optional 16-bit prescalar. The prescalar
    58     *    effectively sets the period of the timer tick; the prescalar counts down
    59     *    from the prescale factor to 0, then a timer tick occurs. So, with a
    60     *    prescale set, the actual timer period is (prescale * period).
    61     *  @p
    62     *
    63     *  @p(html)
    64     *  <h3> Calling Context </h3>
    65     *  <table border="1" cellpadding="3">
    66     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    67     *
    68     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    69     *    <!--                                                                                                                 -->
    70     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #getCount}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #getPrescale}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #getPrescaleCount}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #setPrescale}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    87     *    <tr><td colspan="6"> Definitions: <br />
    88     *       <ul>
    89     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    90     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    91     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    92     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    93     *           <ul>
    94     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    95     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    96     *             <li> During main().</li>
    97     *             <li> During BIOS.startupFxns.</li>
    98     *           </ul>
    99     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   100     *           <ul>
   101     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   102     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
   103     *           </ul>
   104     *       </ul>
   105     *    </td></tr>
   106     *  </table>
   107     *  @p
   108     */
   109
   110    @InstanceFinalize       /* Clear the timer and delete its Hwi */
   111    @InstanceInitError      /* To report unavailability of a timer */
   112    @ModuleStartup          /* To configure static timers */
   113
   114    module Timer inherits ti.sysbios.interfaces.ITimer
   115    {
   116        /*! Max value of Timer period for PeriodType_COUNTS*/
   117        const UInt MAX_PERIOD = 0xffffffff;
   118
   119        /*! Number of timer peripherals on chip */
   120        const Int NUM_TIMER_DEVICES = 3;
   121
   122        /*! Timer Emulation Mode. */
   123        struct EmulationMode {
   124            UInt free;      /*! At sw breakpoint, stop or free-run the timer. */
   125            UInt soft;      /*! At sw breakpoint, hard stop or run down timer. */
   126        };
   127
   128        /*! @_nodoc */
   129        metaonly struct BasicView {
   130            Ptr         halTimerHandle;
   131            String      label;
   132            UInt        id;
   133            String      startMode;
   134            String      runMode;
   135            UInt        period;
   136            String      periodType;
   137            UInt        prescalar;
   138            UInt        intNum;
   139            UArg        arg;
   140            String      tickFxn[];
   141            String      hwiHandle;
   142        };
   143
   144        /*! @_nodoc */
   145        metaonly struct DeviceView {
   146            UInt        id;
   147            String      deviceAddr;
   148            UInt        intNum;
   149            UInt        period;
   150            UInt        currCount;
   151            UInt        remainingCount;
   152        };
   153
   154        /*! @_nodoc */
   155        @Facet
   156        metaonly config ViewInfo.Instance rovViewInfo =
   157            ViewInfo.create({
   158                viewMap: [
   159                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   160                    ['Device', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDevice', structName: 'DeviceView'}],
   161                ]
   162            });
   163
   164        /*!
   165         *  Assert raised in Timer_create when timer id specified is not supported.
   166         */
   167        config Assert.Id A_invalidTimer = {
   168            msg: "A_invalidTimer: Timer id must be 0-2"
   169        };
   170
   171        /*!
   172         *  Error raised in Timer_create when timer requested is in use.
   173         */
   174        config Error.Id E_notAvailable = {
   175            msg: "E_notAvailable: Timer not available %d"
   176        };
   177
   178        /*!
   179         *  Assert raised in Timer_create if an invalid RunMode is requested.
   180         */
   181        config Assert.Id A_invalidRunMode = {
   182            msg: "A_invalidRunMode: Invalid RunMode"
   183        };
   184
   185        /*!
   186         *  Assert raised in Timer_create when Hwi Params does not mask 'self'.
   187         *
   188         *  This is not allowed because the timers on this platform do not
   189         *  inherently support one-shot mode. Instead, a stub is used to stop the
   190         *  timer, so it is important that the timer interrupt not occur again
   191         *  before the stub has stopped the timer.
   192         */
   193        config Assert.Id A_invalidHwiMask = {
   194            msg: "A_InvalidMask: Mask in hwiParams cannot enable self"
   195        };
   196
   197        /*!
   198         *  Assert raised when period requested is not supported.
   199         */
   200        config Assert.Id E_cannotSupport = {
   201            msg: "E_cannotSupport: Timer cannot support requested period"
   202        };
   203
   204        /*!
   205         *  ======== anyMask ========
   206         *  Available mask to be used when select = Timer_ANY
   207         */
   208        config UInt anyMask = 0x7;
   209
   210    instance:
   211
   212        /*!
   213         *  ======== emulationModeInit ========
   214         *  Initial timer emulation mode. Default hard stop.
   215         *
   216         *  Determines timer state at a software breakpoint. If 'free' is 1, the
   217         *  timer will continue to run, and the value of 'soft' doesn't matter.
   218         *  When 'free' is 0 and 'soft' is 1, the timer runs down to 0 then stops.
   219         *  When 'free' is 0 and 'soft' is 0, the timer halts.
   220         *
   221         *  @p(html)
   222         *  <pre>
   223         *  FREE   SOFT
   224         *  0      0      Stop after next timer decrement. (Hard stop)
   225         *  0      1      Stop after timer runs down to 0. (Soft stop)
   226         *  1      x      Continue running the timer.
   227         *  </pre>
   228         */
   229        config EmulationMode emulationModeInit = {free: 0, soft: 0};
   230
   231        /*!
   232         *  ======== prescale ========
   233         *  Prescale factor.
   234         *
   235         *  The prescale factor determines the length of a timer tick.
   236         *  If a prescale of 10 is specified, a timer tick will occur
   237         *  every 11 cycles.
   238         *
   239         *  If the timer is used as a counter, the prescale factor determines
   240         *  the period between counts. Otherwise, the prescale factor can be used
   241         *  to achieve longer timer periods: with a prescale specified, the actual
   242         *  period is (period * prescale+1).
   243         */
   244        config UInt16 prescale = 0;
   245
   246        /*!
   247         *  ======== hwiParams ========
   248         *  Parameters for the Hwi object created for the Timer ISR.
   249         *
   250         *  The mask setting for the Hwi object should include SELF to prevent
   251         *  nested timer interrupts.
   252         */
   253        config Hwi.Params *hwiParams = null;
   254
   255        /*!
   256         *  ======== getCount ========
   257         *  Returns the number of counts that have passed.
   258         *
   259         *  The 28x timer counts downward from the period to 0, but getCount
   260         *  subtracts the timer counter value from the period so that getCount
   261         *  counts upward instead of downward.
   262         *
   263         *  @b(returns) timer counts, counting upward from 0
   264         */
   265        @DirectCall
   266        override UInt32 getCount();
   267
   268        /*!
   269         *  ======== setPreScale ========
   270         *  Set timer prescale value.
   271         *
   272         *  This function sets the value of the prescalar, and will also reload
   273         *  the timer counter and prescale registers.
   274         *
   275         *  The prescalar decrements with each timer clock source cycle until it
   276         *  reaches zero, then the timer's count is decremented by one. The
   277         *  prescalar has the effect of setting the rate of the timer tick.
   278         *
   279         *  @param(preScalar) The value to set the prescale period to.
   280         */
   281        Void setPrescale(UInt16 preScalar);
   282
   283        /*!
   284         *  ======== getPrescale ========
   285         *  Get timer prescale value.
   286         *
   287         *  This is not the prescale count, but the period of the prescalar.
   288         *
   289         *  @b(returns) prescale value
   290         */
   291        UInt16 getPrescale();
   292
   293        /*!
   294         *  ======== getPrescaleCount ========
   295         *  Reads timer prescale counter.
   296         *
   297         *  The prescale counter counts down from prescale to 0, but
   298         *  getPrescaleCount subtracts the counter value from the period so that
   299         *  this function counts upward instead of downward.
   300         *
   301         *  @b(returns) prescale counter, counting upward from 0
   302         */
   303        UInt16 getPrescaleCount();
   304
   305        /*!
   306         *  ======== getExpiredCounts64 ========
   307         *  @_nodoc
   308         *  Called by TimestampProvider to read the timer counter, accounting
   309         *  for counter rollover.
   310         *
   311         *  This version of the API returns a 64-bit count and is only used when
   312         *  the TimestampProvider is using a dedicated timer.
   313         *
   314         *  This function must be called with interrupts disabled.
   315         *
   316         *  @b(returns) Timer counts, accounting for counter rollover.
   317         */
   318        @DirectCall
   319        Void getExpiredCounts64(Types.Timestamp64 *result);
   320
   321    internal:   /* not for client use */
   322
   323        /*!
   324         *  ======== oneShotStub ========
   325         *  This stub implements oneShot mode by stopping the timer and clearing
   326         *  the CPU IFR bit. It does not clear the PIEIFR bit, so timer 0 does
   327         *  not support one shot mode.
   328         *
   329         *  @param(arg) The timer object
   330         */
   331        Void oneShotStub(UArg arg);
   332
   333        /*!
   334         *  ======== startupNeeded ========
   335         *  Flag used to prevent Module_startup and Timer_startup code from being
   336         *  brought in unnecessarily. Flag is set if there are any static Timer
   337         *  instances.
   338         */
   339        config UInt startupNeeded = false;
   340
   341        struct Instance_State {
   342            Int                id;             /* timer id. */
   343            EmulationMode      emulationModeInit; /* initial emu mode */
   344            ITimer.RunMode     runMode;        /* timer mode */
   345            ITimer.StartMode   startMode;      /* timer mode */
   346            UInt32             period;         /* period */
   347            ITimer.PeriodType  periodType;
   348            UInt16             prescale;       /* prescale */
   349            UInt               intNum;         /* intr num */
   350            UArg               arg;            /* tickFxn arg*/
   351            Hwi.FuncPtr        tickFxn;        /* tickFxn */
   352            Types.FreqHz       extFreq;
   353            Hwi.Handle         hwi;
   354        }
   355
   356        struct Module_State {
   357            Char   availMask;                       /* Available peripherals */
   358            Handle staticTimers[NUM_TIMER_DEVICES]; /* Array of statically created
   359                                                     * timer handles based on id */
   360        }
   361    }
   362    /*
   363     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:50; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   364
   365     */
   366


module ti.sysbios.family.c28.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c28;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *  </table>
    73     *  @p
    74     *
    75     */
    76
    77    @ModuleStartup          /* To get Clock Timer Handle */
    78
    79    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    80    {
    81        /*!
    82         * TimestampProvider timer id: 0, 1, or 2
    83         *
    84         * This parameter is ignored if useClockTimer is true.
    85         */
    86        config UInt timerId = Timer.ANY;
    87
    88        /*!
    89         *  Whether the TimestampProvider should share the Clock's timer.
    90         *
    91         *  This parameter overrides the timeId setting.
    92         *
    93         *  Sharing the Clock timer leaves more timers available for other uses,
    94         *  but makes the Timestamp APIs less efficient. If the Clock timer is
    95         *  used, the timestamp is calculated as:
    96         *    (Clock ticks) x (tick period) + (current timer count)
    97         *  This also limits the maximum value of the timestamp:
    98         *    max timestamp = 2^32 x (Clock tick period)
    99         *
   100         *  Using a dedicated timer allows for a full 64-bit timestamp and does not
   101         *  require any multiplication to retrieve the value.
   102         */
   103        config Bool useClockTimer = false;
   104
   105        /*!@_nodoc
   106         *  Internal use. If Timestamp is using a dedicated timer, this function is
   107         *  added to Startup.lastFxns to start the timer before reaching main.
   108         *
   109         *  There are no C symbol references to this function, so it must be kept
   110         *  above the internal section so that it does not fall away when building
   111         *  a ROM image. If the function falls out of the ROM, when the ROM
   112         *  application finally references the symbol, it will not exist, and the
   113         *  library will be brought in a second time resulting in multiple symbol
   114         *  definitions.
   115         */
   116        Void startTimer();
   117
   118        /*!@_nodoc
   119         *  Internal use. If Timestamp is using a dedicated timer, this function is
   120         *  the timer interrupt handler which maintains a count which is the upper
   121         *  32-bits of the timestamp.
   122         *
   123         *  This function must be kept 'public' for ROM concerns. See startTimer
   124         *  for explanation.
   125         */
   126        Void rolloverFunc(UArg unused);
   127
   128    internal:   /* not for client use */
   129
   130        struct Module_State {
   131            Timer.Handle     timer;    /* timer instance used */
   132            volatile UInt32  hi;       /* upper 32 bits */
   133        }
   134    }
   135    /*
   136     *  @(#) ti.sysbios.family.c28; 2, 0, 0, 0,461; 6-15-2011 16:24:50; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   137
   138     */
   139


package ti.sysbios.family.c28.f28m35x

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     *
    36     *  The link below provides SYS/BIOS C28x register usage information:
    37     *
    38     *      {@link ./doc-files/c28regconv.html SYS/BIOS C28x Register Usage}
    39     *
    40     *! Open Issues:
    41     *  @p(blist)
    42     *      - System_printf() issue. Args need to be cast as UInt16
    43     *      - PLL not set ot 150MHz. Who whould do this? Gel OK?
    44     *      - Disable watchdog. Gel OK?
    45     *      - Hwi needs to be revisited wrt PIE
    46     *      - Task stack should be in lower memory. How to ensure?
    47     *      - Testcases need x28 specific config to build
    48     *      - UArg data type is different in SYS/BIOS 6 compared to DSP/BIOS 5.20.
    49     *      Old was Void *, New is intptr_t. Old was treated by codegen
    50     *      as a pointer and passed in XAR regs. New is treated as 32 bit
    51     *      data and passed in ACC. Effects Task_glue().
    52     *  @p
    53     */
    54
    55    /*!
    56     *  ======== ti.sysbios.family.c28 ========
    57     *  Contains specifications for the C28 specific SYS/BIOS functions.
    58     *
    59     */
    60    package ti.sysbios.family.c28.f28m35x [2,0,0,0]{
    61        module TimestampProvider;
    62    }
    63    /*
    64     *  @(#) ti.sysbios.family.c28.f28m35x; 2, 0, 0, 0,8; 6-15-2011 16:24:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    65
    66     */
    67


module ti.sysbios.family.c28.f28m35x.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c28.f28m35x;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     *
    76     */
    77
    78
    79    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    80    {
    81
    82    internal:
    83
    84        const UInt32 MIPCCOUNTERL = 0x4E0C;
    85        const UInt32 MIPCCOUNTERH = 0x4E0E;
    86
    87    }
    88
    89    /*
    90     *  @(#) ti.sysbios.family.c28.f28m35x; 2, 0, 0, 0,8; 6-15-2011 16:24:49; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    91
    92     */
    93


package ti.sysbios.family.c62

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c62 ========
    41     *  Contains specifications for C6x specific SYS/BIOS functions.
    42     *
    43     *  The link below provides SYS/BIOS C6x register usage information:
    44     *
    45     *      {@link ./doc-files/c6xregconv.html SYS/BIOS C6x Register Usage}
    46     *
    47     */
    48    package ti.sysbios.family.c62 [2,0,0,0] {
    49        module TaskSupport;
    50        module IntrinsicsSupport;
    51    }
    52    /*
    53     *  @(#) ti.sysbios.family.c62; 2, 0, 0, 0,500; 6-15-2011 16:24:52; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    54
    55     */
    56


module ti.sysbios.family.c62.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c62;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  C64 Task Support Module.
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*! default Task stack size. */
    46        override readonly config SizeT defaultStackSize = 2048;
    47
    48        /*! required stack alignment (in MAUs). */
    49        override readonly config UInt stackAlignment = 8;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.c62; 2, 0, 0, 0,500; 6-15-2011 16:24:51; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


C6000 DSP/BIOS Register Usage

This document provides tables describing the TMS320C6000TM register conventions in terms of preservation across multi-threaded context switching and preconditions.

Overview

In a multi-threaded application using DSP/BIOS, it is necessary to know which registers can or cannot be modified. Furthermore, users need to understand which registers need to be saved/restored across a function call or an interrupt.

The following definitions describe the various possible register handling behaviors:

  • Scratch register. These registers are saved/restored by the Hwi dispatcher with temporary register bit masks.
  • Preserved register. These registers are saved/restored during a Task context switch.
  • Initialized register. These registers are set to a particular value during Hwi processing and restored to their incoming value upon exiting from the interrupt routine.
  • Read-Only register. These registers may be read but must not be modified.
  • Global register. These registers are shared across all threads in the system. To make a temporary change, save the register, make the change, and then restore it.
  • Other. These registers do not fit into one of the categories above.

Register Conventions

Table 1 Register and Status Bit Handling

Register

Status Bit

Register or Status Bit Name

Type

Notes

A0-A9,
B0-B9

General purpose registers

Scratch

A10-A12,
A14-A15,
B10-B13

General purpose registers

Preserved

A13

Frame pointer

Preserved

B14

Data page pointer

Initialized

Hwi sets to bss before calling ISR

B15

Stack pointer

Initialized

Hwi sets to Hwi stack before calling ISR

A16-A31**,
B16-B31**

General purpose registers

Scratch

AMR

Addressing mode register

Initialized

Hwi sets to 0 before calling ISR

CSR

GIE

Global interrupt enable

Global

PGIE

Previous global interrupt enable

Global

DCC

Data cache control mode

Preserved

PCC

Program cache control mode

Preserved

EN

Endian bit

Read-Only

SAT

Saturation bit

Scratch

PWRD

Control power-down modes

Global

Revision ID

Revision ID

Read-Only

CPU ID

CPU ID

Read-Only

IFR

Interrupt flag register

Read-Only

ISR

Interrupt set register

Other

Cannot be read

ICR

Interrupt clear register

Other

Cannot be read

IER

Interrupt enable register

Read-Only

ISTP

Interrupt service table pointer

Read-Only

IRP

Interrupt return pointer

Global

Can be modified with interrupts disabled.

NRP

Non-maskable interrupt return pointer

Read-Only

PCE1

Program counter, E1 phase

Read-Only

FADCR*

Rmode

Rounding mode

Global

Currently DSP/BIOS does not deal with this register.

UNDER

Underflow status bit

INEX

Exponent status bit

OVER

Overflow status bit

INFO

Signed infinity status bit

INVAL

INVAL status bit

DEN2

Denormalized number

DEN1

Denormalized number

NAN2

NaN number

NAN1

NaN number

FAUCR*

DIV0

DIV0 status bit

Global

Currently DSP/BIOS does not deal with this register.

UNORD

UNORD status bit

UNDER

Underflow status bit

INEX

Exponent status bit

OVER

Overflow status bit

INFO

Signed infinity status bit

INVAL

INVAL status bit

DEN2

Denormalized number

DEN1

Denormalized number

NAN2

NaN number

NAN1

NaN number

FMCR*

Rmode

Rounding mode

Global

Currently DSP/BIOS does not deal with this register.

UNDER

Underflow status bit

INEX

Exponent status bit

OVER

Overflow status bit

INFO

Signed infinity status bit

INVAL

INVAL status bit

DEN2

Denormalized number

DEN1

Denormalized number

NAN2

NaN number

NAN1

NaN number

GFPGFR**

Galois Field Polynomial
Generator

Global

Currently DSP/BIOS does not deal with this register.

TSR+

GIE

Global interrupt enable

Global

SGIE

Saved global interrupt enable

Global

GEE

Global exception enable

Read-Only

XEN

Maskable exception enable

Read-Only

DBGM

Emulator debug mask

Read-Only

CXM

Current execution mode

Read-Only

INT

Interrupt processing

Read-Only / Other

DSP/BIOS does not maintain this C64x+ status bit. Since DSP/BIOS does not do a "return from interrupt" for certain task switches, your application should not expect this bit to correctly indicate whether an interrupt is currently being processed.

EXC

Exception processing

Read-Only

SPLX

SPLOOP executing

Read-Only

IB

Interrupt blocked

Read-Only

ITSR+

Interrupt task state register

Global

NTSR+

NMI/Exception task state register

Global

EFR+

Exception flag register

Read-Only

ECR+

Exception clear register

Read-Only

IERR+

Internal exception cause register

Read-Only

SSR+

Saturation status register

Global

ILC+

Inner loop SPL buffer count

Global

RILC+

Reload inner loop SPL buffer count

Global

GPLYA+

GMPY polynomial for A side

Scratch, Preserve

GPLYB+

GMPY polynomial for B side

Scratch, Preserve

TSCL+

Low half of 64-bit time stamp counter

Read-Only

TSCH+

High half of 64-bit time stamp counter

Read-Only

DNUM+

DSP number

Read-Only

DIER+

Debug interrupt enable register

Global

Notes:

* - Denotes registers available on the `C67x, `C67x+ to support floating point operations.

** - Denotes registers available on the `C64x, `C67x+ only.

+ - Denotes registers available on the `C64x+ only.

The General purpose registers follow the 'C' compiler conventions. IRP can be used as a scratch register only when interrupts are disabled. ITSR and NTSR are identical copies of TSR, see TSR for details on each individual status bit.

For the `C67x FADCR, FAUCR, and FMCR registers, the compiler assumes the nearest rounding mode is used. This is assumed to be the default mode at power-up. The compiler does not actually do anything to set it up that way, nor does it ever write or read these registers. These registers are completely under user control. Code may generate slightly different results if you change these registers.


module ti.sysbios.family.c64.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c64;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43    import xdc.runtime.Assert;
    44    import xdc.runtime.Error;
    45
    46    /*!
    47     *  ======== Hwi ========
    48     *  C64x Hardware Interrupt Support Module.
    49     *
    50     *  This Hwi module provides C64 family-specific implementations of the
    51     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    52     *
    53     *  Additional C64 device-specific APIs are also provided.
    54     *
    55     *  @a(NOTE)
    56     *  In this Hwi module implementation, the instance config parameter value
    57     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    58     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    59     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    60     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    61     *  silently converted to {@link #MaskingOption_SELF}.
    62     *
    63     *  @p(html)
    64     *  <h3> Calling Context </h3>
    65     *  <table border="1" cellpadding="3">
    66     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    67     *
    68     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    69     *    <!--                                                                                                                 -->
    70     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #disableIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #eventMap}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    82     *    <tr><td> {@link #restoreIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    84     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td colspan="6"> Definitions: <br />
    92     *       <ul>
    93     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    94     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    95     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    96     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    97     *           <ul>
    98     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    99     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   100     *             <li> During main().</li>
   101     *             <li> During BIOS.startupFxns.</li>
   102     *           </ul>
   103     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   104     *           <ul>
   105     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   106     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   107     *           </ul>
   108     *       </ul>
   109     *    </td></tr>
   110     *
   111     *  </table>
   112     *  @p
   113     *
   114     */
   115
   116    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   117    @ModuleStartup         /* generate a call to Hwi_init at startup */
   118
   119    module Hwi inherits ti.sysbios.interfaces.IHwi
   120    {
   121        // -------- Module Constants --------
   122
   123        /*! C64 supports 16 interrupts. */
   124        const Int NUM_INTERRUPTS = 16;
   125
   126        // -------- Module Types --------
   127
   128        /*! @_nodoc Hwi plug function type definition. */
   129        typedef Void (*PlugFuncPtr)(void);
   130
   131        /*!
   132         *  ======== BasicView ========
   133         *  @_nodoc
   134         */
   135        metaonly struct BasicView {
   136            String      label;
   137            UInt        intNum;
   138            String      fxn;
   139            UArg        arg;           // Argument to Hwi function.
   140            Ptr         irp;
   141            UInt        eventId;
   142            String      disableMask;   // Interrupts to mask during ISR.
   143            String      restoreMask;   // Interrupts to restore after ISR.
   144        };
   145
   146        /*!
   147         *  ======== ModuleView ========
   148         *  @_nodoc
   149         */
   150        metaonly struct ModuleView {
   151            String      options[4];
   152            SizeT       hwiStackPeak;
   153            SizeT       hwiStackSize;
   154            Ptr         hwiStackBase;
   155        };
   156
   157        /*!
   158         *  ======== rovViewInfo ========
   159         *  @_nodoc
   160         */
   161        @Facet
   162        metaonly config ViewInfo.Instance rovViewInfo =
   163            ViewInfo.create({
   164                viewMap: [
   165                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   166                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   167                ]
   168            });
   169
   170        // -------- Module Parameters --------
   171
   172        /*!
   173         *  non-dispatched interrupt object.
   174         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   175         */
   176        metaonly struct NonDispatchedInterrupt {
   177            Int             intNum;
   178            PlugFuncPtr     fxn;            /*! "Hwi_plug'd" ISR function. */
   179            Bool            enableInt;
   180            Int             eventId;
   181        };
   182
   183        /*!
   184         *  non-dispatched interrupt array.
   185         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   186         */
   187        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   188
   189        /*!
   190         *  Alternate reset vector address. Default is undefined.
   191         *
   192         *  if initialized by the user then an additional reset vector
   193         *  is created and placed in the ".resetVector" section.
   194         *  To place the .resetVector section into a specific memory section,
   195         *  add the following command to your config script:
   196         *  @p(code)
   197         *  Program.sectMap[".resetVector"] = YourMemorySection;
   198         *  @p
   199         */
   200        metaonly config Ptr resetVectorAddress;
   201
   202        /*!
   203         *  Error raised when Hwi is already defined
   204         */
   205        config Error.Id E_alreadyDefined = {
   206            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   207        };
   208
   209        /*!
   210         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   211         */
   212        config Log.Event LM_begin = {
   213            mask: Diags.USER1 | Diags.USER2,
   214            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   215        };
   216
   217        /*!
   218         *  Issued just after return from Hwi function (with interrupts disabled)
   219         */
   220        config Log.Event LD_end = {
   221            mask: Diags.USER2,
   222            msg: "LD_end: hwi: 0x%x"
   223        };
   224
   225        // -------- Module Functions --------
   226
   227        /*!
   228         *  ======== disable ========
   229         */
   230        @Macro
   231        override UInt disable();
   232
   233        /*!
   234         *  ======== enable ========
   235         */
   236        @Macro
   237        override UInt enable();
   238
   239        /*!
   240         *  ======== restore ========
   241         */
   242        @Macro
   243        override Void restore(UInt key);
   244
   245        /*!
   246         *  ======== inUseMeta ========
   247         *  @_nodoc
   248         *  Check for Hwi already in use.
   249         *  For internal SYS/BIOS use only.
   250         *  Should be called prior to any internal Hwi.create().
   251         *
   252         *  @param(intNum)  interrupt number
   253         */
   254        metaonly Bool inUseMeta(UInt intNum);
   255
   256        /*!
   257         *  ======== eventMap ========
   258         *  Map Event to Interrupt
   259         *
   260         *  Function maps a GEM event to an interrupt number so that the
   261         *  event is the interrupt source of the vector.
   262         *
   263         *  @param(intNum)  interrupt number
   264         *  @param(eventId) event ID
   265         */
   266        @DirectCall
   267        Void eventMap(Int intNum, Int eventId);
   268
   269        /*!
   270         *  ======== eventMapMeta ========
   271         *  Maps GEM Event to interrupt number statically
   272         *
   273         *  Function maps an event to an interrupt number so that the
   274         *  event is the interrupt source of the vector.
   275         *
   276         *  @param(intNum)      interrupt number
   277         *  @param(eventId)     event Id
   278         */
   279        metaonly Void eventMapMeta(Int intNum, Int eventId);
   280
   281        /*!
   282         *  @_nodoc
   283         *  ======== plug ========
   284         *  Plug an interrupt vector with an ISR address.
   285         *
   286         *  Hwi_plug writes an Interrupt Service Fetch Packet (ISFP) into the
   287         *  Interrupt Service Table (IST), at the address corresponding to intNum
   288         *  The op-codes written in the ISFP create a branch to the function
   289         *  entry  point specified by fxn:
   290         *
   291         *  @p(code)
   292         *          stw     b0, *SP--[1]
   293         *          mvk     fxn, b0
   294         *          mvkh    fxn, b0
   295         *          b       b0
   296         *          ldw     *++SP[1],b0
   297         *          nop     4
   298         *  @p
   299         *
   300         *  Hwi_plug hooks up the specified function as the branch target of a
   301         *  hardware interrupt (fielded by the CPU) at the vector address
   302         *  specified in intNum. Hwi_plug does not enable the interrupt.
   303         *  Use Hwi_enableIER to enable specific interrupts.
   304         *
   305         *  For internal SYS/BIOS use only.
   306         *
   307         *  Constraints and Calling Context
   308         *  o vecid must be a valid interrupt ID in the range of 0-15.
   309         *
   310         *  @param(intNum)  interrupt number
   311         *  @param(fxn)     pointer to ISR function
   312         */
   313        @DirectCall
   314        Void plug(UInt intNum, PlugFuncPtr fxn);
   315
   316        /*!
   317         *  ======== plugMeta ========
   318         *  Statically plug an interrupt vector with an ISR address.
   319         *
   320         *  @param(intNum)  interrupt number
   321         *  @param(fxn)     pointer to ISR function
   322         */
   323        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   324
   325        /*!
   326         *  ======== getHandle ========
   327         *  Returns Hwi_handle associated with interrupt number
   328         *
   329         *  @param(intNum)  interrupt number
   330         *  @b(returns)     handle associated with intNum
   331         */
   332        @DirectCall
   333        Handle getHandle(UInt intNum);
   334
   335        /*!
   336         *  ======== disableIER ========
   337         *  Disable certain maskable interrupts.
   338         *
   339         *  Atomically disables specific interrupts by clearing the bits
   340         *  specified by mask in the Interrupt Enable Register (IER).
   341         *
   342         *  The IER bits to be cleared should be set to 1 in the mask.
   343         *
   344         *  @param(mask)    bitmask of interrupts to disable
   345         *  @b(returns)     previous IER settings bitmask
   346         */
   347        @DirectCall
   348        Bits16 disableIER(Bits16 mask);
   349
   350        /*!
   351         *  ======== enableIER ========
   352         *  Enable certain maskable interrupts.
   353         *
   354         *  Atomically enables specific interrupts by setting the bits
   355         *  specified by mask in the Interrupt Enable Register (IER).
   356         *
   357         *  The IER bits to be set should be set to 1 in the mask.
   358         *
   359         *  @param(mask)    bitmask of interrupts to enable
   360         *  @b(returns)     previous IER settings bitmask
   361         */
   362        @DirectCall
   363        Bits16 enableIER(Bits16 mask);
   364
   365        /*!
   366         *  ======== restoreIER ========
   367         *  Restore maskable interrupts to the state they were in
   368         *  when either disableIER() or enableIER() was called.
   369         *
   370         *  Atomically writes the given mask to the IER register. Typically used
   371         *  to restore the IER register to the state returned from a call to
   372         *  either {@link #disableIER()} or {@link #enableIER()}.
   373         *
   374         *  @param(mask)    bitmask of interrupts to restore
   375         *  @b(returns)     previous IER settings bitmask
   376         */
   377        @DirectCall
   378        Bits16 restoreIER(Bits16 mask);
   379
   380    instance:
   381
   382        /*!
   383         *  Dispatcher auto-nesting interrupt disable mask.
   384         *
   385         *  When the dispatcher's auto interrupt nesting support feature
   386         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   387         *  this mask defines which IER bits are disabled prior to invoking
   388         *  the user's ISR function with GIE = 1.
   389         *
   390         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   391         *  prior to invoking the ISR.
   392         *
   393         *  The value of this mask is normally auto-calculated based on the
   394         *  value of the maskSetting. However, manual setting of this
   395         *  mask is enabled by setting the maskSetting to
   396         *  {@link #MaskingOption MaskingOption_BITMASK}.
   397         *
   398         *  The default value is derived from the
   399         *  {@link #MaskingOption MaskingOption_SELF}
   400         *  maskSetting.
   401         */
   402        config Bits16 disableMask = 0;
   403
   404        /*!
   405         *  Dispatcher auto-nesting interrupt restore mask.
   406         *
   407         *  When the dispatcher's auto interrupt nesting support feature
   408         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   409         *  this mask defines which IER bits are restored to their previous
   410         *  setting upon return from the user's ISR function.
   411         *
   412         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   413         *
   414         *  The value of this mask is normally auto-calculated based on the
   415         *  value of the maskSetting. However, manual setting of this
   416         *  mask is enabled by setting the maskSetting to
   417         *  {@link #MaskingOption MaskingOption_BITMASK}.
   418         *
   419         *  The default value is derived from the
   420         *  {@link #MaskingOption MaskingOption_SELF}
   421         *  maskSetting.
   422         */
   423        config Bits16 restoreMask = 0;
   424
   425        /*!
   426         *  Interrupt priority. Not supported on this target.
   427         */
   428        override config Int priority = 0;
   429
   430        /*!
   431         *  ======== reconfig ========
   432         *  Reconfigures a dispatched interrupt.
   433         *
   434         *  This function reconfigures the dispatched interrupt so the
   435         *  specified function is called with the specified parameters.
   436         *
   437         *  @param(fxn)     pointer to ISR function
   438         *  @param(params)  pointer to Hwi parameter structure
   439         */
   440        @DirectCall
   441        Void reconfig(FuncPtr fxn, const Params *params);
   442
   443    internal:   /* not for client use */
   444
   445        /*
   446         * Swi and Task module function pointers.
   447         * Used to decouple Hwi from Swi and Task when
   448         * dispatcherSwiSupport or
   449         * dispatcherTaskSupport is false.
   450         */
   451        config UInt (*swiDisable)();
   452        config Void (*swiRestoreHwi)(UInt);
   453        config UInt (*taskDisable)();
   454        config Void (*taskRestoreHwi)(UInt);
   455
   456        /*
   457         *  ======== getIsrStackAddress ========
   458         *  Returns initial isrStack address.
   459         *  This API was developed solely for the Exception module
   460         *  to allow removal of the Hwi_link.xdt template definition
   461         *  of ti_sysbios_family_c64p_Hwi_isrStack which was not
   462         *  ROM-able
   463         */
   464        Char *getIsrStackAddress();
   465
   466        /* Interrupt Dispatcher */
   467        Void dispatchC(Int intNum);
   468
   469        /* unPlugged interrupt handler */
   470        Void unPluggedInterrupt();
   471
   472        /*!
   473         *  const array to hold all HookSet objects.
   474         */
   475        config HookSet hooks[length] = [];
   476
   477        /*! Meta World Only Hwi Configuration Object. */
   478        metaonly struct InterruptObj {
   479            String name;            /* symbol used for vector table entry */
   480            Bool used;              /* Interrupt already defined? */
   481            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   482            FuncPtr fxn;            /* Dispatched ISR function */
   483            PlugFuncPtr pfxn;       /* "Hwi_plug'd" ISR function. */
   484        };
   485
   486        /*!
   487         * Meta-only array of interrupt objects.
   488         * This meta-only array of Hwi config objects is initialized
   489         * in Hwi.xs:module$meta$init().
   490         */
   491        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   492
   493        struct Instance_State {
   494            Bits16      disableMask;    // Interrupts to mask during ISR.
   495            Bits16      restoreMask;    // Interrupts to restore after ISR.
   496            UArg        arg;            // Argument to Hwi function.
   497            FuncPtr     fxn;            // Hwi function.
   498            Irp         irp;            // current IRP
   499            Ptr         hookEnv[];
   500        };
   501
   502        struct Module_State {
   503            Char        intEvents[12];  // Initial event mapping
   504            Bits16      ierMask;        // Initial IER mask
   505            Char        *taskSP;        // temporary storage of interrupted
   506                                        // Task's SP during ISR execution
   507            /* ROM */
   508            Char        *isrStack;      // Points to isrStack address
   509            Ptr         vectorTableBase;// ti_sysbios_family_c64_Hwi0
   510            Ptr         bss;            // bss address
   511
   512            Handle      dispatchTable[NUM_INTERRUPTS];
   513                                        // dispatch table
   514        };
   515    }
   516    /*
   517     *  @(#) ti.sysbios.family.c64; 2, 0, 0, 0,498; 6-15-2011 16:24:57; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   518
   519     */
   520


package ti.sysbios.family.c64

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    //requires ti.sysbios.knl;
    39
    40    /*!
    41     *  ======== ti.sysbios.family.c64 ========
    42     *  Contains specifications for the C64 specific SYS/BIOS functions.
    43     *
    44     *  The link below provides SYS/BIOS C6x register usage information:
    45     *
    46     *      {@link ./../c62/doc-files/c6xregconv.html SYS/BIOS C6x Register Usage}
    47     *
    48     */
    49    package ti.sysbios.family.c64 [2,0,0,0] {
    50        module Hwi;
    51        module Timer;
    52        module TimestampProvider;
    53        module Clobber;
    54        module Settings;
    55    }
    56    /*
    57     *  @(#) ti.sysbios.family.c64; 2, 0, 0, 0,498; 6-15-2011 16:24:58; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    58
    59     */
    60


module ti.sysbios.family.c64.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.c64;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  C64 target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.c64; 2, 0, 0, 0,498; 6-15-2011 16:24:57; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c64.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64;
    39
    40    import xdc.runtime.Types;
    41    import xdc.runtime.Error;
    42    import ti.sysbios.interfaces.ITimer;
    43
    44    /*!
    45     *  ======== Timer ========
    46     *  Timer Peripherals Manager for c64 family.
    47     *
    48     *  @p(html)
    49     *  <h3> Calling Context </h3>
    50     *  <table border="1" cellpadding="3">
    51     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    52     *
    53     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    54     *    <!--                                                                                                                 -->
    55     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    56     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    61     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td> {@link #getCount}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    68     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    70     *    <tr><td colspan="6"> Definitions: <br />
    71     *       <ul>
    72     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    73     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    74     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    75     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    76     *           <ul>
    77     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    78     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    79     *             <li> During main().</li>
    80     *             <li> During BIOS.startupFxns.</li>
    81     *           </ul>
    82     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    83     *           <ul>
    84     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    85     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    86     *           </ul>
    87     *       </ul>
    88     *    </td></tr>
    89     *
    90     *  </table>
    91     *  @p
    92     *
    93     */
    94    @InstanceFinalize       /* To cleanup */
    95    @InstanceInitError      /* To report unavailability of timer */
    96    @ModuleStartup          /* to configure static timers */
    97
    98    module Timer inherits ti.sysbios.interfaces.ITimer
    99    {
   100        /*! Max value of Timer period for PeriodType_COUNTS*/
   101        const UInt MAX_PERIOD = 0xffffffff;
   102
   103        /*! Number of timer peripherals on chip */
   104        const Int NUM_TIMER_DEVICES = 3;
   105
   106        /*! @_nodoc
   107         *  Min instructions to use in trigger().
   108         */
   109        const Int MIN_SWEEP_PERIOD = 16;
   110
   111        /*! Timer Configuration struct.
   112         *
   113         *  @field(func)    When true TOUT is timer output. When false TOUT pin
   114         *                  is a general-purpose output pin.
   115         *  @field(invout)  When true inverted TSTAT drives TOUT. When false non
   116         *                  inverted TSTAT drives TOUT.
   117         *  @field(dataout) When true TSTAT is driven on TOUT after inversion by
   118         *                  INVOUT. When false DATOUT is driven on TOUT.
   119         *  @field(pwid)    When true TSTAT goes inactive two clock cycles after
   120         *                  timer counter equald timer period value. When false
   121         *                  TSTAT goes inactive one clock cycle after the timer
   122         *                  counter value equals the timer period value.
   123         *  @field(cp)      When true TSTAT has a 50% duty cycle. When false TSTAT
   124         *                  is active for one CPU cycle after timer reaches the
   125         *                  timer period. PWID determines the width.
   126         *  @field(spnd)    When true timer stops counting during emulation halt.
   127         *                  When false timer continues to count during emulation
   128         *                  halt.
   129         */
   130        struct Control {
   131            UInt func;      /*! 0=TOUT is GPIO; 1=TOUT is timer output */
   132            UInt invout;    /*! 0=TOUT is TSTAT TOUT; 1=TOUT is ~TSTAT */
   133            UInt datout;    /*! 0=DATOUT drives TOUT; 1=TSTAT drives TOUT */
   134            UInt pwid;      /*! 0=width is ONE; 1=width is TWO */
   135            UInt cp;        /*! 0=pulse mode; 1=clock mode*/
   136            UInt spnd;      /*! 0=timer continues; 1=timer stops; */
   137        };
   138
   139        /*! @_nodoc */
   140        @XmlDtd
   141        metaonly struct Instance_View {
   142            String              label;
   143            UInt                id;
   144            Control             configuration;
   145            ITimer.RunMode      runMode;
   146            ITimer.StartMode    startMode;
   147            UInt                period;
   148            UInt                intNum;
   149            UArg                arg;
   150            String              isrFxn[];
   151            Types.FreqHz        extFreq;
   152            UInt32              accuTicks;
   153            String              hwiHandle;
   154        };
   155
   156        /*! @_nodoc */
   157        @XmlDtd
   158        metaonly struct Device_View {
   159            UInt    id;
   160            Bool    inUse;
   161        };
   162
   163        /*! @_nodoc */
   164        @XmlDtd
   165        metaonly struct Module_View {
   166            Device_View     timers[NUM_TIMER_DEVICES];
   167        }
   168
   169        /*!
   170         *  Error raised when timer id specified is not supported.
   171         */
   172        config Error.Id E_invalidTimer = {
   173            msg: "E_invalidTimer: Invalid Timer Id %d"
   174        };
   175
   176        /*!
   177         *  Error raised when timer requested is in use
   178         */
   179        config Error.Id E_notAvailable = {
   180            msg: "E_notAvailable: Timer not available %d"
   181        };
   182
   183        /*!
   184         *  Error raised when Hwi Params has mask where self is turned on.
   185         *
   186         *  This is not allowed because the timers on this platform do not
   187         *  support one-shot mode and a stub is used to stop it.
   188         *  Another timer interrupt cannot go off when the ISR is running.
   189         */
   190        config Error.Id E_invalidHwiMask = {
   191            msg: "E_InvalidMask: Mask in hwiParams cannot enable self"
   192        };
   193
   194        /*!
   195         *  Error raised when period requested is not supported
   196         */
   197        config Error.Id E_cannotSupport = {
   198            msg: "E_cannotSupport: Timer cannot support requested period %d"
   199        };
   200
   201        /*!
   202         *  ======== anyMask ========
   203         *  Available mask to be used when select = Timer_ANY
   204         */
   205        config UInt anyMask = 0x7;
   206
   207        /*!
   208         *  ======== oneShotStub ========
   209         *  @_nodoc
   210         *  C64 timer does not support one shot mode. This stub stops timer
   211         *  and clears IFR.
   212         *
   213         *  @param(arg)     Unused.
   214         */
   215        Void oneShotStub(UArg arg);
   216
   217        /*!
   218         *  ======== getHandle ========
   219         *  @_nodoc
   220         *  Used by TimestampProvider module to get hold of timer handle used by
   221         *  Clock.
   222         *
   223         *  @param(id)      timer Id.
   224         */
   225        Handle getHandle(UInt id);
   226
   227    instance:
   228
   229        /*! Control register configuration. Default spnd=1. */
   230        config Control controlRegInit = {func: 0, invout: 0, datout:0,
   231            pwid:0, cp:0, spnd:1};
   232
   233        /*! Hwi Params for Hwi Object. Default is null. */
   234        config Hwi.Params *hwiParams = null;
   235
   236        /*! Hwi intNum to be used by Timer. */
   237        config Int intNum = -1;
   238
   239        /*!
   240         *  ======== reconfig ========
   241         *  Used to modify static timer instances at runtime.
   242         *
   243         *  @param(timerParams)     timer Params
   244         *  @param(tickFxn)         functions that runs when timer expires.
   245         */
   246        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   247
   248
   249    internal:   /* not for client use */
   250
   251        /*!
   252         *  ======== noStartupNeeded ========
   253         *  Flag used to prevent misc code from being brought in
   254         *  un-necessarily
   255         */
   256        config UInt startupNeeded = false;
   257
   258        struct Instance_State {
   259            Bool                    staticInst;
   260            Int                     id;
   261            UInt                    controlRegInit;
   262            ITimer.RunMode          runMode;
   263            ITimer.StartMode        startMode;
   264            UInt                    period;
   265            ITimer.PeriodType       periodType;
   266            UInt                    intNum;
   267            UArg                    arg;
   268            Hwi.FuncPtr             tickFxn;
   269            Types.FreqHz            extFreq;
   270            Hwi.Handle              hwi;
   271        }
   272
   273        struct Module_State {
   274            Ptr             baseAddress[NUM_TIMER_DEVICES];
   275            UInt            availMask;      /* available peripherals */
   276            Handle          handles[NUM_TIMER_DEVICES];
   277                                            /* array of handles based on id */
   278        }
   279    }
   280    /*
   281     *  @(#) ti.sysbios.family.c64; 2, 0, 0, 0,498; 6-15-2011 16:24:58; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   282
   283     */
   284


module ti.sysbios.family.c64.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     *
    76     */
    77
    78    @ModuleStartup          /* To get Clock Timer Handle */
    79
    80    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    81    {
    82        /*! @_nodoc */
    83        @XmlDtd
    84        metaonly struct Module_View {
    85            Timer.Instance_View timer;
    86            Bool    usesClockTimer;
    87        };
    88
    89        /*! TimestampProvider timer id. Max id value is 2 */
    90        config UInt timerId = Timer.ANY;
    91
    92        /*!
    93         *  Set this parameter when you want TimestampProvider is use the same timer
    94         *  as the Clock module.
    95         *
    96         *  This parameter overrides the timeId setting.
    97         */
    98        config Bool useClockTimer = false;
    99
   100        /*!@_nodoc
   101         *  Internal use. Function that starts timer before main
   102         */
   103        Void startTimer();
   104
   105        /*!@_nodoc
   106         *  Internal use. Timer rollover interrupt handler.
   107         */
   108        Void rolloverFunc(UArg unused);
   109
   110    internal:   /* not for client use */
   111
   112        struct Module_State {
   113            Timer.Handle    timer;          /* timer instance used */
   114            volatile UInt32 hi;             /* upper 32 bits */
   115        }
   116    }
   117    /*
   118     *  @(#) ti.sysbios.family.c64; 2, 0, 0, 0,498; 6-15-2011 16:24:58; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   119
   120     */
   121


module ti.sysbios.family.c64p.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    /*!
    43     *  ======== Cache ========
    44     *  Cache Module
    45     *
    46     *  This Cache module provides C64+ family-specific implementations of the
    47     *  APIs defined in {@link ti.sysbios.interfaces.ICache ICache}.  It also
    48     *  provides additional C64+ specific cache functions.
    49     *
    50     *  Unconstrained Functions
    51     *  All functions
    52     *
    53     *  @p(html)
    54     *  <h3> Calling Context </h3>
    55     *  <table border="1" cellpadding="3">
    56     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    57     *
    58     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    59     *    <!--                                                                                                                 -->
    60     *    <tr><td> {@link #disable}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    61     *    <tr><td> {@link #enable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    62     *    <tr><td> {@link #getMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    63     *    <tr><td> {@link #getMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    64     *    <tr><td> {@link #getSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #inv}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #invL1pAll*} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #setMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #setMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #setSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #wait}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #wb}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #wbAll*}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #wbInv}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #wbInvAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td colspan="6"> Definitions: <br />
    76     *       <ul>
    77     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    78     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    79     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    80     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    81     *           <ul>
    82     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    83     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    84     *             <li> During main().</li>
    85     *             <li> During BIOS.startupFxns.</li>
    86     *           </ul>
    87     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    88     *           <ul>
    89     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    90     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    91     *           </ul>
    92     *       <li> <b>*</b>: These APIs are intended to be made at initialization time, but are not restricted to this. </li>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99
   100    @ModuleStartup
   101
   102    module Cache inherits ti.sysbios.interfaces.ICache
   103    {
   104        // -------- Module Types --------
   105
   106        /*!
   107         *  ======== ModuleView ========
   108         *  @_nodoc
   109         */
   110        metaonly struct ModuleView {
   111            String  L1PCacheSize;
   112            String  L1PMode;
   113            String  L1DCacheSize;
   114            String  L1DMode;
   115            String  L2CacheSize;
   116            String  L2Mode;
   117        };
   118
   119        /*!
   120         *  ======== MarRegisterView ========
   121         *  @_nodoc
   122         */
   123        metaonly struct MarRegisterView {
   124            UInt    number;
   125            Ptr     addr;
   126            Ptr     startAddrRange;
   127            Ptr     endAddrRange;
   128        };
   129
   130        /*!
   131         *  ======== rovViewInfo ========
   132         *  @_nodoc
   133         */
   134        @Facet
   135        metaonly config ViewInfo.Instance rovViewInfo =
   136            ViewInfo.create({
   137                viewMap: [
   138                    ['Module',
   139                        {
   140                            type: ViewInfo.MODULE,
   141                            viewInitFxn: 'viewInitModule',
   142                            structName: 'ModuleView'
   143                        }
   144                    ],
   145                    ['EnableMARs',
   146                        {
   147                            type: xdc.rov.ViewInfo.MODULE_DATA,
   148                            viewInitFxn: 'viewInitMarRegisters',
   149                            structName: 'MarRegisterView'
   150                        }
   151                    ]
   152                ]
   153            });
   154
   155        /*! Lists of cache modes for L1/L2 caches */
   156        enum Mode {
   157            Mode_FREEZE,    /*! No new cache lines are allocated */
   158            Mode_BYPASS,    /*! All access result in long-distance access */
   159            Mode_NORMAL     /*! Normal operation of cache */
   160        };
   161
   162        /*! Level 1 cache size type definition. Can be used for both L1D & L1P */
   163        enum L1Size {
   164            L1Size_0K = 0,  /*! Amount of cache is 0K, Amount of SRAM is 32K */
   165            L1Size_4K = 1,  /*! Amount of cache is 4K, Amount of SRAM is 28K */
   166            L1Size_8K = 2,  /*! Amount of cache is 8K, Amount of SRAM is 24K */
   167            L1Size_16K = 3, /*! Amount of cache is 16K, Amount of SRAM is 16K */
   168            L1Size_32K = 4  /*! Amount of cache is 32K, Amount of SRAM is 0K */
   169        };
   170
   171        /*! Level 2 cache size type definition. */
   172        enum L2Size {
   173            L2Size_0K = 0,   /*! L2 is all SRAM */
   174            L2Size_32K = 1,  /*! Amount of cache is 32K */
   175            L2Size_64K = 2,  /*! Amount of cache is 64K */
   176            L2Size_128K = 3, /*! Amount of cache is 128K */
   177            L2Size_256K = 4, /*! Amount of cache is 256K */
   178            L2Size_512K = 5, /*! Amount of cache is 512K */
   179            L2Size_1024K = 6 /*! Amount of cache is 1024K */
   180        };
   181
   182        /*! MAR register setting type definition. */
   183        enum Mar {
   184            Mar_DISABLE = 0, /*! The Permit Copy bit of MAR register is disabled */
   185            Mar_ENABLE = 1   /*! The Permit Copy bit of MAR register is enabled */
   186        };
   187
   188        /*! Structure for specifying all cache sizes. */
   189        struct Size {
   190            L1Size l1pSize;         /*! L1 Program cache size */
   191            L1Size l1dSize;         /*! L1 Data data size */
   192            L2Size l2Size;          /*! L2 cache size */
   193        };
   194
   195        /*!
   196         * Cache sizes.
   197         *
   198         * When this parameter is set in user's cfg script, user set cache sizes
   199         * override those specified by the Cache module or the platform.
   200         */
   201        config Size initSize = {
   202            l1pSize: L1Size_32K,
   203            l1dSize: L1Size_32K,
   204            l2Size: L2Size_0K
   205        };
   206
   207        /*!
   208         *  EMIF A configuration address.
   209         *
   210         *  By default, this is set to the physical address. On devices with
   211         *  a MMU where the physical address is mapped to a virtual address,
   212         *  the virtual address must be specified here.
   213         */
   214        config UInt *EMIFA_CFG;
   215
   216        /*!
   217         *  EMIF A base register address.
   218         *
   219         *  By default, this is set to the emif A base register physical address.
   220         *  On devices with a MMU where the physical address is mapped to a virtual
   221         *  address, the virtual address must be specified here.
   222         */
   223        config UInt EMIFA_BASE;
   224
   225        /*!
   226         *  EMIF A address space length.
   227         */
   228        config UInt EMIFA_LENGTH;
   229
   230        /*!
   231         *  EMIF B configuration address.
   232         *
   233         *  By default, this is set to the physical address. On devices with
   234         *  a MMU where the physical address is mapped to a virtual address,
   235         *  the virtual address must be specified here.
   236         */
   237        config UInt *EMIFB_CFG;
   238
   239        /*!
   240         *  EMIF B base register address.
   241         *
   242         *  By default, this is set to the emif B base register physical address.
   243         *  On devices with a MMU where the physical address is mapped to a virtual
   244         *  address, the virtual address must be specified here.
   245         */
   246        config UInt EMIFB_BASE;
   247
   248        /*!
   249         *  EMIF B address space length.
   250         */
   251        config UInt EMIFB_LENGTH;
   252
   253        /*!
   254         *  EMIF C configuration address.
   255         *
   256         *  By default, this is set to the physical address. On devices with
   257         *  a MMU where the physical address is mapped to a virtual address,
   258         *  the virtual address must be specified here.
   259         */
   260        config UInt *EMIFC_CFG;
   261
   262        /*!
   263         *  EMIF C base register address.
   264         *
   265         *  By default, this is set to the emif C base register physical address.
   266         *  On devices with a MMU where the physical address is mapped to a virtual
   267         *  address, the virtual address must be specified here.
   268         */
   269        config UInt EMIFC_BASE;
   270
   271        /*!
   272         *  EMIF C address space length.
   273         */
   274        config UInt EMIFC_LENGTH;
   275
   276        /*!
   277         *  MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF)
   278         *
   279         *  If undefined by the user, this parameter is configured to match the
   280         *  memory map of the platform.
   281         *  Each memory region defined in the platform will have all of its
   282         *  corresponding MAR bits set.
   283         *
   284         *  To override the default behavior you must initialize this parameter
   285         *  in your configuration script:
   286         *
   287         *  @p(code)
   288         *  // disable MAR bits for addresses 0x00000000 to 0x1FFFFFFF
   289         *  Cache.MAR0_31 = 0x00000000;
   290         *  @p
   291         */
   292        config UInt32 MAR0_31;
   293
   294        /*!
   295         *  MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF)
   296         *
   297         *  see {@link #MAR0_31} for more info
   298         */
   299        config UInt32 MAR32_63;
   300
   301        /*!
   302         *  MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF)
   303         *
   304         *  see {@link #MAR0_31} for more info
   305         */
   306        config UInt32 MAR64_95;
   307
   308        /*!
   309         *  MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF)
   310         *
   311         *  see {@link #MAR0_31} for more info
   312         */
   313        config UInt32 MAR96_127;
   314
   315        /*!
   316         *  MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF)
   317         *
   318         *  see {@link #MAR0_31} for more info
   319         */
   320        config UInt32 MAR128_159;
   321
   322        /*!
   323         *  MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF)
   324         *
   325         *  see {@link #MAR0_31} for more info
   326         */
   327        config UInt32 MAR160_191;
   328
   329        /*!
   330         *  MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF)
   331         *
   332         *  see {@link #MAR0_31} for more info
   333         */
   334        config UInt32 MAR192_223;
   335
   336        /*!
   337         *  MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF)
   338         *
   339         *  see {@link #MAR0_31} for more info
   340         */
   341        config UInt32 MAR224_255;
   342
   343        /*!
   344         *  ======== disable ========
   345         *  Disables the 'type' cache(s)
   346         *
   347         *  Disabling of L2 cache is currently not supported.
   348         */
   349        @DirectCall
   350        override Void disable(Bits16 type);
   351
   352        /*!
   353         *  ======== setMode ========
   354         *  Set mode of a cache
   355         *
   356         *  @param(type)    bit mask of cache type
   357         *  @param(mode)    mode of cache
   358         *
   359         *  @b(returns)     previous mode of cache
   360         */
   361        @DirectCall
   362        Mode setMode(Bits16 type, Mode mode);
   363
   364        /*!
   365         *  ======== getMode ========
   366         *  Get mode of a cache
   367         *
   368         *  @param(type)     bit mask of cache type
   369         *  @b(returns)      mode of specified level of cache
   370         */
   371        @DirectCall
   372        Mode getMode(Bits16 type);
   373
   374        /*!
   375         *  ======== setSize ========
   376         *  Set sizes of all caches
   377         *
   378         *  @param(size)    pointer to structure of type Cache_Size
   379         */
   380        @DirectCall
   381        Void setSize(Size *size);
   382
   383        /*!
   384         *  ======== getSize ========
   385         *  Get sizes of all caches
   386         *
   387         *  @param(size)    pointer to structure of type Cache_Size
   388         */
   389        @DirectCall
   390        Void getSize(Size *size);
   391
   392        /*!
   393         *  ======== getMar ========
   394         *  Get the value of the MAR register defined for the specified
   395         *  base address
   396         *
   397         *  @param(baseAddr)        address for which MAR is requested
   398         *
   399         *  @b(returns)     value of MAR register associated with  specified address
   400         */
   401        @DirectCall
   402        Mar getMar(Ptr baseAddr);
   403
   404        /*!
   405         *  ======== setMar ========
   406         *  Set the MAR register(s) that corresponds to the specified
   407         *  address range.
   408         *
   409         *  @param(baseAddr)        start address for which to set MAR
   410         *  @param(byteSize)        size (in bytes) of memory block
   411         *  @param(value)           enum of type Cache_Mar
   412         */
   413        @DirectCall
   414        Void setMar(Ptr baseAddr, SizeT byteSize, Mar value);
   415
   416        /*!
   417         *  ======== invL1pAll ========
   418         *  Invalidate all of L1 Program cache
   419         *
   420         *  Performs a global invalidate of L1P cache.
   421         *  Polls the L1P invalidate register until done.
   422         */
   423        @DirectCall
   424        Void invL1pAll();
   425
   426        /*!
   427         *  ======== wbAll ========
   428         *  Write back all caches
   429         *
   430         *  Perform a global write back.  There is no effect on L1P cache.
   431         *  All cache lines are left valid in L1D cache and the data in L1D cache
   432         *  is written back to L2 or external.  All cache lines are left valid in
   433         *  L2 cache and the data in L2 cache is written back to external.
   434         */
   435        @DirectCall
   436        override Void wbAll();
   437
   438        /*!
   439         *  ======== wbInvAll ========
   440         *  Write back invalidate all caches
   441         *
   442         *  Performs a global write back and invalidate.  All cache lines are
   443         *  invalidated in L1P cache.  All cache lines are written back to L2 or
   444         *  external and then invalidated in L1D cache.  All cache lines are
   445         *  written back to external and then invalidated in L2 cache.
   446         */
   447        @DirectCall
   448        override Void wbInvAll();
   449
   450    internal:
   451
   452        /* cache configuration registers */
   453        const UInt32 L2CFG  = 0x01840000;
   454        const UInt32 L1PCFG = 0x01840020;
   455        const UInt32 L1PCC  = 0x01840024;
   456        const UInt32 L1DCFG = 0x01840040;
   457        const UInt32 L1DCC  = 0x01840044;
   458        const UInt32 MAR    = 0x01848000;
   459
   460        struct Module_State {
   461            volatile UInt32 *emifAddr;      /*! Emif configuration address */
   462        }
   463    }
   464    /*
   465     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   466
   467     */
   468


module ti.sysbios.family.c64p.EventCombiner

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== EventCombiner.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p;
    39
    40    import xdc.runtime.Error;
    41
    42    /*!
    43     *  ======== EventCombiner ========
    44     *  Event Combiner Manager module
    45     *
    46     *  The event combiner allows the user to combine up to 32 system events
    47     *  into a single combined event.  The events 0, 1, 2, and 3 are the events
    48     *  associated with the event combiner.  Using the EventCombiner module
    49     *  along with the Hwi module, allows the user to route a combined event
    50     *  to any of the 12 maskable CPU interrupts available on GEM.  The
    51     *  EventCombiner supports up to 128 system events.  Users can specify
    52     *  a function and an argument for each system event and can choose to
    53     *  enable whichever system events they want.
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    59     *
    60     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    61     *    <!--                                                                                                                 -->
    62     *    <tr><td> {@link #disableEvent}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    63     *    <tr><td> {@link #dispatch}        </td><td>   Y    </td><td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #dispatchPlug}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #enableEvent}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td colspan="6"> Definitions: <br />
    67     *       <ul>
    68     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    69     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    70     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    71     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    72     *           <ul>
    73     *             <li> In your module startup after this module is started (e.g. EventCombiner_Module_startupDone() returns TRUE). </li>
    74     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    75     *             <li> During main().</li>
    76     *             <li> During BIOS.startupFxns.</li>
    77     *           </ul>
    78     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    79     *           <ul>
    80     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    81     *             <li> In your module startup before this module is started (e.g. EventCombiner_Module_startupDone() returns FALSE).</li>
    82     *           </ul>
    83     *       </ul>
    84     *    </td></tr>
    85     *
    86     *  </table>
    87     *  @p
    88     */
    89
    90    @ModuleStartup
    91
    92    module EventCombiner
    93    {
    94        /*!
    95         *  ======== EventView ========
    96         *  @_nodoc
    97        */
    98        metaonly struct EventView {
    99            UInt         eventId;
   100            String       fxn;
   101            String       arg;
   102        };
   103
   104        /*!
   105         *  ======== rovViewInfo ========
   106         *  @_nodoc
   107         */
   108        @Facet
   109        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   110            xdc.rov.ViewInfo.create({
   111                viewMap: [
   112                    ['Events',
   113                        {
   114                            type: xdc.rov.ViewInfo.MODULE_DATA,
   115                            viewInitFxn: 'viewInitEvents',
   116                            structName: 'EventView'
   117                        }
   118                    ]
   119                ]
   120            });
   121
   122        // -------- Module Constants --------
   123
   124        /*! C64+ supports 128 events. */
   125        const Int NUM_EVENTS = 128;
   126
   127        // -------- Module Types --------
   128
   129        /*! Event Combiner dispatcher function type definition. */
   130        typedef Void (*FuncPtr)(UArg);
   131
   132        /*!
   133         *  Event Configuration Object.
   134         *
   135         *  unmask - Boolean value that specifies if an event should be
   136         *      unmasked in the C64+ EVTMASK registers.
   137         *  fxn - function to call when this event occurs.
   138         *  arg - arg to fxn.
   139         */
   140        metaonly struct EventObj {
   141            Bool unmask;
   142            FuncPtr fxn;
   143            UArg arg;
   144        };
   145
   146        /*!
   147         *  Error raised when an unplug Event is executed.
   148         */
   149        config Error.Id E_unpluggedEvent = {
   150            msg: "E_unpluggedEvent: Event# %d is unplugged"
   151        };
   152
   153        // -------- Module Parameters --------
   154
   155        /*!
   156         *  ======== EVTMASK ========
   157         *  Holds the initialization values for the C64+ EVTMASK registers (0-3).
   158         *
   159         *  It is assigned values based on the 'unmask' member of the 'events'
   160         *  configuration array.  It can also be assigned manually in the program
   161         *  configuration script.
   162         */
   163        config Bits32 EVTMASK[4];
   164
   165        /*!
   166         *  ======== events ========
   167         *  For holding configuration values for all C64+ events.
   168         *
   169         *  Array elements can be configured in the program
   170         *  configuration script.
   171         */
   172        metaonly config EventObj events[NUM_EVENTS];
   173
   174        /*!
   175         *  ======== eventGroupHwiNum ========
   176         *  Configures the mapping of a C64+ combined event group to an interrupt.
   177         *
   178         *  There is one element per combined event group (0-3).
   179         */
   180        metaonly config Int eventGroupHwiNum[4];
   181
   182        /*!
   183         *  ======== dispatchEventGroup ========
   184         *  Configuration method for assigning the eventGroupHwiNum array.
   185         *
   186         *  It accomplishes the same thing as directly setting
   187         *  eventGroupHwiNum[0-3].
   188         *
   189         */
   190        metaonly Void dispatchEventGroup(UInt evt, UInt hwiVec);
   191
   192        /*!
   193         *  ======== disableEvent ========
   194         *  Disables 'evt' from contributing to its combined event group.
   195         *
   196         *  It accomplishes this by setting the corresponding
   197         *  bit in the C64+ EVTMASK array to 1 (to mask it).
   198         */
   199        Void disableEvent(UInt evt);
   200
   201        /*!
   202         *  ======== enableEvent ========
   203         *  Enables 'evt' to contribute to its combined event group.
   204         *
   205         *  It accomplishes this by setting the corresponding
   206         *  bit in the C64+ EVTMASK array to 0 (to unmask it).
   207         */
   208        Void enableEvent(UInt evt);
   209
   210        /*!
   211         *  ======== dispatch ========
   212         *  The Event Combiner dispatcher.
   213         *
   214         *  It is mostly used internally, but can be used directly by the user.
   215         */
   216        Void dispatch(UInt evt);
   217
   218        /*!
   219         *  ======== dispatchPlug ========
   220         *  Used to configure a dispatcher entry for 'evt'.
   221         *
   222         *  The parameters correspond to the same ones for static configuration
   223         *  in EventObj.  dispatchPlug does not map the corresponding combined
   224         *  event group to an Hwi interrupt - such an action needs to be
   225         *  performed either using the event combiner configuration or using the Hwi
   226         *  module.
   227         */
   228        Void dispatchPlug(UInt evt, FuncPtr fxn, UArg arg, Bool unmask);
   229
   230        /*!
   231         *  @_nodoc
   232         *  ======== unused ========
   233         *  unused exists simply to map a call in the Ecm dispatcher calling
   234         *  context to the System_exit calling context (casts UArg to Int).
   235         */
   236        Void unused(UArg arg);
   237
   238    internal:
   239
   240        struct DispatchTabElem {
   241            FuncPtr fxn;
   242            UArg arg;
   243        };
   244
   245        struct Module_State {
   246            DispatchTabElem dispatchTab[NUM_EVENTS];
   247        };
   248
   249    }
   250
   251    /*
   252     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   253
   254     */
   255


module ti.sysbios.family.c64p.Exception

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Exception.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c64p;
    38
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43
    44    /*!
    45     *  ======== Exception ========
    46     *  Exception Module
    47     *
    48     *  The Exception module is a basic C64+ exception handler.  It is generally
    49     *  considered to be a program endpoint, since an exception usually
    50     *  indicates something fatal to the system.
    51     *
    52     *  During initialization, the Exception module sets TSR.GEE and TSR.XEN to
    53     *  enable the CPU to recognize the EXECP input.
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    59     *
    60     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    61     *    <!--                                                                                                                 -->
    62     *    <tr><td> {@link #clearLastStatus}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    63     *    <tr><td> {@link #evtEvtClear}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    64     *    <tr><td> {@link #evtExpMaskEnable}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #getLastStatus}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #setReturnPtr}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td colspan="6"> Definitions: <br />
    68     *       <ul>
    69     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    70     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    71     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    72     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    73     *           <ul>
    74     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    75     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    76     *             <li> During main().</li>
    77     *             <li> During BIOS.startupFxns.</li>
    78     *           </ul>
    79     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    80     *           <ul>
    81     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    82     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    83     *           </ul>
    84     *       </ul>
    85     *    </td></tr>
    86     *
    87     *  </table>
    88     *  @p
    89     */
    90
    91    @ModuleStartup         /* generate a call to Exception at startup */
    92
    93    module Exception
    94    {
    95        /*!
    96         *  ======== rovViewInfo ========
    97         *  @_nodoc
    98         */
    99        @Facet
   100        metaonly config ViewInfo.Instance rovViewInfo =
   101            ViewInfo.create({
   102                viewMap: [
   103                     ['Exception',
   104                        {
   105                            type: ViewInfo.TREE,
   106                            viewInitFxn: 'viewInitException',
   107                            structName: 'Context'
   108                        }
   109                    ]
   110                ]
   111            });
   112
   113        // -------- Module Types --------
   114
   115        /*! FuncPtr - Hook function type definition. */
   116        typedef Void (*FuncPtr)(void);
   117
   118        /*! @_nodoc
   119         *  Context - Register contents at the time of the exception.
   120         *  dispatch() creates a Context structure on the Hwi ISR stack and
   121         *  fills it before calling handler.  A pointer to this
   122         *  Context structure is returned by getLastStatus().
   123         */
   124        struct Context {
   125            Ptr ILC;        //! register ILC
   126            Ptr RILC;       //! register RILC
   127            Ptr AMR;        //! register AMR
   128            Ptr SSR;        //! register SSR
   129            Ptr IRP;        //! register IRP
   130            Ptr NRP;        //! register NRP
   131            Ptr ITSR;       //! register ITSR
   132            Ptr NTSR;       //! register NTSR
   133            Ptr EFR;        //! register EFR
   134            Ptr IERR;       //! register IERR
   135            Ptr B30;        //! general purpose register b30
   136            Ptr B31;        //! general purpose register b31
   137            Ptr B28;        //! general purpose register b28
   138            Ptr B29;        //! general purpose register b29
   139            Ptr B26;        //! general purpose register b26
   140            Ptr B27;        //! general purpose register b27
   141            Ptr B24;        //! general purpose register b24
   142            Ptr B25;        //! general purpose register b25
   143            Ptr B22;        //! general purpose register b22
   144            Ptr B23;        //! general purpose register b23
   145            Ptr B20;        //! general purpose register b20
   146            Ptr B21;        //! general purpose register b21
   147            Ptr B18;        //! general purpose register b18
   148            Ptr B19;        //! general purpose register b19
   149            Ptr B16;        //! general purpose register b16
   150            Ptr B17;        //! general purpose register b17
   151            Ptr B14;        //! general purpose register b14
   152            Ptr B15;        //! general purpose register b15
   153            Ptr B12;        //! general purpose register b12
   154            Ptr B13;        //! general purpose register b13
   155            Ptr B10;        //! general purpose register b10
   156            Ptr B11;        //! general purpose register b11
   157            Ptr B8;         //! general purpose register b8
   158            Ptr B9;         //! general purpose register b9
   159            Ptr B6;         //! general purpose register b6
   160            Ptr B7;         //! general purpose register b7
   161            Ptr B4;         //! general purpose register b4
   162            Ptr B5;         //! general purpose register b5
   163            Ptr B2;         //! general purpose register b2
   164            Ptr B3;         //! general purpose register b3
   165            Ptr B0;         //! general purpose register b0
   166            Ptr B1;         //! general purpose register b1
   167            Ptr A30;        //! general purpose register a30
   168            Ptr A31;        //! general purpose register a31
   169            Ptr A28;        //! general purpose register a28
   170            Ptr A29;        //! general purpose register a29
   171            Ptr A26;        //! general purpose register a26
   172            Ptr A27;        //! general purpose register a27
   173            Ptr A24;        //! general purpose register a24
   174            Ptr A25;        //! general purpose register a25
   175            Ptr A22;        //! general purpose register a22
   176            Ptr A23;        //! general purpose register a23
   177            Ptr A20;        //! general purpose register a20
   178            Ptr A21;        //! general purpose register a21
   179            Ptr A18;        //! general purpose register a18
   180            Ptr A19;        //! general purpose register a19
   181            Ptr A16;        //! general purpose register a16
   182            Ptr A17;        //! general purpose register a17
   183            Ptr A14;        //! general purpose register a14
   184            Ptr A15;        //! general purpose register a15
   185            Ptr A12;        //! general purpose register a12
   186            Ptr A13;        //! general purpose register a13
   187            Ptr A10;        //! general purpose register a10
   188            Ptr A11;        //! general purpose register a11
   189            Ptr A8;         //! general purpose register a8
   190            Ptr A9;         //! general purpose register a9
   191            Ptr A6;         //! general purpose register a6
   192            Ptr A7;         //! general purpose register a7
   193            Ptr A4;         //! general purpose register a4
   194            Ptr A5;         //! general purpose register a5
   195            Ptr A2;         //! general purpose register a2
   196            Ptr A3;         //! general purpose register a3
   197            Ptr A0;         //! general purpose register a0
   198            Ptr A1;         //! general purpose register a1
   199        };
   200
   201        /*! Status - structure filled by getLastStatus(). */
   202        struct Status {
   203            Bits32  efr;            //! EFR register
   204            Bits32  nrp;            //! NRP register
   205            Bits32  ntsr;           //! NTSR register
   206            Bits32  ierr;           //! IERR register
   207            Context *excContext;    //! Context structure filled by last exception
   208        };
   209
   210        // -------- Module Constants --------
   211
   212        /*
   213         *  Bitmasks for C64+ Exception Flag Register (EFR).
   214         */
   215        const Bits32 EFRSXF = 0x00000001;   //! Software exception flag
   216        const Bits32 EFRIXF = 0x00000002;   //! Internal exception flag
   217        const Bits32 EFREXF = 0x40000000;   //! EXCEP flag
   218        const Bits32 EFRNXF = 0x80000000;   //! NMI exception flag
   219
   220        /*
   221         *  Bitmasks for C64+ Exception Clear Register (ECR).
   222         */
   223        const Bits32 ECRSXF = EFRSXF;       //! Software exception flag
   224        const Bits32 ECRIXF = EFRIXF;       //! Internal exception flag
   225        const Bits32 ECREXF = EFREXF;       //! EXCEP flag
   226        const Bits32 ECRNXF = EFRNXF;       //! NMI exception flag
   227
   228        /*
   229         *  Bitmasks for C64+ Internal Exception Report Register (IERR).
   230         */
   231        const Bits32 IERRIFX = 0x00000001;  //! Instruction fetch exception
   232        const Bits32 IERRFPX = 0x00000002;  //! Fetch packet exception
   233        const Bits32 IERREPX = 0x00000004;  //! Execute packet exception
   234        const Bits32 IERROPX = 0x00000008;  //! Opcode exception
   235        const Bits32 IERRRCX = 0x00000010;  //! Resource conflict exception
   236        const Bits32 IERRRAX = 0x00000020;  //! Resource access exeption
   237        const Bits32 IERRPRX = 0x00000040;  //! Priviledge exception
   238        const Bits32 IERRLBX = 0x00000080;  //! Loop buffer exception
   239        const Bits32 IERRMSX = 0x00000100;  //! Missed stall exception
   240
   241        /*
   242         *  Exception-related bitmasks for C64+ Task State Register (TSR).
   243         */
   244        const Bits32 TSRGEE = 0x00000004;   //! Global exception enable
   245        const Bits32 TSRXEN = 0x00000008;   //! External exception enable
   246        const Bits32 TSREXC = 0x00000400;   //! Exception processing
   247
   248        /* TSR Privilege Mode bits */
   249        const Bits32 TSRCXM   = 0x000000C0; //! Current execution mode bits
   250        const Bits32 TSRCXMSHIFT = 6;       //! TSR.CXM left shift value
   251        const Bits32 TSRCXMSV = 0x00000000; //! Supervisor mode
   252        const Bits32 TSRCXMUS = 0x00000040; //! User mode
   253
   254        /*! Error raised when abortFlag is true */
   255        config Error.Id E_exceptionMin = {
   256            msg: "E_exceptionMin: pc = 0x%08x, sp = 0x%08x."
   257        };
   258
   259        config Error.Id E_exceptionMax = {
   260            msg: "E_exceptionMax: pc = 0x%08x, sp = 0x%08x.\nTo see more exception detail, use ROV or set 'ti.sysbios.family.c64p.Exception.enablePrint = true;'"
   261        };
   262
   263        // -------- Module Parameters --------
   264
   265        /*!
   266         *  enableExternalMPC - Enable handling of Memory Protection
   267         *  Controller (MPC) exceptions.
   268         */
   269        config Bool enableExternalMPC = false;
   270
   271        /*!
   272         *  enablePrint - Enable print of exception details and Register values
   273         */
   274        config Bool enablePrint = true;
   275
   276        /*!
   277         *  exceptionHook - Function hook called by handler
   278         *  This is called anytime an exception occurs.
   279         */
   280        config FuncPtr exceptionHook = null;
   281
   282        /*!
   283         *  internalHook - Function hook called by internalHandler
   284         *  Function is only called when an internal exception has occurred.
   285         */
   286        config FuncPtr internalHook = null;
   287
   288        /*!
   289         *  externalHook - Function hook called by externalHandler
   290         *  Function is only called when an external exception has occurred.
   291         */
   292        config FuncPtr externalHook = null;
   293
   294        /*!
   295         *  nmiHook - Function hook called by nmiHandler
   296         *  Function is called for legacy NMI exceptions only
   297         */
   298        config FuncPtr nmiHook = null;
   299
   300        /*! returnHook - Function hook called at the end of Exception_dispatch */
   301        config FuncPtr returnHook = null;
   302
   303        /*!
   304         *  getLastStatus - Fills passed status structure with the Status
   305         *  fields that were recorded by the last invocation of
   306         *  dispatch(), handler() and internalHandler().
   307         *  The 'excContext' is valid only in the scope of sub-handler
   308         *  "Hook" functions, since the Context structure is stored on the
   309         *  Hwi ISR stack.
   310         */
   311        @DirectCall
   312        Void getLastStatus(Status *status);
   313
   314        /*!
   315         *  clearLastStatus - Clears internal Status structure.
   316         */
   317        @DirectCall
   318        Void clearLastStatus();
   319
   320        /*!
   321         *  setReturnPtr - Configures dispatch() to "return" (branch) to the
   322         *  passed ptr.
   323         */
   324        @DirectCall
   325        FuncPtr setReturnPtr(FuncPtr ptr);
   326
   327        /*!
   328         *  evtEvtClear - Clear a C64+ event from the EVTFLAG register.
   329         */
   330        @DirectCall
   331        Void evtEvtClear(UInt event);
   332
   333        /*!
   334         *  evtExpMaskEnable - Enable a C64+ event to generate an exception.
   335         */
   336        @DirectCall
   337        Void evtExpMaskEnable(UInt event);
   338
   339        /*! @_nodoc
   340         *  dispatch - The default low-level dispatcher, plugged into the
   341         *  C64+ NMI vector.
   342         */
   343        @DirectCall
   344        Void dispatch();
   345
   346    internal:
   347
   348        /* MPC CPU Access Memory Protecton Fault Event numbers */
   349        const UInt EVTPMCCMPA = 120;        /* PMC memory protection fault event */
   350        const UInt EVTDMCCMPA = 122;        /* DMC memory protection fault event */
   351        const UInt EVTUMCCMPA = 124;        /* UMC memory protection fault event */
   352        const UInt EVTEMCCMPA = 126;        /* EMC memory protection fault event */
   353
   354        /*!
   355         *  handler - The high-level dispatcher, called by dispatch().
   356         *  Performs the following steps in order:
   357         *    a. records EFR/NRP/NTSR in a Status structure
   358         *    b. logs EFR/NRP/NTSR.CXM with text output to module's logger
   359         *    c. calls exceptionHook
   360         *    d. clears EFR
   361         *    e. calls into subhandlers
   362         *    f. aborts system
   363         */
   364        Void handler(Bool abortFlag);
   365
   366        /*!
   367         *  internalHandler - Internal exception handler called by
   368         *  handler().  Performs the following steps in order:
   369         *    a. records IERR in a Status structure
   370         *    b. logs IERR with text output to module's logger
   371         *    c. calls internalHook
   372         *    d. clears IERR
   373         */
   374        Void internalHandler();
   375
   376        /*!
   377         *  externalHandler - External exception handler called by
   378         *  handler().  Performs the following steps in order:
   379         *    a. logs text output to module's logger
   380         *    b. calls externalHook
   381         */
   382        Void externalHandler();
   383
   384        /*!
   385         *  nmiHandler - Legacy NMI handler called by handler().
   386         *  Performs the following steps in order:
   387         *    a. logs text output to module's logger
   388         *    b. calls nmiHook
   389         */
   390        Void nmiHandler();
   391
   392        struct Module_State {
   393            Bits32  efr;
   394            Bits32  nrp;
   395            Bits32  ntsr;
   396            Bits32  ierr;
   397            FuncPtr returnHook;
   398            Context *excContext;
   399            Char    scratch[16];    // sratch memory used by dispatch
   400            Char    *isrStack;      // for ROM - Points to isrStack address
   401        };
   402
   403    }
   404
   405    /*
   406     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:01; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   407
   408     */
   409


module ti.sysbios.family.c64p.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c64p;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Log;
    44
    45    /*!
    46     *  ======== Hwi ========
    47     *  C64+ Hardware Interrupt Support Module.
    48     *
    49     *  This Hwi module provides C64+ family-specific implementations of the
    50     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    51     *
    52     *  Additional C64+ device-specific APIs are also provided.
    53     *
    54     *  An example of creating a Hwi instance:
    55     *
    56     *  @p(code)
    57     *
    58     *  Int intNum;
    59     *  Hwi_Params params;
    60     *  Error_Block eb;
    61     *
    62     *  // Initialize the error block
    63     *  Error_init(&eb);
    64     *
    65     *  // Initialize the Hwi parameters
    66     *  Hwi_Params_init(&params);
    67     *
    68     *  // Set the GEM event id in the params
    69     *  params.eventId = 78
    70     *
    71     *  // Specify the interrupt vector number
    72     *  intNum = 8;
    73     *
    74     *  // create the Hwi for the specified interrupt number and params
    75     *  Hwi_create(intNum, myIsr, &params, &eb);
    76     *
    77     *  @p
    78     *
    79     *  @a(NOTE)
    80     *  In this Hwi module implementation, the instance config parameter value
    81     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    82     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    83     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    84     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    85     *  silently converted to {@link #MaskingOption_SELF}.
    86     *
    87     *  @p(html)
    88     *  <h3> Calling Context </h3>
    89     *  <table border="1" cellpadding="3">
    90     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    91     *
    92     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    93     *    <!--                                                                                                                 -->
    94     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    97     *    <tr><td> {@link #disableIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    99     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   100     *    <tr><td> {@link #enableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   101     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #eventMap}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   103     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   105     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   106     *    <tr><td> {@link #restoreIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   107     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   108     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   109     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   110     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   111     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   112     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   113     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   114     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   115     *    <tr><td colspan="6"> Definitions: <br />
   116     *       <ul>
   117     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   118     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   119     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   120     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   121     *           <ul>
   122     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   123     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   124     *             <li> During main().</li>
   125     *             <li> During BIOS.startupFxns.</li>
   126     *           </ul>
   127     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   128     *           <ul>
   129     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   130     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   131     *           </ul>
   132     *       </ul>
   133     *    </td></tr>
   134     *
   135     *  </table>
   136     *  @p
   137     */
   138
   139    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   140    @ModuleStartup         /* generate a call to Hwi_init at startup */
   141
   142    module Hwi inherits ti.sysbios.interfaces.IHwi
   143    {
   144        // -------- Module Constants --------
   145
   146        /*! C64+ supports 16 interrupts. */
   147        const Int NUM_INTERRUPTS = 16;
   148
   149        // -------- Module Types --------
   150
   151        /*! @_nodoc Hwi plug function type definition. */
   152        typedef Void (*PlugFuncPtr)(void);
   153
   154        /*!
   155         *  ======== BasicView ========
   156         *  @_nodoc
   157         */
   158        metaonly struct BasicView {
   159            Ptr         halHwiHandle;
   160            String      label;
   161            UInt        intNum;
   162            String      fxn;
   163            UArg        arg;           // Argument to Hwi function.
   164            Ptr         irp;
   165            UInt        eventId;
   166            String      disableMask;   // Interrupts to mask during ISR.
   167            String      restoreMask;   // Interrupts to restore after ISR.
   168        };
   169
   170        /*!
   171         *  ======== ModuleView ========
   172         *  @_nodoc
   173         */
   174        metaonly struct ModuleView {
   175            String      options[4];
   176            SizeT       hwiStackPeak;
   177            SizeT       hwiStackSize;
   178            Ptr         hwiStackBase;
   179        };
   180
   181        /*!
   182         *  ======== rovViewInfo ========
   183         *  @_nodoc
   184         */
   185        @Facet
   186        metaonly config ViewInfo.Instance rovViewInfo =
   187            ViewInfo.create({
   188                viewMap: [
   189                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   190                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   191                ]
   192            });
   193
   194        // -------- Module Parameters --------
   195
   196        /*!
   197         *  non-dispatched interrupt object.
   198         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   199         */
   200        metaonly struct NonDispatchedInterrupt {
   201            Int             intNum;
   202            PlugFuncPtr     fxn;            /*! "Hwi_plug'd" ISR function. */
   203            Bool            enableInt;
   204            Int             eventId;
   205        };
   206
   207        /*!
   208         *  non-dispatched interrupt array.
   209         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   210         */
   211        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   212
   213        /*!
   214         *  Alternate reset vector address. Default is undefined.
   215         *
   216         *  if initialized by the user then an additional reset vector
   217         *  is created and placed in the ".resetVector" section.
   218         *  To place the .resetVector section into a specific memory section,
   219         *  add the following command to your config script:
   220         *  @p(code)
   221         *  Program.sectMap[".resetVector"] = YourMemorySection;
   222         *  @p
   223         */
   224        metaonly config Ptr resetVectorAddress;
   225
   226        /*!
   227         *  Error raised when Hwi is already defined
   228         */
   229        config Error.Id E_alreadyDefined = {
   230            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   231        };
   232
   233        /*!
   234         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   235         */
   236        config Log.Event LM_begin = {
   237            mask: Diags.USER1 | Diags.USER2,
   238            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   239        };
   240
   241        /*!
   242         *  Issued just after return from Hwi function (with interrupts disabled)
   243         */
   244        config Log.Event LD_end = {
   245            mask: Diags.USER2,
   246            msg: "LD_end: hwi: 0x%x"
   247        };
   248
   249        /*!
   250         *  enable Exception module for exception processing.
   251         */
   252        config Bool enableException = true;
   253
   254        // -------- Module Functions --------
   255
   256        /*!
   257         *  ======== disable ========
   258         */
   259        @Macro
   260        override UInt disable();
   261
   262        /*!
   263         *  ======== enable ========
   264         */
   265        @Macro
   266        override UInt enable();
   267
   268        /*!
   269         *  ======== restore ========
   270         */
   271        @Macro
   272        override Void restore(UInt key);
   273
   274        /*!
   275         *  ======== inUseMeta ========
   276         *  @_nodoc
   277         *  Check for Hwi already in use.
   278         *  For internal SYS/BIOS use only.
   279         *  Should be called prior to any internal Hwi.create().
   280         *
   281         *  @param(intNum)  interrupt number
   282         */
   283        metaonly Bool inUseMeta(UInt intNum);
   284
   285        /*!
   286         *  ======== eventMap ========
   287         *  Maps a GEM event to interrupt number
   288         *
   289         *  Function maps a GEM event to an interrupt number so that the
   290         *  event is the interrupt source of the vector.
   291         *
   292         *  @p(code)
   293         *      // Maps GEM event #65 as the interrupt source of int vector #7
   294         *      Hwi_eventMap(7, 65);
   295         *  @p
   296         *
   297         *  @param(intNum)  interrupt number
   298         *  @param(eventId) event ID
   299         */
   300        @DirectCall
   301        Void eventMap(Int intNum, Int eventId);
   302
   303        /*!
   304         *  ======== eventMapMeta ========
   305         *  Maps GEM Event to interrupt number statically
   306         *
   307         *  Function maps a GEM event to an interrupt number so that the
   308         *  event is the interrupt source of the vector.
   309         *
   310         *  @p(code)
   311         *      // Maps GEM event #65 as the interrupt source of int vector #7
   312         *      Hwi.eventMapMeta(7, 65);
   313         *  @p
   314         *
   315         *  @param(intNum)      interrupt number
   316         *  @param(eventId)     event Id
   317         */
   318        metaonly Void eventMapMeta(Int intNum, Int eventId);
   319
   320        /*!
   321         *  @_nodoc
   322         *  ======== plug ========
   323         *  Plug an interrupt vector with an ISR address.
   324         *
   325         *  Hwi_plug writes an Interrupt Service Fetch Packet (ISFP) into the
   326         *  Interrupt Service Table (IST), at the address corresponding to intNum
   327         *  The op-codes written in the ISFP create a branch to the function
   328         *  entry  point specified by fxn:
   329         *
   330         *  @p(code)
   331         *          stw     b0, *SP--[1]
   332         *          mvk     fxn, b0
   333         *          mvkh    fxn, b0
   334         *          b       b0
   335         *          ldw     *++SP[1],b0
   336         *          nop     4
   337         *  @p
   338         *
   339         *  Hwi_plug hooks up the specified function as the branch target of a
   340         *  hardware interrupt (fielded by the CPU) at the vector address
   341         *  specified in intNum. Hwi_plug does not enable the interrupt.
   342         *  Use Hwi_enableIER to enable specific interrupts.
   343         *
   344         *  For internal SYS/BIOS use only.
   345         *
   346         *  Constraints and Calling Context
   347         *  o vecid must be a valid interrupt ID in the range of 0-15.
   348         *
   349         *  @param(intNum)  interrupt number
   350         *  @param(fxn)     pointer to ISR function
   351         */
   352        @DirectCall
   353        Void plug(UInt intNum, PlugFuncPtr fxn);
   354
   355        /*!
   356         *  ======== plugMeta ========
   357         *  Statically plug an interrupt vector with an ISR address.
   358         *
   359         *  @param(intNum)  interrupt number
   360         *  @param(fxn)     pointer to ISR function
   361         */
   362        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   363
   364        /*!
   365         *  ======== getHandle ========
   366         *  Returns Hwi_handle associated with interrupt number
   367         *
   368         *  @param(intNum)  interrupt number
   369         *  @b(returns)     handle associated with intNum
   370         */
   371        @DirectCall
   372        Handle getHandle(UInt intNum);
   373
   374        /*!
   375         *  ======== disableIER ========
   376         *  Disable certain maskable interrupts.
   377         *
   378         *  Atomically disables specific interrupts by clearing the bits
   379         *  specified by mask in the Interrupt Enable Register (IER).
   380         *
   381         *  The IER bits to be cleared should be set to 1 in the mask.
   382         *
   383         *  @param(mask)    bitmask of interrupts to disable
   384         *  @b(returns)     previous IER settings bitmask
   385         */
   386        @DirectCall
   387        Bits16 disableIER(Bits16 mask);
   388
   389        /*!
   390         *  ======== enableIER ========
   391         *  Enable certain maskable interrupts.
   392         *
   393         *  Atomically enables specific interrupts by setting the bits
   394         *  specified by mask in the Interrupt Enable Register (IER).
   395         *
   396         *  The IER bits to be set should be set to 1 in the mask.
   397         *
   398         *  @param(mask)    bitmask of interrupts to enable
   399         *  @b(returns)     previous IER settings bitmask
   400         */
   401        @DirectCall
   402        Bits16 enableIER(Bits16 mask);
   403
   404        /*!
   405         *  ======== restoreIER ========
   406         *  Restore maskable interrupts to the state they were in
   407         *  when either disableIER() or enableIER() was called.
   408         *
   409         *  Atomically writes the given mask to the IER register. Typically used
   410         *  to restore the IER register to the state returned from a call to
   411         *  either {@link #disableIER()} or {@link #enableIER()}.
   412         *
   413         *  @param(mask)    bitmask of interrupts to restore
   414         *  @b(returns)     previous IER settings bitmask
   415         */
   416        @DirectCall
   417        Bits16 restoreIER(Bits16 mask);
   418
   419    instance:
   420
   421        /*!
   422         *  Dispatcher auto-nesting interrupt disable mask.
   423         *
   424         *  When the dispatcher's auto interrupt nesting support feature
   425         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   426         *  this mask defines which IER bits are disabled prior to invoking
   427         *  the user's ISR function with GIE = 1.
   428         *
   429         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   430         *  prior to invoking the ISR.
   431         *
   432         *  The value of this mask is normally auto-calculated based on the
   433         *  value of the maskSetting. However, manual setting of this
   434         *  mask is enabled by setting the maskSetting to
   435         *  {@link #MaskingOption MaskingOption_BITMASK}.
   436         *
   437         *  The default value is derived from the
   438         *  {@link #MaskingOption MaskingOption_SELF}
   439         *  maskSetting.
   440         */
   441        config Bits16 disableMask = 0;
   442
   443        /*!
   444         *  Dispatcher auto-nesting interrupt restore mask.
   445         *
   446         *  When the dispatcher's auto interrupt nesting support feature
   447         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   448         *  this mask defines which IER bits are restored to their previous
   449         *  setting upon return from the user's ISR function.
   450         *
   451         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   452         *
   453         *  The value of this mask is normally auto-calculated based on the
   454         *  value of the maskSetting. However, manual setting of this
   455         *  mask is enabled by setting the maskSetting to
   456         *  {@link #MaskingOption MaskingOption_BITMASK}.
   457         *
   458         *  The default value is derived from the
   459         *  {@link #MaskingOption MaskingOption_SELF}
   460         *  maskSetting.
   461         */
   462        config Bits16 restoreMask = 0;
   463
   464        /*!
   465         *  Interrupt priority. Not supported on this target.
   466         */
   467        override config Int priority = 0;
   468
   469        /*!
   470         *  ======== reconfig ========
   471         *  Reconfigures a dispatched interrupt.
   472         *
   473         *  This function reconfigures the dispatched interrupt so the
   474         *  specified function is called with the specified parameters.
   475         *
   476         *  @param(fxn)     pointer to ISR function
   477         *  @param(params)  pointer to Hwi parameter structure
   478         */
   479        @DirectCall
   480        Void reconfig(FuncPtr fxn, const Params *params);
   481
   482    internal:   /* not for client use */
   483
   484        /*
   485         * Swi and Task module function pointers.
   486         * Used to decouple Hwi from Swi and Task when
   487         * dispatcherSwiSupport or
   488         * dispatcherTaskSupport is false.
   489         */
   490        config UInt (*swiDisable)();
   491        config Void (*swiRestoreHwi)(UInt);
   492        config UInt (*taskDisable)();
   493        config Void (*taskRestoreHwi)(UInt);
   494
   495        /*
   496         *  ======== getIsrStackAddress ========
   497         *  Returns initial isrStack address.
   498         *  This API was developed solely for the Exception module
   499         *  to allow removal of the Hwi_link.xdt template definition
   500         *  of ti_sysbios_family_c64p_Hwi_isrStack which was not
   501         *  ROM-able
   502         */
   503        Char *getIsrStackAddress();
   504
   505        /*
   506         *  ======== getEvent ========
   507         *  Returns associated event num from INTMUX
   508         */
   509        UInt getEvent(UInt intNum);
   510
   511        /* Interrupt Dispatcher */
   512        Void dispatchC(Int intNum);
   513
   514        /* unPlugged interrupt handler */
   515        Void unPluggedInterrupt();
   516
   517        /*!
   518         *  const array to hold all HookSet objects.
   519         */
   520        config HookSet hooks[length] = [];
   521
   522        /*! Meta World Only Hwi Configuration Object. */
   523        metaonly struct InterruptObj {
   524            String name;            /* symbol used for vector table entry */
   525            Bool used;              /* Interrupt already defined? */
   526            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   527            FuncPtr fxn;            /* Dispatched ISR function */
   528            PlugFuncPtr pfxn;       /* "Hwi_plug'd" ISR function. */
   529        };
   530
   531        /*!
   532         * Meta-only array of interrupt objects.
   533         * This meta-only array of Hwi config objects is initialized
   534         * in Hwi.xs:module$meta$init().
   535         */
   536        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   537
   538        struct Instance_State {
   539            Bits16      disableMask;    // Interrupts to mask during ISR.
   540            Bits16      restoreMask;    // Interrupts to restore after ISR.
   541            UArg        arg;            // Argument to Hwi function.
   542            FuncPtr     fxn;            // Hwi function.
   543            Irp         irp;            // current IRP
   544            Ptr         hookEnv[];
   545        };
   546
   547        struct Module_State {
   548            Char        intEvents[12];  // Initial event mapping
   549            Bits16      ierMask;        // Initial IER mask
   550            Char        *taskSP;        // temporary storage of interrupted
   551                                        // Task's SP during ISR execution
   552            /* ROM */
   553            Char        *isrStack;      // Points to isrStack address
   554            Ptr         vectorTableBase;// ti_sysbios_family_c64_Hwi0
   555            Ptr         bss;            // bss address
   556
   557            Handle      dispatchTable[NUM_INTERRUPTS];
   558                                        // dispatch table
   559        };
   560    }
   561
   562    /*
   563     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:01; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   564
   565     */
   566


module ti.sysbios.family.c64p.MemoryProtect

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== MemoryProtect.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p;
    39
    40    /*!
    41     *  ======== MemoryProtect ========
    42     *  MemoryProtect Module
    43     *
    44     *  This module provide an API to {@link #getPA() get} and to
    45     *  {@link #setPA() set} the permission attributes of a memory range.
    46     *  A memory range can be set to user {@link #MPPA_UX executable},
    47     *  user {@link #MPPA_UW writable}, user {@link #MPPA_UR readable},
    48     *  supervisor {@link #MPPA_SX executable}, supervisor
    49     *  {@link #MPPA_SW writable}, or supervisor {@link #MPPA_SR readable}.
    50     *  Setting a memory range to only user readable, writable or executable
    51     *  should be done with caution because BIOS executes in supervisor mode.
    52     *  Whenever setting the permission attributes of a memory range,
    53     *  the {@link #MPPA_LOCAL local} CPU access field must be set, if the
    54     *  local CPU accesses the memory range.  If the local field is not set,
    55     *  an exception is generated if the CPU tries to access the memory range.
    56     *
    57     *  This module is to be used in correlation with the
    58     *  {@link ti.sysbios.family.c64p.Exception Exception} module.
    59     *  When this module is in use, external exceptions are enabled by default.
    60     *  Any memory protection fault which arises generates an exception.
    61     *  This exception is processed and decoded by the Exception module.
    62     *
    63     *  An example of setting Local L2 RAM to be supervisor read-only and
    64     *  CPU accessible:
    65     *
    66     *  @p(code)
    67     *    UInt32 paMask;
    68     *    paMask = MemoryProtect_MPPA_LOCAL |
    69     *             MemoryProtect_MPPA_SR;
    70     *
    71     *    MemoryProtect_setPA((Ptr)0x11800000, 0x40000, paMask);
    72     *  @p
    73     *
    74     *  @p(html)
    75     *  <h3> Calling Context </h3>
    76     *  <table border="1" cellpadding="3">
    77     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    78     *
    79     *    <tr><th> Function               </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    80     *    <!--                                                                                                                 -->
    81     *    <tr><td> {@link #getPA}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    82     *    <tr><td> {@link #setPA}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    83     *    <tr><td colspan="6"> Definitions: <br />
    84     *       <ul>
    85     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    86     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    87     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    88     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    89     *           <ul>
    90     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    91     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    92     *             <li> During main().</li>
    93     *             <li> During BIOS.startupFxns.</li>
    94     *           </ul>
    95     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    96     *           <ul>
    97     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    98     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    99     *           </ul>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     */
   106
   107    @ModuleStartup
   108
   109    module MemoryProtect
   110    {
   111        // -------- Module Types --------
   112
   113        /*
   114         *  MPPA Permission Attribute Register bitmasks.
   115         */
   116        const UInt32 MPPA_UX    = 0x00000001;   /*! User mode may execute       */
   117        const UInt32 MPPA_UW    = 0x00000002;   /*! User mode may write         */
   118        const UInt32 MPPA_UR    = 0x00000004;   /*! User mode may read          */
   119        const UInt32 MPPA_SX    = 0x00000008;   /*! Supervisor mode may execute */
   120        const UInt32 MPPA_SW    = 0x00000010;   /*! Supervisor mode may write   */
   121        const UInt32 MPPA_SR    = 0x00000020;   /*! Supervisor mode read        */
   122        const UInt32 MPPA_LOCAL = 0x00000100;   /*! Local CPU may access        */
   123
   124        /*!
   125         *  ======== getPA ========
   126         *  Gets the PA (Permission Attribute) corresponding to addr.
   127         *
   128         *  @param(addr)    address of memory location for which the PA applies
   129         *  @param(paMask)  ptr to location where PA mask for addr is stored
   130         *
   131         *  @b(returns)     if address doesn't belong to any configured MPC then
   132         *                  FALSE, otherwise TRUE and *paMask contains addr's
   133         *                  MPPA setting
   134         */
   135        Bool getPA(Ptr addr, UInt32 *paMask);
   136
   137        /*!
   138         *  ======== setPA ========
   139         *  Sets the PA (Permission Attribute) corresponding to addr/size.
   140         *
   141         *  The PA is applied to all addresses that are spanned by the
   142         *  memory block.
   143         *
   144         *  @param(addr)    begin address of memory block for which the PA applies
   145         *  @param(size)    size of memory block
   146         *  @param(paMask)  PA mask to assign for the memory block
   147         *
   148         *  @b(returns)     if address doesn't belong to any configured MPC then
   149         *                  FALSE, otherwise TRUE and PA was written to addr's
   150         *                  MPPA register
   151         */
   152        Bool setPA(Ptr addr, SizeT size, UInt32 paMask);
   153
   154        /*!@_nodoc
   155         *  ======== getPageSize ========
   156         *  Gets the page size corresponding to addr.
   157         *
   158         *  @param(addr)    address of memory location for which the PA applies
   159         *  @param(pageSize) pointer to location where the page size is stored
   160         *
   161         *  @b(returns)     FALSE - address doesn't belong to any configured MPC
   162         *                  TRUE - *pageSize contains addr's MPC page size
   163         */
   164        Bool getPageSize(Ptr addr, UInt *pageSize);
   165
   166        /*!@_nodoc
   167         *  ======== getPrivMode ========
   168         *  Retrieves the current privilege mode
   169         *
   170         *  @b(returns)     current privilege mode
   171         */
   172        UInt getPrivMode();
   173
   174        /*!@_nodoc
   175         *  ======== setPrivMode ========
   176         *  Sets the privilege mode
   177         *
   178         *  @param(mode)    the privilege mode to set
   179         */
   180        Void setPrivMode(UInt mode);
   181
   182
   183    internal:
   184
   185        /*!
   186         *  Struct defining the bit range of an address
   187         */
   188        struct BitRange {
   189            Char msb;
   190            Char lsb;
   191        };
   192
   193        /*!
   194         *  Each MPC needs to implement MPLCK.
   195         *  DMC/PMC/UMA all conform to the struct below.
   196         */
   197        struct Lock {
   198            volatile UInt32 mpLk0;      /* lock bits 31-0 */
   199            volatile UInt32 mpLk1;      /* lock bits 63-32 */
   200            volatile UInt32 mpLk2;      /* lock bits 95-64 */
   201            volatile UInt32 mpLk3;      /* lock bits 127-96 */
   202            volatile UInt32 mpLkCmd;    /* lock command register */
   203            volatile UInt32 mpLkStat;   /* lock status register */
   204        };
   205
   206        /*!
   207         *  Struct defining the fault registers
   208         */
   209        struct Fault {
   210            volatile UInt32 mpFar;      /* MPC Fault Address Register */
   211            volatile UInt32 mpFsr;      /* MPC Fault Status Register */
   212            volatile UInt32 mpFcr;      /* MPC Fault Clear Register */
   213        };
   214
   215        /*!
   216         *  Key represents the 128-bit key used for locking
   217         *  and unlocking a controller's permission attribute entries.
   218         *  It is used for writing to the MPLK0-MPLK3 registers.
   219         */
   220        struct Key {
   221            UInt32  key0;       /* bits 0-31 of 128-bit key */
   222            UInt32  key1;       /* bits 32-63 of 128-bit key */
   223            UInt32  key2;       /* bits 64-95 of 128-bit key */
   224            UInt32  key3;       /* bits 96-127 of 128-bit key */
   225        };
   226
   227        /*!
   228         *  Struct defining a controller
   229         */
   230        struct Controller {
   231            Fault   *mpFault;       /* addr of MP Fault registers */
   232            Lock    *mpLck;         /* addr of MP Lock registers */
   233            UInt32  *mppaTab;       /* addr of base of MP PA table */
   234            UInt32  *mpCfg;         /* addr of MP Configuration register */
   235            UInt32  nPages;         /* # pages in the MPC */
   236            UInt32  evtNum;         /* Event number for controller */
   237        };
   238
   239        /*!
   240         *  The following values relate to indexing into the module state
   241         *  controller array.  Subtract 1 from the value before using it as an
   242         *  index into the 0-based array (NONE isn't used to index the array).
   243         */
   244        const UInt NONE  = 0;
   245        const UInt UMAP0 = 1;
   246        const UInt UMAP1 = 2;
   247        const UInt DMC   = 3;
   248        const UInt PMC   = 4;
   249        const UInt UMC   = UMAP0;
   250
   251        /*! lock/unlock values */
   252        const UInt LCKUNLOCK  = 0x00000001;
   253        const UInt LCKLOCK    = 0x00000002;
   254        const UInt LCKKEYR    = 0x00000004;
   255        const UInt LKSTATLK   = 0x00000001;
   256
   257        /*! The key values used for locking/unlocking PA table */
   258        config Key key = {
   259            key0: 0x90abcdef,
   260            key1: 0x12345678,
   261            key2: 0x87654321,
   262            key3: 0xfedcba09
   263        };
   264
   265        /*!
   266         *  Region Extract Masks table indexed by [controller(0-3)][region(0-1)].
   267         *  The constants used are fixed based on the GEM architecture spec.
   268         *  They are based on the minimum theoretical page size (lower constant)
   269         *  and the number of pages (higher constant minus lower constant).
   270         *  However, in reality, the actual minimum page size is floored at
   271         *  some minimum (i.e., the "size" parameter can't, per the
   272         *  HW design spec, be lower than some minimum (2 for DMC/PMC, 6 for UMC).
   273         */
   274        config BitRange regExtMasks[4][2];
   275
   276        /*!
   277         *  This array is used to map the MegaByte field of an address
   278         *  (0x00N00000) to the controller that controls that address.
   279         *  An MPC's address range falls within and is wholy contained
   280         *  in the MegaByte hex digit.
   281         */
   282        config Char megaByte2MPC[16];
   283
   284        /*!
   285         *  Array of addresses that mark the begin of region 0 for each MPC.
   286         *  Each MPC contains two regions (0 & 1), however, the first two
   287         *  entries correspond to the two "regions" of UMC (UMC_P0 & UMC_P1),
   288         *  and as such the entries for them are forced to the max address
   289         *  value such that any compare that uses them will be < them,
   290         *  thus indicating region 0.
   291         */
   292        config UInt regionCompare[4];
   293
   294        /*!
   295         *  Array of addresses that mark the end of region 0 for each MPC.
   296         */
   297        config UInt regionEnd[4];
   298
   299        /*! L1 program memory controller */
   300        config Controller pmcCtrl;
   301
   302        /*! L1 data memory controller */
   303        config Controller dmcCtrl;
   304
   305        /*! L2 unified memory controller */
   306        config Controller umcCtrl;
   307
   308        /*!
   309         *  ======== decodeRegion ========
   310         *  Determine the beginning and end page numbers for region.
   311         *
   312         *  Validate begAddr/endAddr range to be within internal address space.
   313         *  Return region (UMAP0/UMAP1/DMC/PMC), beginning and ending page
   314         *  numbers if valid.  Returns -1 if complete address range is not valid.
   315         */
   316        Int decodeRegion(UInt32 begAddr, UInt32 endAddr,
   317                         UInt32 *begPage, UInt32 *endPage);
   318
   319        /*!
   320         *  ======== getAddrPageSize ========
   321         *  Returns the page size corresponding to addr.
   322         */
   323        Int getAddrPageSize(Ptr addr);
   324
   325        /*!
   326         *  ======== lock ========
   327         *  Locks the permission attribute.
   328         *
   329         *  Locks the permission attribute table entries for the
   330         *  specified controller, using the specified key.
   331         */
   332        Void lock(Controller *ctrl, Key *key);
   333
   334        /*!
   335         *  ======== makeLocal ========
   336         *  Convert address into a local address
   337         *
   338         *  Validate addr to be a GEM internal address & convert addr into
   339         *  its local address if global.  Returns TRUE if addr is a valid GEM
   340         *  internal address, and fills space with local/global code (1/0).
   341         *  Returns FALSE if addr is not a valid GEM internal address.  space
   342         *  is valid only when TRUE is returned.
   343         */
   344        Bool makeLocal(UInt *addr, UInt *space);
   345
   346        /*!
   347         *  ======== readPA ========
   348         *  Reads the permission attribute
   349         *
   350         *  Returns the permission attribute for the specified
   351         *  page within the specified controller.
   352         */
   353        UInt32 readPA(Controller *ctrl, UInt page);
   354
   355        /*!
   356         *  ======== unlock ========
   357         *  Unlocks the permission attribute.
   358         *
   359         *  Unlocks the permission attribute table entries for the
   360         *  specified controller, using the specified key.
   361         */
   362        Void unlock(Controller *ctrl, Key *key);
   363
   364        /*!
   365         *  ======== writePA ========
   366         *  Writes the permission attribute
   367         *
   368         *  Writes the permission attribute perm for the specified
   369         *  page within the specified controller.  The permission attribute
   370         *  entries need to be unlocked first and then locked afterwards.
   371         */
   372        Void writePA(Controller *ctrl, UInt page, UInt32 perm);
   373
   374        /* Module state */
   375        struct Module_State {
   376            Controller *controllers[];
   377        }
   378    }
   379    /*
   380     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   381
   382     */
   383


package ti.sysbios.family.c64p

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    //requires ti.sysbios.knl;
    39
    40    /*!
    41     *  ======== ti.sysbios.family.c64p ========
    42     *  Contains specifications for the C64P specific SYS/BIOS functions.
    43     *
    44     *  The link below provides SYS/BIOS C6x register usage information:
    45     *
    46     *      {@link ./../c62/doc-files/c6xregconv.html SYS/BIOS C6x Register Usage}
    47     *
    48     */
    49    package ti.sysbios.family.c64p [2,0,0,0] {
    50        module EventCombiner;
    51        module Exception;
    52        module Hwi;
    53        module TimestampProvider;
    54        module MemoryProtect;
    55        module Clobber;
    56        module Cache;
    57        module Settings;
    58    }
    59    /*
    60     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    61
    62     */
    63


module ti.sysbios.family.c64p.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.c64p;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  C64P and C674 target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c64p.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     *
    76     */
    77
    78    @ModuleStartup          /* To start TimeStamp Counter */
    79
    80    module TimestampProvider inherits ti.sysbios.interfaces.ITimestamp
    81    {
    82    }
    83
    84    /*
    85     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,497; 6-15-2011 16:25:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    86
    87     */
    88


package ti.sysbios.family.c64p.dm6437

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.dm6437 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.dm6437 [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.dm6437; 2, 0, 0, 0,354; 6-15-2011 16:24:58; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


package ti.sysbios.family.c64p.dm6446

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.dm6446 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.dm6446 [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.dm6446; 2, 0, 0, 0,354; 6-15-2011 16:25:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


package ti.sysbios.family.c64p.omap3430

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.omap3430 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.omap3430 [2,0,0,0] {
    45        module TimerSupport;
    46        module Wugen;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.family.c64p.omap3430; 2, 0, 0, 0,328; 6-15-2011 16:25:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c64p.omap3430.Wugen

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Wugen.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p.omap3430;
    39
    40    /*!
    41     *  ======== Wugen ========
    42     *  Wugen Module
    43     *
    44     *  Unconstrained Functions
    45     *  All functions
    46     *
    47     *  @p(html)
    48     *  <h3> Calling Context </h3>
    49     *  <table border="1" cellpadding="3">
    50     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    51     *
    52     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    53     *    <!--                                                                                                                 -->
    54     *    <tr><td> {@link #applyMasks}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    55     *    <tr><td> {@link #disableDma}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    56     *    <tr><td> {@link #disableEvent}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    57     *    <tr><td> {@link #enableDma}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    58     *    <tr><td> {@link #enableEvent}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    59     *    <tr><td> {@link #getMasks}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    60     *    <tr><td> {@link #ierToMasks} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    61     *    <tr><td colspan="6"> Definitions: <br />
    62     *       <ul>
    63     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    64     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    65     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    66     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    67     *           <ul>
    68     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    69     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    70     *             <li> During main().</li>
    71     *             <li> During BIOS.startupFxns.</li>
    72     *           </ul>
    73     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    74     *           <ul>
    75     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    76     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    77     *           </ul>
    78     *       </ul>
    79     *    </td></tr>
    80     *
    81     *  </table>
    82     *  @p
    83     */
    84
    85    @ModuleStartup
    86
    87    module Wugen
    88    {
    89        /*!
    90         *  ======== applyMasks ========
    91         *  This function takes an array of 3 integers and applies the specified
    92         *  mask to the WUGEN interrupt mask registers. If the bit in the mask is
    93         *  enabled, the corresponding interrupt in the WUGEN will be blocked.
    94         *
    95         *  @param(mask)    array of three integers for applying to the WUGEN
    96         *                  interrupt mask register.
    97         *                  First mask consists of IRQ 0-31
    98         *                  Second mask consists of IRQ 32-47
    99         *                  Third mask consists of DMA requests
   100         */
   101        Void applyMasks(UInt32 mask[]);
   102
   103        /*!
   104         *  ======== disableDma ========
   105         *  Disables the specified DMA source in the WUGEN
   106         *
   107         *  @param(dmaid)   the DMA id for a particular EDMA source.
   108         */
   109        Void disableDma(UInt dmaid);
   110
   111        /*!
   112         *  ======== disableEvent ========
   113         *  Disables the specified interrupt event source in the WUGEN
   114         *
   115         *  @param(eventid) the event number of an interrupt source
   116         */
   117        Void disableEvent(UInt eventid);
   118
   119        /*!
   120         *  ======== enableDma ========
   121         *  Enables the specified DMA source in the WUGEN
   122         *
   123         *  @param(dmaid)   the DMA id for a particular EDMA source.
   124         */
   125        Void enableDma(UInt dmaid);
   126
   127        /*!
   128         *  ======== enableEvent ========
   129         *  Enables the specified interrupt event source in the WUGEN
   130         *
   131         *  @param(eventid) the event number of an interrupt source
   132         */
   133        Void enableEvent(UInt eventid);
   134
   135        /*!
   136         *  ======== getMasks ========
   137         *  This function returns the WUGEN interrupt mask registers
   138         *
   139         *  @param(mask)    array of three integers used to return the WUGEN
   140         *                  interrupt mask registers
   141         *                  First mask consists of IRQ 0-31
   142         *                  Second mask consists of IRQ 32-47
   143         *                  Third mask consists of DMA requests
   144         */
   145        Void getMasks(UInt32 mask[]);
   146
   147        /*!
   148         *  ======== ierToMasks ========
   149         *  Compute the WUGEN masks needed to allow the interrupts set in the IER
   150         *  register to propagate through the WUGEN.  This function does not enable
   151         *  external DMA requests.  You must set these explicitly to configure a
   152         *  DMA request as a wakeup event.
   153         *
   154         *  @param(mask)    array of three integers for returning WUGEN masks.
   155         *                  First mask consists of IRQ 0-31
   156         *                  Second mask consists of IRQ 32-47
   157         *                  Third mask consists of DMA requests
   158         */
   159        Void ierToMasks(UInt32 mask[]);
   160
   161
   162    internal:
   163
   164    }
   165    /*
   166     *  @(#) ti.sysbios.family.c64p.omap3430; 2, 0, 0, 0,328; 6-15-2011 16:25:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   167
   168     */
   169


package ti.sysbios.family.c64p.primus

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.primus ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.primus [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.primus; 2, 0, 0, 0,353; 6-15-2011 16:25:07; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


package ti.sysbios.family.c64p.tci6482

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.tci6482 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.tci6482 [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.tci6482; 2, 0, 0, 0,353; 6-15-2011 16:25:09; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


package ti.sysbios.family.c64p.tci6488

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.tci6488 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.tci6488 [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.tci6488; 2, 0, 0, 0,353; 6-15-2011 16:25:12; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


package ti.sysbios.family.c64p.tesla

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.tesla ========
    41     *  Contains specifications for the c64p.tesla-specific SYS/BIOS functions.
    42     */
    43    package ti.sysbios.family.c64p.tesla [1,0,0,0] {
    44        module TimerSupport;
    45        module Wugen;
    46        module Power;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.family.c64p.tesla; 1, 0, 0, 0,248; 6-15-2011 16:25:16; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c64p.tesla.Power

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Power.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c64p.tesla;
    39
    40    /*!
    41     *  ======== Power ========
    42     *  Power Module
    43     *
    44     *  This module is used to reduce power consumption of the Tesla subsystem.
    45     *  Three reduction techniques are supported:
    46     *
    47     *  Suspend/Resume with Retention: The Tesla subsystem is put into standby,
    48     *  upon which PRCM will transition the power domain to closed-switch retention
    49     *  (CSWR).  Upon release from retention reset, the CPU will start executing
    50     *  from reset; a reset hook function will hijack the boot process, restore CPU
    51     *  state to that before retention, and then return back into the
    52     *  Power_suspend() API, which will return to its caller, to resume the
    53     *  application.
    54     *
    55     *  Suspend/Resume with Hibernation: The Tesla subsystem context is saved to
    56     *  external RAM, and GEM is put into standby.  Upon the standby transition,
    57     *  PRCM will transition the power domain to off.  Upon release from reset, the
    58     *  CPU will start executing from reset; a reset hook function will hijack the
    59     *  boot process, restore CPU state, return back into the Power_suspend() API,
    60     *  which will restore the remaining Tesla subsystem context, and then return
    61     *  to its caller, to resume the application.
    62     *
    63     *  Idling in the Idle loop:  A function will be inserted into the Idle loop,
    64     *  which will automatically idle the CPU while waiting for the next interrupt.
    65     *
    66     *  The application must explicitly call to Power_suspend() for Suspend/Resume
    67     *  functionality.  For idling functionality, this enabled statically, in the
    68     *  application configuration, and the idling in the idle loop will happen
    69     *  routinely upon execution of the Idle loop.
    70     *
    71     *  Suspend/Resume can be invoked from Task, Swi, or Idle loop context.
    72     *  It cannot be invoked from Hwi context.
    73     */
    74    module Power
    75    {
    76        /*! Suspend Level. */
    77        enum  Suspend {
    78            Suspend_RETENTION,      /*! Suspend to RETENTION state */
    79            Suspend_HIBERNATE       /*! Suspend to HIBERNATE state */
    80        };
    81
    82        /*! Base address of EDMA TPCC registers */
    83        config Ptr tpccRegs = 0x01C00000;
    84
    85        /*! Base address of SYSC registers */
    86        config Ptr syscRegs = 0x01C20000;
    87
    88        /*! Idle the CPU when threads blocked waiting for an interrupt? */
    89        config Bool idle = false;
    90
    91        /*! Name of segment to load Power's reset code and saved context */
    92        metaonly config String loadSegment = "EXT_RAM";
    93
    94        /*!
    95         *  ======== idleCPU ========
    96         *  Function used to automatically idle the CPU in the Idle loop.
    97         *
    98         *  When the 'idle' configuration flag is set: this function will
    99         *  be added to the list of Idle loop functions.  When called from the
   100         *  Idle loop, it will invoke the IDLE instruction, to idle the CPU until
   101         *  the next interrupt occurs.  This function will idle the CPU, but will
   102         *  not put the whole megamodule (GEM) into standby.
   103         */
   104        @DirectCall
   105        Void idleCPU();
   106
   107        /*!
   108         *  ======== suspend ========
   109         *  Function used for suspend/resume of the Tesla subsystem.
   110         *
   111         *  This function will save Tesla subsystem context and then put GEM into
   112         *  standby, as the final steps for a transition to either retention
   113         *  (CSWR), or hibernate (also referred to as off-mode).
   114         *
   115         *  Prior to invoking this function the application software must prepare
   116         *  for suspend, which includes: configuring PRCM for the appropriate
   117         *  transition once GEM goes to standby; disabling unintended wakeup
   118         *  interrupts, and configuring intended wakeups; taking care of any
   119         *  required notifications to software components; and 'quieting' of the
   120         *  DSP application (e.g., ensuring that all in-progress EDMA activity
   121         *  completes).
   122         */
   123        @DirectCall
   124        UInt suspend(Suspend level);
   125
   126    internal:
   127
   128        struct CpuSysRegs {
   129            UInt32  AMR;
   130            UInt32  CSR;
   131            UInt32  IER;
   132            UInt32  ISTP;
   133            UInt32  IRP;
   134            UInt32  SSR;
   135            UInt32  GPLYB;
   136            UInt32  GFPGFR;
   137            UInt32  TSR;
   138            UInt32  ITSR;
   139            UInt32  IERR;
   140        }
   141
   142        struct IntcConfig {
   143            UInt32 EVTMASK0;
   144            UInt32 EVTMASK1;
   145            UInt32 EVTMASK2;
   146            UInt32 EVTMASK3;
   147            UInt32 EXPMASK0;
   148            UInt32 EXPMASK1;
   149            UInt32 EXPMASK2;
   150            UInt32 EXPMASK3;
   151            UInt32 INTMUX1;
   152            UInt32 INTMUX2;
   153            UInt32 INTMUX3;
   154            UInt32 AEGMUX0;
   155            UInt32 AEGMUX1;
   156            UInt32 INTDMASK;
   157        };
   158
   159        struct SyscConfig {
   160            UInt32 SYSCONFIG;
   161            UInt32 VBUSM2OCP;
   162            UInt32 EDMA;
   163            UInt32 CORE;
   164            UInt32 IVA_ICTRL;
   165            UInt32 IDLEDLY;
   166        };
   167
   168        struct UnicacheConfig {
   169            UInt32 CONFIG;
   170            UInt32 OCP;
   171        };
   172
   173        struct AmmuConfig {
   174            UInt32 largeAddr[8];
   175            UInt32 largePolicy[8];
   176            UInt32 medAddr[7];
   177            UInt32 medPolicy[7];
   178            UInt32 smallAddr[3];
   179            UInt32 smallPolicy[3];
   180            UInt32 mmuConfig;
   181        };
   182
   183        struct EdmaConfig {
   184            UInt32 CLKGDIS;
   185            UInt32 DCHMAP[64];
   186            UInt32 QCHMAP[8];
   187            UInt32 DMAQNUM[8];
   188            UInt32 QDMAQNUM;
   189            UInt32 QUETCMAP;
   190            UInt32 QUEPRI;
   191            UInt32 regionAccessBits[24];
   192            UInt32 QWMTHRA;
   193            UInt32 AETCTL;
   194            UInt32 IER;
   195            UInt32 IERH;
   196            UInt32 QEER;
   197            UInt32 PaRAMs[1024];
   198        };
   199
   200        struct SubsystemContext {
   201            CpuSysRegs      cpuSysRegs;
   202            UnicacheConfig  configL1;
   203            UnicacheConfig  configL2;
   204            IntcConfig      configINTC;
   205            SyscConfig      configSYSC;
   206            AmmuConfig      configAMMU;
   207            EdmaConfig      configEDMA;
   208            Bool            tscRunning;
   209        };
   210
   211        /*!
   212         *  ======== resetFxn ========
   213         *  Startup reset function that checks if coming out of a processor reset
   214         *  due to Power_suspend().  If no, it will simply return.  If yes, it
   215         *  will restore CPU context, and return using a saved return pointer,
   216         *  warping back into the Power_suspend API.
   217         */
   218        Void resetFxn();
   219
   220        /*!
   221         *  ======== standby ========
   222         *  Function used for final CPU register save and transition to standby.
   223         */
   224        UInt standby(UInt32 *cpuRegs);
   225
   226    }
   227
   228    /*
   229     *  @(#) ti.sysbios.family.c64p.tesla; 1, 0, 0, 0,248; 6-15-2011 16:25:16; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   230
   231     */
   232


module ti.sysbios.family.c64p.tesla.Wugen

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Wugen.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c64p.tesla;
    38
    39    import xdc.runtime.Error;
    40
    41    import ti.sysbios.interfaces.IHwi;
    42    import ti.sysbios.family.c64p.Hwi;
    43
    44    /*!
    45     *  ======== Wugen ========
    46     *  Wugen Module
    47     *
    48     *  Using Wugen will install a Hwi beginHook that automatically clears
    49     *  the corresponding pending WUGEN IRQ bit for the interrupting event.
    50     *
    51     *  Currently this functionality is provided only for non-combined events.
    52     *
    53     *  Combined events must be cleared manually by the user's ISR.
    54     *
    55     *  Unconstrained Functions
    56     *  All functions
    57     *
    58     *  @p(html)
    59     *  <h3> Calling Context </h3>
    60     *  <table border="1" cellpadding="3">
    61     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    62     *
    63     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    64     *    <!--                                                                                                                 -->
    65     *    <tr><td> {@link #applyMasks}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #disableDma}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #disableEvent}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #enableDma}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #enableEvent}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #getMasks}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #ierToMasks} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td colspan="6"> Definitions: <br />
    73     *       <ul>
    74     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    75     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    76     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    77     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    78     *           <ul>
    79     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    80     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    81     *             <li> During main().</li>
    82     *             <li> During BIOS.startupFxns.</li>
    83     *           </ul>
    84     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    85     *           <ul>
    86     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    87     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    88     *           </ul>
    89     *       </ul>
    90     *    </td></tr>
    91     *
    92     *  </table>
    93     *  @p
    94     */
    95
    96    @ModuleStartup
    97
    98    module Wugen
    99    {
   100        /*!
   101         *  ======== applyMasks ========
   102         *  This function takes an array of 5 integers and applies the specified
   103         *  mask to the WUGEN interrupt mask registers. If the bit in the mask is
   104         *  enabled, the corresponding interrupt in the WUGEN will be blocked.
   105         *
   106         *  @param(mask)    array of five integers for applying to the WUGEN
   107         *                  interrupt mask register.
   108         *                  mask[0] consists of IRQ 0-31
   109         *                  mask[1] consists of IRQ 32-63
   110         *                  mask[2] consists of IRQ 64-71
   111         *                  mask[3] consists of DMA 0-31 requests
   112         *                  mask[4] consists of DMA 32-63 requests
   113         */
   114        Void applyMasks(UInt32 mask[]);
   115
   116        /*!
   117         *  ======== disableDma ========
   118         *  Disables the specified DMA source in the WUGEN
   119         *
   120         *  @param(dmaid)   the DMA id for a particular EDMA source.
   121         */
   122        Void disableDma(UInt dmaid);
   123
   124        /*!
   125         *  ======== disableEvent ========
   126         *  Disables the specified interrupt event source in the WUGEN
   127         *
   128         *  @param(eventid) the event number of an interrupt source
   129         */
   130        Void disableEvent(UInt eventid);
   131
   132        /*!
   133         *  ======== enableDma ========
   134         *  Enables the specified DMA source in the WUGEN
   135         *
   136         *  @param(dmaid)   the DMA id for a particular EDMA source.
   137         */
   138        Void enableDma(UInt dmaid);
   139
   140        /*!
   141         *  ======== enableEvent ========
   142         *  Enables the specified interrupt event source in the WUGEN
   143         *
   144         *  @param(eventid) the event number of an interrupt source
   145         */
   146        Void enableEvent(UInt eventid);
   147
   148        /*!
   149         *  ======== getMasks ========
   150         *  This function returns the WUGEN interrupt mask registers
   151         *
   152         *  @param(mask)    array of five integers used to return the WUGEN
   153         *                  interrupt mask registers
   154         *                  mask[0] consists of IRQ 0-31
   155         *                  mask[1] consists of IRQ 32-63
   156         *                  mask[2] consists of IRQ 64-71
   157         *                  mask[3] consists of DMA 0-31 requests
   158         *                  mask[4] consists of DMA 32-63 requests
   159         */
   160        Void getMasks(UInt32 mask[]);
   161
   162        /*!
   163         *  ======== ierToMasks ========
   164         *  Compute the WUGEN masks needed to allow the interrupts set in the IER
   165         *  register to propagate through the WUGEN.  This function does not enable
   166         *  external DMA requests.  You must set these explicitly to configure a
   167         *  DMA request as a wakeup event.
   168         *
   169         *  @param(mask)    array of five integers for returning WUGEN masks.
   170         *                  mask[0] consists of IRQ 0-31
   171         *                  mask[1] consists of IRQ 32-63
   172         *                  mask[2] consists of IRQ 64-71
   173         *                  mask[3] consists of DMA 0-31 requests
   174         *                  mask[4] consists of DMA 32-63 requests
   175         */
   176        Void ierToMasks(UInt32 mask[]);
   177
   178    internal:
   179
   180        /*!
   181         *  ======== hwiRegisterHook ========
   182         *  Hwi register hook to capture hook ID
   183         */
   184        Void hwiRegisterHook(Int id);
   185
   186        /*!
   187         *  ======== hwiCreateHook ========
   188         *  Hwi create hook that calculates corresponding irqNum
   189         */
   190        Void hwiCreateHook(IHwi.Handle hwi, Error.Block *eb);
   191
   192        /*!
   193         *  ======== hwiBeginHook ========
   194         * Hwi begin hook that clears wugen pending irqNum
   195         */
   196        Void hwiBeginHook(IHwi.Handle hwi);
   197
   198        /*!
   199         *  ======== intToIrq ========
   200         *  Convert interrupt number to IRQ number
   201         */
   202        UInt intToIrq(UInt intNum);
   203
   204        /*!
   205         *  ======== evtToIrq ========
   206         *  Convert eventId number to IRQ number
   207         */
   208        UInt evtToIrq(UInt intNum);
   209
   210        /*!
   211         *  ======== intToEvt ========
   212         *  Convert interrupt number to eventId
   213         */
   214        UInt intToEvt(UInt intNum);
   215
   216        struct Module_State {
   217            Int     hwiHookId;
   218        };
   219    }
   220    /*
   221     *  @(#) ti.sysbios.family.c64p.tesla; 1, 0, 0, 0,248; 6-15-2011 16:25:16; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   222
   223     */
   224


package ti.sysbios.family.c64p.ti81xx

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c64p.omap3430 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.family.c64p.ti81xx [2,0,0,0] {
    45        module TimerSupport;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.family.c64p.ti81xx; 2, 0, 0, 0,77; 6-15-2011 16:25:15; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


module ti.sysbios.family.c66.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c66;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    /*!
    43     *  ======== Cache ========
    44     *  Cache Module
    45     *
    46     *  This Cache module provides C66 family-specific implementations of the
    47     *  APIs defined in {@link ti.sysbios.interfaces.ICache ICache}.  It also
    48     *  provides additional C66 specific cache functions.
    49     *
    50     *  Unconstrained Functions
    51     *  All functions
    52     *
    53     *  @p(html)
    54     *  <h3> Calling Context </h3>
    55     *  <table border="1" cellpadding="3">
    56     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    57     *
    58     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    59     *    <!--                                                                                                                 -->
    60     *    <tr><td> {@link #disable}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    61     *    <tr><td> {@link #enable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    62     *    <tr><td> {@link #getMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    63     *    <tr><td> {@link #getMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    64     *    <tr><td> {@link #getSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #inv}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #invL1pAll*} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #setMar*}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #setMode*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #setSize*}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #wait}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #wb}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #wbAll*}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #wbInv}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #wbInvAll}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td colspan="6"> Definitions: <br />
    76     *       <ul>
    77     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    78     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    79     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    80     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    81     *           <ul>
    82     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    83     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    84     *             <li> During main().</li>
    85     *             <li> During BIOS.startupFxns.</li>
    86     *           </ul>
    87     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    88     *           <ul>
    89     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    90     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    91     *           </ul>
    92     *       <li> <b>*</b>: These APIs are intended to be made at initialization time, but are not restricted to this. </li>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99
   100    @ModuleStartup
   101
   102    module Cache inherits ti.sysbios.interfaces.ICache
   103    {
   104        // -------- Module Types --------
   105
   106        /*!
   107         *  ======== ModuleView ========
   108         *  @_nodoc
   109         */
   110        metaonly struct ModuleView {
   111            String  L1PCacheSize;
   112            String  L1PMode;
   113            String  L1DCacheSize;
   114            String  L1DMode;
   115            String  L2CacheSize;
   116            String  L2Mode;
   117        };
   118
   119        /*!
   120         *  ======== MarRegisterView ========
   121         *  @_nodoc
   122         */
   123        metaonly struct MarRegisterView {
   124            UInt    number;
   125            Ptr     addr;
   126            Ptr     startAddrRange;
   127            Ptr     endAddrRange;
   128            Bool    cacheable;
   129            Bool    writeThrough;
   130            Bool    externalCacheable;
   131            Bool    prefetchable;
   132        };
   133
   134        /*!
   135         *  ======== rovViewInfo ========
   136         *  @_nodoc
   137         */
   138        @Facet
   139        metaonly config ViewInfo.Instance rovViewInfo =
   140            ViewInfo.create({
   141                viewMap: [
   142                    ['Module',
   143                        {
   144                            type: ViewInfo.MODULE,
   145                            viewInitFxn: 'viewInitModule',
   146                            structName: 'ModuleView'
   147                        }
   148                    ],
   149                    ['EnableMARs',
   150                        {
   151                            type: xdc.rov.ViewInfo.MODULE_DATA,
   152                            viewInitFxn: 'viewInitMarRegisters',
   153                            structName: 'MarRegisterView'
   154                        }
   155                    ]
   156                ]
   157            });
   158
   159        /*! Lists of cache modes for L1/L2 caches */
   160        enum Mode {
   161            Mode_FREEZE,    /*! No new cache lines are allocated */
   162            Mode_BYPASS,    /*! All access result in long-distance access */
   163            Mode_NORMAL     /*! Normal operation of cache */
   164        };
   165
   166        /*! Level 1 cache size type definition. Can be used for both L1D & L1P */
   167        enum L1Size {
   168            L1Size_0K = 0,  /*! Amount of cache is 0K, Amount of SRAM is 32K */
   169            L1Size_4K = 1,  /*! Amount of cache is 4K, Amount of SRAM is 28K */
   170            L1Size_8K = 2,  /*! Amount of cache is 8K, Amount of SRAM is 24K */
   171            L1Size_16K = 3, /*! Amount of cache is 16K, Amount of SRAM is 16K */
   172            L1Size_32K = 4  /*! Amount of cache is 32K, Amount of SRAM is 0K */
   173        };
   174
   175        /*! Level 2 cache size type definition. */
   176        enum L2Size {
   177            L2Size_0K = 0,   /*! L2 is all SRAM */
   178            L2Size_32K = 1,  /*! Amount of cache is 32K */
   179            L2Size_64K = 2,  /*! Amount of cache is 64K */
   180            L2Size_128K = 3, /*! Amount of cache is 128K */
   181            L2Size_256K = 4, /*! Amount of cache is 256K */
   182            L2Size_512K = 5, /*! Amount of cache is 512K */
   183            L2Size_1024K = 6 /*! Amount of cache is 1024K */
   184        };
   185
   186        /*! MAR register setting type definition. */
   187        enum Mar {
   188            Mar_DISABLE = 0, /*! The Permit Copy bit of MAR register is disabled */
   189            Mar_ENABLE = 1   /*! The Permit Copy bit of MAR register is enabled */
   190        };
   191
   192        const UInt32 PC  = 1;     /*! Permit Caching                     */
   193        const UInt32 WTE = 2;     /*! Write through enabled              */
   194        const UInt32 PCX = 4;     /*! Permit caching in external cache   */
   195        const UInt32 PFX = 8;     /*! Prefetchable by external engines   */
   196
   197        /*! Structure for specifying all cache sizes. */
   198        struct Size {
   199            L1Size l1pSize;         /*! L1 Program cache size */
   200            L1Size l1dSize;         /*! L1 Data data size */
   201            L2Size l2Size;          /*! L2 cache size */
   202        };
   203
   204        /*! Default sizes of caches.
   205         * @_nodoc
   206         */
   207        config Size initSize = {
   208            l1pSize: L1Size_32K,
   209            l1dSize: L1Size_32K,
   210            l2Size: L2Size_0K
   211        };
   212
   213        /*! @_nodoc
   214         *  MAR 00 - 31 register bitmask. (for addresses 0x00000000 - 0x1FFFFFFF)
   215         *
   216         *  If undefined by the user, this parameter is configured to match the
   217         *  memory map of the platform.
   218         *  Each memory region defined in the platform will have all of its
   219         *  corresponding MAR bits set.
   220         *
   221         *  To override the default behavior you must initialize this parameter
   222         *  in your configuration script:
   223         *
   224         *  @p(code)
   225         *  // disable MAR bits for addresses 0x00000000 to 0x1FFFFFFF
   226         *  Cache.MAR0_31 = 0x00000000;
   227         *  @p
   228         */
   229        metaonly config UInt32 MAR0_31;
   230
   231        /*! @_nodoc
   232         *  MAR 32 - 63 register bitmask (for addresses 0x20000000 - 0x3FFFFFFF)
   233         *
   234         *  see {@link #MAR0_31} for more info
   235         */
   236        metaonly config UInt32 MAR32_63;
   237
   238        /*! @_nodoc
   239         *  MAR 64 - 95 register bitmask (for addresses 0x40000000 - 0x5FFFFFFF)
   240         *
   241         *  see {@link #MAR0_31} for more info
   242         */
   243        metaonly config UInt32 MAR64_95;
   244
   245        /*! @_nodoc
   246         *  MAR 96 - 127 register bitmask (for addresses 0x60000000 - 0x7FFFFFFF)
   247         *
   248         *  see {@link #MAR0_31} for more info
   249         */
   250        metaonly config UInt32 MAR96_127;
   251
   252        /*! @_nodoc
   253         *  MAR 128 - 159 register bitmask (for addresses 0x80000000 - 0x9FFFFFFF)
   254         *
   255         *  see {@link #MAR0_31} for more info
   256         */
   257        metaonly config UInt32 MAR128_159;
   258
   259        /*! @_nodoc
   260         *  MAR 160 - 191 register bitmask (for addresses 0xA0000000 - 0xBFFFFFFF)
   261         *
   262         *  see {@link #MAR0_31} for more info
   263         */
   264        metaonly config UInt32 MAR160_191;
   265
   266        /*! @_nodoc
   267         *  MAR 192 - 223 register bitmask (for addresses 0xC0000000 - 0xDFFFFFFF)
   268         *
   269         *  see {@link #MAR0_31} for more info
   270         */
   271        metaonly config UInt32 MAR192_223;
   272
   273        /*! @_nodoc
   274         *  MAR 224 - 255 register bitmask (for addresses 0xE0000000 - 0xFFFFFFFF)
   275         *
   276         *  see {@link #MAR0_31} for more info
   277         */
   278        metaonly config UInt32 MAR224_255;
   279
   280        /*! @_nodoc
   281         *
   282         *  This parameter is used to break up large blocks into multiple
   283         *  small blocks which are done atomically.  Each block of the
   284         *  specified size waits for the cache operation to finish before
   285         *  starting the next block.  Setting this size to 0, means the
   286         *  cache operations are not done atomically.
   287         */
   288        config UInt32 atomicBlockSize = 1024;
   289
   290        /*!
   291         *  ======== getMarMeta ========
   292         *  Gets the current MAR value for the specified base address
   293         *
   294         *  @param(baseAddr)  address for which MAR value is requested
   295         *
   296         *  @b(returns)       MAR value for specified address
   297         */
   298        metaonly UInt32 getMarMeta(Ptr baseAddr);
   299
   300        /*!
   301         *  ======== setMarMeta ========
   302         *  Set MAR register(s) that corresponds to the specified address range.
   303         *
   304         *  The 'pc' ("Permit Caching") field is enabled for all memory regions
   305         *  in the device platform.  Only set the fields of the Mar structure
   306         *  which need to be modified.  Any field not set retains its reset value.
   307         *
   308         *  @param(baseAddr)        start address for which to set MAR
   309         *  @param(byteSize)        size (in bytes) of memory block
   310         *  @param(value)           value for setting MAR register
   311         */
   312        metaonly Void setMarMeta(Ptr baseAddr, SizeT byteSize, UInt32 value);
   313
   314        /*!
   315         *  ======== disable ========
   316         *  Disables the 'type' cache(s)
   317         *
   318         *  Disabling of L2 cache is currently not supported.
   319         */
   320        @DirectCall
   321        override Void disable(Bits16 type);
   322
   323        /*!
   324         *  ======== getMode ========
   325         *  Get mode of a cache
   326         *
   327         *  @param(type)     bit mask of cache type
   328         *  @b(returns)      mode of specified level of cache
   329         */
   330        @DirectCall
   331        Mode getMode(Bits16 type);
   332
   333        /*!
   334         *  ======== setMode ========
   335         *  Set mode of a cache
   336         *
   337         *  @param(type)    bit mask of cache type
   338         *  @param(mode)    mode of cache
   339         *
   340         *  @b(returns)     previous mode of cache
   341         */
   342        @DirectCall
   343        Mode setMode(Bits16 type, Mode mode);
   344
   345        /*!
   346         *  ======== getSize ========
   347         *  Get sizes of all caches
   348         *
   349         *  @param(size)    pointer to structure of type Cache_Size
   350         */
   351        @DirectCall
   352        Void getSize(Size *size);
   353
   354        /*!
   355         *  ======== setSize ========
   356         *  Set sizes of all caches
   357         *
   358         *  @param(size)    pointer to structure of type Cache_Size
   359         */
   360        @DirectCall
   361        Void setSize(Size *size);
   362
   363        /*!
   364         *  ======== getMar ========
   365         *  Gets the MAR register for the specified base address
   366         *
   367         *  @param(baseAddr)  address for which MAR is requested
   368         *
   369         *  @b(returns)       value of MAR register
   370         */
   371        @DirectCall
   372        UInt32 getMar(Ptr baseAddr);
   373
   374        /*!
   375         *  ======== setMar ========
   376         *  Set MAR register(s) that corresponds to the specified address range.
   377         *
   378         *  All cached entries in L1 and L2 are written back and invalidated.
   379         *
   380         *  @param(baseAddr)        start address for which to set MAR
   381         *  @param(byteSize)        size (in bytes) of memory block
   382         *  @param(value)           value for setting MAR register
   383         */
   384        @DirectCall
   385        Void setMar(Ptr baseAddr, SizeT byteSize, UInt32 value);
   386
   387        /*!
   388         *  ======== invL1pAll ========
   389         *  Invalidate all of L1 Program cache
   390         *
   391         *  Performs a global invalidate of L1P cache.
   392         *  Polls the L1P invalidate register until done.
   393         */
   394        @DirectCall
   395        Void invL1pAll();
   396
   397        /*!
   398         *  ======== wbAll ========
   399         *  Write back all caches
   400         *
   401         *  Perform a global write back.  There is no effect on L1P cache.
   402         *  All cache lines are left valid in L1D cache and the data in L1D cache
   403         *  is written back to L2 or external.  All cache lines are left valid in
   404         *  L2 cache and the data in L2 cache is written back to external.
   405         */
   406        @DirectCall
   407        override Void wbAll();
   408
   409        /*!
   410         *  ======== wbInvAll ========
   411         *  Write back invalidate all caches
   412         *
   413         *  Performs a global write back and invalidate.  All cache lines are
   414         *  invalidated in L1P cache.  All cache lines are written back to L2 or
   415         *  external and then invalidated in L1D cache.  All cache lines are
   416         *  written back to external and then invalidated in L2 cache.
   417         */
   418        @DirectCall
   419        override Void wbInvAll();
   420
   421
   422    internal:
   423
   424        /*!
   425         *  ======== invPrefetchBuffer ========
   426         *  Invalidate the prefetch buffer
   427         */
   428        Void invPrefetchBuffer();
   429
   430        /* cache configuration registers */
   431        const UInt32 L2CFG  = 0x01840000;
   432        const UInt32 L1PCFG = 0x01840020;
   433        const UInt32 L1PCC  = 0x01840024;
   434        const UInt32 L1DCFG = 0x01840040;
   435        const UInt32 L1DCC  = 0x01840044;
   436        const UInt32 MAR    = 0x01848000;
   437
   438        /* For setting the MAR registers at startup */
   439        config UInt32 marvalues[256];
   440    }
   441    /*
   442     *  @(#) ti.sysbios.family.c66; 2, 0, 0, 0,110; 6-15-2011 16:25:18; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   443
   444     */
   445


package ti.sysbios.family.c66

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.family.c66 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     *  The link below provides SYS/BIOS C6x register usage information:
    44     *
    45     *      {@link ./../c62/doc-files/c6xregconv.html SYS/BIOS C6x Register Usage}
    46     *
    47     */
    48    package ti.sysbios.family.c66 [2,0,0,0] {
    49        module Cache;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.c66; 2, 0, 0, 0,110; 6-15-2011 16:25:18; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.c66.tci66xx.CpIntc

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== CpIntc.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c66.tci66xx;
    39
    40    import xdc.runtime.Error;
    41
    42    /*!
    43     *  ======== CpIntc ========
    44     *  Common Platform Interrupt Controller Manager
    45     *
    46     *  This module manages the CP_INTC hardware.  This module supports enabling
    47     *  and disabling of both system and host interrupts.  This module also
    48     *  supports mapping system interrupts to host interrupts and host interrupts
    49     *  to Hwis or to the EventCombiner.  These functionality are supported
    50     *  statically and during runtime for CP_INTCs connected to the GEM interrupt
    51     *  controller but only during runtime for other CP_INTCs.  There is a dispatch
    52     *  function for handling GEM hardware interrupts triggered by a system
    53     *  interrupt.  The Global Enable Register is enabled by default in the module
    54     *  startup function.
    55     *
    56     *  System interrupts are those interrupts generated by a hardware module
    57     *  in the system.  These interrupts are inputs into CP_INTC.
    58     *  Host interrupts are the output interrupts of CP_INTC.
    59     *  There is a one-to-one mapping between channels and host interrupts
    60     *  therefore, the term "host interrupt" is also used for channels.
    61     *
    62     *  This modules does not support prioritization, nesting, and vectorization.
    63     */
    64
    65    @ModuleStartup
    66
    67    module CpIntc
    68    {
    69        /*!
    70         *  ======== SysIntsView ========
    71         *  @_nodoc
    72         */
    73        metaonly struct SysIntsView {
    74            UInt         systemInt ;
    75            UInt8        hostInt;
    76            String       fxn;
    77            String       arg;
    78            Bool         enabled;
    79        };
    80
    81        /*!
    82         *  ======== rovViewInfo ========
    83         *  @_nodoc
    84         */
    85        @Facet
    86        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
    87            xdc.rov.ViewInfo.create({
    88                viewMap: [
    89                    ['SysInts',
    90                        {
    91                            type: xdc.rov.ViewInfo.MODULE_DATA,
    92                            viewInitFxn: 'viewInitSystemInts',
    93                            structName: 'SysIntsView'
    94                        }
    95                    ]
    96                ]
    97            });
    98
    99        /*! CpIntc dispatcher function type definition. */
   100        typedef Void (*FuncPtr)(UArg);
   101
   102        /*!
   103         *  Common Platform Interrupt Controller.
   104         */
   105        struct RegisterMap {
   106            UInt32 REV;         /*! 0x00 Revision Register */
   107            UInt32 CR;          /*! 0x04 Control Register */
   108            UInt32 RES_08;      /*! 0x08 reserved */
   109            UInt32 HCR;         /*! 0x0C Host Control Register */
   110            UInt32 GER;         /*! 0x10 Global Enable Register */
   111            UInt32 RES_14;      /*! 0x14 reserved */
   112            UInt32 RES_18;      /*! 0x18 reserved */
   113            UInt32 GNLR;        /*! 0x1C Global Nesting Level Register */
   114            UInt32 SISR;        /*! 0x20 Status Index Set Register */
   115            UInt32 SICR;        /*! 0x24 Status Index Clear Register */
   116            UInt32 EISR;        /*! 0x28 Enable Index Set Register */
   117            UInt32 EICR;        /*! 0x2C Enable Index Clear Register */
   118            UInt32 GWER;        /*! 0x30 Global Wakeup Enable Register */
   119            UInt32 HIEISR;      /*! 0x34 Host Int Enable Index Set Register */
   120            UInt32 HIDISR;      /*! 0x38 Host Int Disable Index Set Register */
   121            UInt32 RES_3C;      /*! 0x3C reserved */
   122            UInt32 PPR;         /*! 0x40 Pacer Prescale Register */
   123            UInt32 RES_44;      /*! 0x44 reserved */
   124            UInt32 RES_48;      /*! 0x48 reserved */
   125            UInt32 RES_4C;      /*! 0x4C reserved */
   126            Ptr   *VBR;         /*! 0x50 Vector Base Register */
   127            UInt32 VSR;         /*! 0x54 Vector Size Register */
   128            Ptr    VNR;         /*! 0x58 Vector Null Register */
   129            UInt32 RES_5C[9];   /*! 0x5C-0x7C reserved */
   130            Int32  GPIR;        /*! 0x80 Global Prioritized Index Register */
   131            Ptr   *GPVR;        /*! 0x84 Global Prioritized Vector Register */
   132            UInt32 RES_88;      /*! 0x88 reserved */
   133            UInt32 RES_8C;      /*! 0x8C reserved */
   134            UInt32 GSIER;       /*! 0x90 Global Secure Interrupt Enable Register */
   135            UInt32 SPIR;        /*! 0x94 Secure Prioritized Index Register */
   136            UInt32 RES_98[26];  /*! 0x98-0xFC reserved */
   137            UInt32 PPMR[64];    /*! 0x100-0x1FC Pacer Parameter/Map Registers */
   138            UInt32 SRSR[32];    /*! 0x200-0x27C Status Raw/Set Registers */
   139            UInt32 SECR[32];    /*! 0x280-0x2FC Status Enabled/Clear Registers */
   140            UInt32 ESR[32];     /*! 0x300-0x37C Enable Set Registers */
   141            UInt32 ECR[32];     /*! 0x380-0x3FC Enable Clear Registers */
   142            UInt8  CMR[1024];   /*! 0x400-0x7FC Channel Map Registers */
   143            UInt8  HIMR[256];   /*! 0x800-0x8FC Host Interrupt Map Registers */
   144            UInt32 HIPIR[256];  /*! 0x900-0xCFC Host Interrupt Pri Index Registers */
   145            UInt32 PR[32];      /*! 0xD00-0xD7C Polarity Registers */
   146            UInt32 TR[32];      /*! 0xD80-0xDFC Type Registers */
   147            UInt32 WER[64];     /*! 0xE00-0xEFC Wakeup Enable Registers */
   148            UInt32 DSR[64];     /*! 0xF00-0xFFC Debug Select Registers */
   149            UInt32 SER[32];     /*! 0x1000-0x107C Secure Enable Registers */
   150            UInt32 SDR[32];     /*! 0x1080-0x10FC Secure Disable Registers */
   151            UInt32 HINLR[256];  /*! 0x1100-0x14FC Host Interrupt Nesting Level Registers */
   152            UInt32 HIER[8];     /*! 0x1500-0x151F Host Interrupt Enable Registers */
   153            UInt32 RES1520[56]; /*! 0x1520-0x15fC Reserved */
   154            Ptr   *HIPVR[256];  /*! 0x1600-0x19fC Host Interrupt Prioritized Vector */
   155            UInt32 RES1A00[384];/*! 0x1A00-0x1FFC Reserved */
   156        };
   157
   158        /*!
   159         *  System Interrupt Object.
   160         */
   161        metaonly struct SysIntObj {
   162            FuncPtr fxn;            // function to call when this event occurs.
   163            UArg    arg;            // arg for function.
   164            UInt8   hostInt;        // the host interrupt.
   165            Bool    enable;         // enable the system interrupt.
   166        };
   167
   168        /*!
   169         *  Error raised when an unplug system interrupt is executed.
   170         */
   171        config Error.Id E_unpluggedSysInt = {
   172            msg: "E_unpluggedSysInt: System Interrupt# %d is unplugged"
   173        };
   174
   175        /*!
   176         *  ======== sysInts ========
   177         *  Use for configuring the system interrupts.
   178         *
   179         *  During static configuration this array can be used to configure
   180         *  the function to execute when a system interrupt is triggered,
   181         *  the arg to the function, the host interrupt to which the system
   182         *  interrupt is mapped too, and whether to enable the system interrupt.
   183         */
   184        metaonly config SysIntObj sysInts[];
   185
   186        /*!
   187         *  ======== getEventIdMeta ========
   188         *  Returns the GEM event id associated with the host interrupt
   189         *
   190         *  If no event id is associated with the host interrupt, the value
   191         *  -1 will be returned.
   192         *
   193         *  @param(hostInt)  host interrupt number
   194         */
   195        metaonly Int getEventIdMeta(UInt hostInt);
   196
   197        /*!
   198         *  ======== mapHostIntToEventCombinerMeta ========
   199         *  Maps the host interrupt to the Event Combiner.
   200         *
   201         *  The GEM event corresponding to the 'hostInt' in the Event Combiner
   202         *  will be unmask but the event group will not be dispatched.
   203         *  The Event Combiner function for this event will be set to the
   204         *  dispatch function and argument set to 'hostInt'.
   205         *  The event group must be dispatched from the Event Combiner Module.
   206         *
   207         *  @param(hostInt) host interrupt number
   208         */
   209        metaonly Void mapHostIntToEventCombinerMeta(UInt hostInt);
   210
   211        /*!
   212         *  ======== mapHostIntToHwiMeta ========
   213         *  Maps the host interrupt to a Hwi.
   214         *
   215         *  A Hwi object will be created with the 'hwiNum', the function
   216         *  set as the dispatch function and argument set to 'hostInt'.
   217         *
   218         *  @param(hostInt) host interrupt number
   219         *  @param(hwiNum)  Hwi number
   220         */
   221        metaonly Void mapHostIntToHwiMeta(UInt hostInt, UInt hwiNum);
   222
   223        /*!
   224         *  ======== clearSystInt ========
   225         *  Clears the system interrupt.
   226         *
   227         *  Writes the system interrupt number to the System Interrupt
   228         *  Status Indexed Clear Register.
   229         *
   230         *  @param(id)      Cp_Intc number
   231         *  @param(sysInt)  system interrupt number
   232         */
   233        Void clearSysInt(UInt id, UInt sysInt);
   234
   235        /*!
   236         *  ======== disableAllHostInts ========
   237         *  Disables all host interrupts.
   238         *
   239         *  Writes a 0 to the Global Enable Register.  It does not
   240         *  override the individual host interrupt enable/disable bits.
   241         *
   242         *  @param(id)      Cp_Intc number
   243         */
   244        Void disableAllHostInts(UInt id);
   245
   246        /*!
   247         *  ======== disableHostInt ========
   248         *  Disables the host interrupts.
   249         *
   250         *  Writes the host interrupt number to the Host Interrupt
   251         *  Enable Index Clear Register.
   252         *
   253         *  @param(id)      Cp_Intc number
   254         *  @param(hostInt) host interrupt number
   255         */
   256        Void disableHostInt(UInt id, UInt hostInt);
   257
   258        /*!
   259         *  ======== disableSysInt ========
   260         *  Disables the system interrupt.
   261         *
   262         *  Writes the system interrupt number to the System Interrupt
   263         *  Enable Indexed Clear Register.
   264         *
   265         *  @param(id)      Cp_Intc number
   266         *  @param(sysInt)  system interrupt number
   267         */
   268        Void disableSysInt(UInt id, UInt sysInt);
   269
   270        /*!
   271         *  ======== dispatch ========
   272         *  The Interrupt service routine handler for CP_INTC events.
   273         *
   274         *  It is used internally, but can also be used by the user.
   275         *
   276         *  @param(hostInt)  host interrupt number
   277         */
   278        Void dispatch(UInt hostInt);
   279
   280        /*!
   281         *  ======== dispatchPlug ========
   282         *  Configures a CpIntc ISR dispatch entry.
   283         *
   284         *  Plugs the function and argument for the specified system interrupt.
   285         *  Also enables the system interrupt if 'unmask' is set to 'true'.
   286         *  Function does not map the system interrupt to a Hwi interrupt.
   287         *
   288         *  @param(sysInt)  system interrupt number
   289         *  @param(fxn)     function
   290         *  @param(arg)     argument to function
   291         *  @param(unmask)  bool to unmask interrupt
   292         */
   293        Void dispatchPlug(UInt sysInt, FuncPtr fxn, UArg arg, Bool unmask);
   294
   295        /*!
   296         *  ======== enableAllHostInts ========
   297         *  Enables all host interrupts.
   298         *
   299         *  Writes a 1 to the Global Enable Register.  It does not
   300         *  override the individual host interrupt enable/disable bits.
   301         *
   302         *  @param(id)      Cp_Intc number
   303         */
   304        Void enableAllHostInts(UInt id);
   305
   306        /*!
   307         *  ======== enableHostInt ========
   308         *  Enables the host interrupt.
   309         *
   310         *  Writes the host interrupt number to the Host Interrupt
   311         *  Enable Indexed Set Register.
   312         *
   313         *  @param(id)      Cp_Intc number
   314         *  @param(hostInt)  host interrupt number
   315         */
   316        Void enableHostInt(UInt id, UInt hostInt);
   317
   318        /*!
   319         *  ======== enableSysInt ========
   320         *  Enables the system interrupt.
   321         *
   322         *  Writes the system interrupt number to the System Interrupt
   323         *  Enable Indexed Set Register.
   324         *
   325         *  @param(id)      Cp_Intc number
   326         *  @param(sysInt)  system interrupt number
   327         */
   328        Void enableSysInt(UInt id, UInt sysInt);
   329
   330        /*!
   331         *  ======== getEventId ========
   332         *  Returns the event id associated with the host interrupt
   333         *
   334         *  @param(hostInt)  host interrupt number
   335         */
   336        Int getEventId(UInt hostInt);
   337
   338        /*!
   339         *  ======== mapSysIntToHostInt ========
   340         *  Maps a system interrupt to a host interrupt.
   341         *
   342         *  Writes the Channel Map Register to map a system interrupt to a
   343         *  channel.  There is a 1 to 1 mapping between channels and
   344         *  host interrupts.
   345         *
   346         *  @param(id)      Cp_Intc number
   347         *  @param(sysInt)  system interrupt number
   348         *  @param(hostInt) host interrupt number
   349         */
   350        Void mapSysIntToHostInt(UInt id, UInt sysInt, UInt hostInt);
   351
   352        /*!
   353         *  ======== postSysInt ========
   354         *  Triggers the system interrupt.
   355         *
   356         *  Writes the system interrupt number to the System Interrupt
   357         *  Status Index Set Register. Used for diagnostic and test purposes
   358         *  only.
   359         *
   360         *  @param(id)      Cp_Intc number
   361         *  @param(sysInt)  system interrupt number
   362         */
   363        Void postSysInt(UInt id, UInt sysInt);
   364
   365        /*!
   366         *  @_nodoc
   367         *  ======== unused ========
   368         *  Unused exists simply to map a call in the Event Combiner dispatcher
   369         *  calling context to the System_exit calling context (casts UArg to Int)
   370         */
   371        Void unused(UArg arg);
   372
   373    internal:
   374
   375        /* Host interrupt object */
   376        metaonly struct HostIntObj {
   377            Int  hwiNum;            // Hwi number associated with host interrupt.
   378            Bool useEventCombiner;  // set to 'true' to use EventCombiner.
   379        };
   380
   381        /* use for mapping host interrupts to Hwi or Event Combiner */
   382        metaonly config HostIntObj hostInts[];
   383
   384        /* the base address of the intc controller */
   385        metaonly config UInt32 baseAddr;
   386
   387        /* the number of systerm interrupts */
   388        config UInt32 numSysInts;
   389
   390        /* the number of system interrupt status registers */
   391        config Int numStatusRegs;
   392
   393        /* for mapping statically configured system interrupt to host interrupt */
   394        config UInt8 sysIntToHostInt[];
   395
   396        /* for mapping host interrups to GEM event id */
   397        config UInt8 hostIntToEventId[];
   398
   399        struct DispatchTabElem {
   400            FuncPtr fxn;            // function to execute
   401            UArg arg;               // arg for function
   402        };
   403
   404        struct Module_State {
   405            volatile RegisterMap *controller[];// Holds CP_INTC address on device.
   406            Bits32          initSIER[];        // Initial Sys Int Enable Reg values
   407            UInt8           hostIntToSysInt[]; // Sys Int associated with Host Int.
   408            DispatchTabElem dispatchTab[];     // Dispatcher Table.
   409        };
   410    }
   411    /*
   412     *  @(#) ti.sysbios.family.c66.tci66xx; 2, 0, 0, 0,102; 6-15-2011 16:25:19; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   413
   414     */
   415


package ti.sysbios.family.c66.tci66xx

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.family.c66.tci66xx ========
    39     */
    40    package ti.sysbios.family.c66.tci66xx [2,0,0,0] {
    41        module CpIntc;
    42    }
    43    /*
    44     *  @(#) ti.sysbios.family.c66.tci66xx; 2, 0, 0, 0,102; 6-15-2011 16:25:20; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    45
    46     */
    47


module ti.sysbios.family.c67p.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c67p;
    38
    39    /*!
    40     *  ======== Cache ========
    41     *  Cache Module
    42     *
    43     *  Unconstrained Functions
    44     *  All functions
    45     *
    46     *  @p(html)
    47     *  <h3> Calling Context </h3>
    48     *  <table border="1" cellpadding="3">
    49     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    50     *
    51     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    52     *    <!--                                                                                                                 -->
    53     *    <tr><td> {@link #disable}    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    54     *    <tr><td> {@link #enable}     </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    55     *    <tr><td> {@link #inv}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    56     *    <tr><td> {@link #wait}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    57     *    <tr><td> {@link #wb}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    58     *    <tr><td> {@link #wbInv}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    59     *    <tr><td colspan="6"> Definitions: <br />
    60     *       <ul>
    61     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    62     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    63     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    64     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    65     *           <ul>
    66     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    67     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    68     *             <li> During main().</li>
    69     *             <li> During BIOS.startupFxns.</li>
    70     *           </ul>
    71     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    72     *           <ul>
    73     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    74     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    75     *           </ul>
    76     *       </ul>
    77     *    </td></tr>
    78     *
    79     *  </table>
    80     *  @p
    81     */
    82
    83    @ModuleStartup
    84
    85    module Cache inherits ti.sysbios.interfaces.ICache
    86    {
    87        /*!
    88         *  Enable the cache? The Default is true.
    89         */
    90        config Bool enableCache = true;
    91    }
    92    /*
    93     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:24; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    94
    95     */
    96


module ti.sysbios.family.c67p.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.c67p;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43    import xdc.runtime.Error;
    44
    45    /*!
    46     *  ======== Hwi ========
    47     *  C67+ Hardware Interrupt Support Module.
    48     *
    49     *  This Hwi module provides C67+ family-specific implementations of the
    50     *  APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    51     *
    52     *  Additional C67+ device-specific APIs are also provided.
    53     *
    54     *  @a(NOTE)
    55     *  In this Hwi module implementation, the instance config parameter value
    56     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    57     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    58     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    59     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    60     *  silently converted to {@link #MaskingOption_SELF}.
    61     *
    62     *  @p(html)
    63     *  <h3> Calling Context </h3>
    64     *  <table border="1" cellpadding="3">
    65     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    66     *
    67     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    68     *    <!--                                                                                                                 -->
    69     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #disableIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #eventMap}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    81     *    <tr><td> {@link #restoreIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    83     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td colspan="6"> Definitions: <br />
    91     *       <ul>
    92     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    93     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    94     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    95     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    96     *           <ul>
    97     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    98     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    99     *             <li> During main().</li>
   100     *             <li> During BIOS.startupFxns.</li>
   101     *           </ul>
   102     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   103     *           <ul>
   104     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   105     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   106     *           </ul>
   107     *       </ul>
   108     *    </td></tr>
   109     *
   110     *  </table>
   111     *  @p
   112     */
   113
   114    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   115    @ModuleStartup         /* generate a call to Hwi_init at startup */
   116
   117    module Hwi inherits ti.sysbios.interfaces.IHwi
   118    {
   119        // -------- Module Constants --------
   120
   121        /*! C64 supports 16 interrupts. */
   122        const Int NUM_INTERRUPTS = 16;
   123
   124        // -------- Module Types --------
   125
   126        /*! @_nodoc @_nodoc Hwi plug function type definition. */
   127        typedef Void (*PlugFuncPtr)(void);
   128
   129        /*!
   130         *  ======== BasicView ========
   131         *  @_nodoc
   132         */
   133        metaonly struct BasicView {
   134            Ptr         halHwiHandle;
   135            String      label;
   136            UInt        intNum;
   137            String      fxn;
   138            UArg        arg;           // Argument to Hwi function.
   139            Ptr         irp;
   140            UInt        eventId;
   141            String      disableMask;   // Interrupts to mask during ISR.
   142            String      restoreMask;   // Interrupts to restore after ISR.
   143        };
   144
   145        /*!
   146         *  ======== ModuleView ========
   147         *  @_nodoc
   148         */
   149        metaonly struct ModuleView {
   150            String      options[4];
   151            SizeT       hwiStackPeak;
   152            SizeT       hwiStackSize;
   153            Ptr         hwiStackBase;
   154        };
   155
   156        /*!
   157         *  ======== rovViewInfo ========
   158         *  @_nodoc
   159         */
   160        @Facet
   161        metaonly config ViewInfo.Instance rovViewInfo =
   162            ViewInfo.create({
   163                viewMap: [
   164                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   165                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   166                ]
   167            });
   168
   169        // -------- Module Parameters --------
   170
   171        /*!
   172         *  non-dispatched interrupt object.
   173         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   174         */
   175        metaonly struct NonDispatchedInterrupt {
   176            Int             intNum;
   177            PlugFuncPtr     fxn;            /*! "Hwi_plug'd" ISR function. */
   178            Bool            enableInt;
   179            Int             eventId;
   180        };
   181
   182        /*!
   183         *  non-dispatched interrupt array.
   184         *  provided so that XGCONF users can easily plug non-dispatched interrupts
   185         */
   186        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   187
   188        /*!
   189         *  Alternate reset vector address. Default is undefined.
   190         *
   191         *  if initialized by the user then an additional reset vector
   192         *  is created and placed in the ".resetVector" section.
   193         *  To place the .resetVector section into a specific memory section,
   194         *  add the following command to your config script:
   195         *  @p(code)
   196         *  Program.sectMap[".resetVector"] = YourMemorySection;
   197         *  @p
   198         */
   199        metaonly config Ptr resetVectorAddress;
   200
   201        /*!
   202         *  Error raised when Hwi is already defined
   203         */
   204        config Error.Id E_alreadyDefined = {
   205            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   206        };
   207
   208        /*!
   209         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   210         */
   211        config Log.Event LM_begin = {
   212            mask: Diags.USER1 | Diags.USER2,
   213            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   214        };
   215
   216        /*!
   217         *  Issued just after return from Hwi function (with interrupts disabled)
   218         */
   219        config Log.Event LD_end = {
   220            mask: Diags.USER2,
   221            msg: "LD_end: hwi: 0x%x"
   222        };
   223
   224        // -------- Module Functions --------
   225
   226        /*!
   227         *  ======== disable ========
   228         */
   229        @Macro
   230        override UInt disable();
   231
   232        /*!
   233         *  ======== enable ========
   234         */
   235        @Macro
   236        override UInt enable();
   237
   238        /*!
   239         *  ======== restore ========
   240         */
   241        @Macro
   242        override Void restore(UInt key);
   243
   244        /*!
   245         *  ======== inUseMeta ========
   246         *  @_nodoc
   247         *  Check for Hwi already in use.
   248         *  For internal SYS/BIOS use only.
   249         *  Should be called prior to any internal Hwi.create().
   250         *
   251         *  @param(intNum)  interrupt number
   252         */
   253        metaonly Bool inUseMeta(UInt intNum);
   254
   255        /*!
   256         *  ======== eventMap ========
   257         *  Map Event to Interrupt
   258         *
   259         *  Function maps an event to an interrupt vector so that the
   260         *  event will be the source of the interrupt of the vector.
   261         *
   262         *  @p(code)
   263         *      // Maps GEM event #65 as the interrupt source of int vector #7
   264         *      Hwi_eventMap(7, 65);
   265         *  @p
   266         *
   267         *  @param(intNum)  interrupt number
   268         *  @param(eventId) event ID
   269         */
   270        @DirectCall
   271        Void eventMap(Int intNum, Int eventId);
   272
   273        /*!
   274         *  ======== eventMapMeta ========
   275         *  Statically map Event to Interrupt
   276         *
   277         *  Function maps an event to an interrupt number so that the
   278         *  event will be the source of the interrupt of the vector.
   279         *
   280         *  @p(code)
   281         *      // Maps GEM event #65 as the interrupt source of int vector #7
   282         *      Hwi.eventMapMeta(7, 65);
   283         *  @p
   284         *
   285         *  @param(intNum)      interrupt number
   286         *  @param(eventId)     pointer to ISR function
   287         */
   288        metaonly Void eventMapMeta(Int intNum, Int eventId);
   289
   290        /*!
   291         *  @_nodoc
   292         *  ======== plug ========
   293         *  Plug an interrupt vector with an ISR address.
   294         *
   295         *  Hwi_plug writes an Interrupt Service Fetch Packet (ISFP) into the
   296         *  Interrupt Service Table (IST), at the address corresponding to intNum
   297         *  The op-codes written in the ISFP create a branch to the function
   298         *  entry  point specified by fxn:
   299         *
   300         *  @p(code)
   301         *          stw     b0, *SP--[1]
   302         *          mvk     fxn, b0
   303         *          mvkh    fxn, b0
   304         *          b       b0
   305         *          ldw     *++SP[1],b0
   306         *          nop     4
   307         *  @p
   308         *
   309         *  Hwi_plug hooks up the specified function as the branch target of a
   310         *  hardware interrupt (fielded by the CPU) at the vector address
   311         *  specified in intNum. Hwi_plug does not enable the interrupt.
   312         *  Use Hwi_enableIER to enable specific interrupts.
   313         *
   314         *  For internal SYS/BIOS use only.
   315         *
   316         *  Constraints and Calling Context
   317         *  o vecid must be a valid interrupt ID in the range of 0-15.
   318         *
   319         *  @param(intNum)  interrupt number
   320         *  @param(fxn)     pointer to ISR function
   321         */
   322        @DirectCall
   323        Void plug(UInt intNum, PlugFuncPtr fxn);
   324
   325        /*!
   326         *  ======== plugMeta ========
   327         *  Statically plug an interrupt vector with an ISR address.
   328         *
   329         *  @param(intNum)  interrupt number
   330         *  @param(fxn)     pointer to ISR function
   331         */
   332        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   333
   334        /*!
   335         *  ======== getHandle ========
   336         *  Returns Hwi_handle associated with intNum
   337         *
   338         *  @param(intNum)  interrupt number
   339         *  @b(returns)     handle associated with intNum
   340         */
   341        @DirectCall
   342        Handle getHandle(UInt intNum);
   343
   344        /*!
   345         *  ======== disableIER ========
   346         *  Disable certain maskable interrupts.
   347         *
   348         *  Atomically disables specific interrupts by clearing the bits
   349         *  specified by mask in the Interrupt Enable Register (IER).
   350         *
   351         *  The IER bits to be cleared should be set to 1 in the mask.
   352         *
   353         *  @param(mask)    bitmask of interrupts to disable
   354         *  @b(returns)     previous IER settings bitmask
   355         */
   356        @DirectCall
   357        Bits16 disableIER(Bits16 mask);
   358
   359        /*!
   360         *  ======== enableIER ========
   361         *  Enable certain maskable interrupts.
   362         *
   363         *  Atomically enables specific interrupts by setting the bits
   364         *  specified by mask in the Interrupt Enable Register (IER).
   365         *
   366         *  The IER bits to be set should be set to 1 in the mask.
   367         *
   368         *  @param(mask)    bitmask of interrupts to enable
   369         *  @b(returns)     previous IER settings bitmask
   370         */
   371        @DirectCall
   372        Bits16 enableIER(Bits16 mask);
   373
   374        /*!
   375         *  ======== restoreIER ========
   376         *  Restore maskable interrupts to the state they were in
   377         *  when either disableIER() or enableIER() was called.
   378         *
   379         *  Atomically writes the given mask to the IER register. Typically used
   380         *  to restore the IER register to the state returned from a call to
   381         *  either {@link #disableIER()} or {@link #enableIER()}.
   382         *
   383         *  @param(mask)    bitmask of interrupts to restore
   384         *  @b(returns)     previous IER settings bitmask
   385         */
   386        @DirectCall
   387        Bits16 restoreIER(Bits16 mask);
   388
   389    instance:
   390
   391        /*!
   392         *  Dispatcher auto-nesting interrupt disable mask.
   393         *
   394         *  When the dispatcher's auto interrupt nesting support feature
   395         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   396         *  this mask defines which IER bits are disabled prior to invoking
   397         *  the user's ISR function with GIE = 1.
   398         *
   399         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   400         *  prior to invoking the ISR.
   401         *
   402         *  The value of this mask is normally auto-calculated based on the
   403         *  value of the maskSetting. However, manual setting of this
   404         *  mask is enabled by setting the maskSetting to
   405         *  {@link #MaskingOption MaskingOption_BITMASK}.
   406         *
   407         *  The default value is derived from the
   408         *  {@link #MaskingOption MaskingOption_SELF}
   409         *  maskSetting.
   410         */
   411        config Bits16 disableMask = 0;
   412
   413        /*!
   414         *  Dispatcher auto-nesting interrupt restore mask.
   415         *
   416         *  When the dispatcher's auto interrupt nesting support feature
   417         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   418         *  this mask defines which IER bits are restored to their previous
   419         *  setting upon return from the user's ISR function.
   420         *
   421         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   422         *
   423         *  The value of this mask is normally auto-calculated based on the
   424         *  value of the maskSetting. However, manual setting of this
   425         *  mask is enabled by setting the maskSetting to
   426         *  {@link #MaskingOption MaskingOption_BITMASK}.
   427         *
   428         *  The default value is derived from the
   429         *  {@link #MaskingOption MaskingOption_SELF}
   430         *  maskSetting.
   431         */
   432        config Bits16 restoreMask = 0;
   433
   434        /*!
   435         *  Interrupt priority. Not supported on this target.
   436         */
   437        override config Int priority = 0;
   438
   439        /*!
   440         *  ======== reconfig ========
   441         *  Reconfigure a dispatched interrupt.
   442         */
   443        @DirectCall
   444        Void reconfig(FuncPtr fxn, const Params *params);
   445
   446    internal:   /* not for client use */
   447
   448        /*
   449         * Swi and Task module function pointers.
   450         * Used to decouple Hwi from Swi and Task when
   451         * dispatcherSwiSupport or
   452         * dispatcherTaskSupport is false.
   453         */
   454        config UInt (*swiDisable)();
   455        config Void (*swiRestoreHwi)(UInt);
   456        config UInt (*taskDisable)();
   457        config Void (*taskRestoreHwi)(UInt);
   458
   459        /*
   460         *  ======== getIsrStackAddress ========
   461         *  Returns initial isrStack address.
   462         *  This API was developed solely for the Exception module
   463         *  to allow removal of the Hwi_link.xdt template definition
   464         *  of ti_sysbios_family_c64p_Hwi_isrStack which was not
   465         *  ROM-able
   466         */
   467        Char *getIsrStackAddress();
   468
   469        /*
   470         *  ======== getEvent ========
   471         *  Returns associated event num from INTMUX
   472         */
   473        UInt getEvent(UInt intNum);
   474
   475        /* Interrupt Dispatcher */
   476        Void dispatchC(Int intNum);
   477
   478        /* unPlugged interrupt handler */
   479        Void unPluggedInterrupt();
   480
   481        /*!
   482         *  const array to hold all HookSet objects.
   483         */
   484        config HookSet hooks[length] = [];
   485
   486        /*! Meta World Only Hwi Configuration Object. */
   487        metaonly struct InterruptObj {
   488            String name;            /* symbol used for vector table entry */
   489            Bool used;              /* Interrupt already defined? */
   490            Bool useDispatcher;     /* Should dispatcher handle this Int? */
   491            FuncPtr fxn;            /* Dispatched ISR function */
   492            PlugFuncPtr pfxn;       /* "Hwi_plug'd" ISR function. */
   493        };
   494
   495        /*!
   496         * Meta-only array of interrupt objects.
   497         * This meta-only array of Hwi config objects is initialized
   498         * in Hwi.xs:module$meta$init().
   499         */
   500        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   501
   502        struct Instance_State {
   503            Bits16      disableMask;    // Interrupts to mask during ISR.
   504            Bits16      restoreMask;    // Interrupts to restore after ISR.
   505            UArg        arg;            // Argument to Hwi function.
   506            FuncPtr     fxn;            // Hwi function.
   507            Irp         irp;            // current IRP
   508            Ptr         hookEnv[];
   509        };
   510
   511        struct Module_State {
   512            Char        intEvents[12];  // Initial event mapping
   513            Bits16      ierMask;        // Initial IER mask
   514            Char        *taskSP;        // temporary storage of interrupted
   515                                        // Task's SP during ISR execution
   516            /* ROM */
   517            Char        *isrStack;      // Points to isrStack address
   518            Ptr         vectorTableBase;// ti_sysbios_family_c64_Hwi0
   519            Ptr         bss;            // bss address
   520
   521            Handle      dispatchTable[NUM_INTERRUPTS];
   522                                        // dispatch table
   523        };
   524    }
   525    /*
   526     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:24; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   527
   528     */
   529


package ti.sysbios.family.c67p

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    //requires ti.sysbios.knl;
    39
    40    /*!
    41     *  ======== ti.sysbios.family.c67p ========
    42     *  Contains specifications for the C64 specific SYS/BIOS functions.
    43     *
    44     *  The link below provides SYS/BIOS C6x register usage information:
    45     *
    46     *      {@link ./../c62/doc-files/c6xregconv.html SYS/BIOS C6x Register Usage}
    47     *
    48     */
    49    package ti.sysbios.family.c67p [2,0,0,0] {
    50        module Cache;
    51        module Hwi;
    52        module Timer;
    53        module TimestampProvider;
    54        module Clobber;
    55        module Settings;
    56    }
    57    /*
    58     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    59
    60     */
    61


module ti.sysbios.family.c67p.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.c67p;
    37
    38    /*!
    39     *  ======== Settings ========
    40     *  Device/Family-specific delegate assignment module for
    41     *  C67P target devices.
    42     */
    43    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    44    {
    45    }
    46
    47
    48    /*
    49     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.c67p.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c67p;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Types;
    44    import ti.sysbios.interfaces.ITimer;
    45
    46    /*!
    47     *  ======== Timer ========
    48     *  Timer Peripherals Manager for c67p family.
    49     *
    50     *  @p(html)
    51     *  <h3> Calling Context </h3>
    52     *  <table border="1" cellpadding="3">
    53     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    54     *
    55     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    56     *    <!--                                                                                                                 -->
    57     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    61     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #getCount}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    68     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    72     *    <tr><td colspan="6"> Definitions: <br />
    73     *       <ul>
    74     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    75     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    76     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    77     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    78     *           <ul>
    79     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    80     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    81     *             <li> During main().</li>
    82     *             <li> During BIOS.startupFxns.</li>
    83     *           </ul>
    84     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    85     *           <ul>
    86     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    87     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    88     *           </ul>
    89     *       </ul>
    90     *    </td></tr>
    91     *
    92     *  </table>
    93     *  @p
    94     *
    95     */
    96    @InstanceFinalize       /* To cleanup */
    97    @InstanceInitError      /* To report unavailability of timer */
    98    @ModuleStartup          /* to configure static timers */
    99
   100    module Timer inherits ti.sysbios.interfaces.ITimer
   101    {
   102        /*! Max value of Timer period for PeriodType_COUNTS*/
   103        const UInt MAX_PERIOD = 0xffffffff;
   104
   105        /*! Number of timer peripherals on chip */
   106        const Int NUM_TIMER_DEVICES = 2;
   107
   108        /*! @_nodoc
   109         *  Min instructions to use in trigger().
   110         */
   111        const Int MIN_SWEEP_PERIOD = 8;
   112
   113        /*! Timer Configuration struct.
   114         *
   115         *  @field(cos)     When true timer stops counting during emulation halt.
   116         *                  When false timer continues to count during emulation
   117         *                  halt.
   118         */
   119        struct Control {
   120            Bool cos;      /*! 0=stop in debug mode; 1=continue in debug mode */
   121        };
   122
   123        /*! @_nodoc */
   124        @XmlDtd
   125        metaonly struct BasicView {
   126            Ptr         halTimerHandle;
   127            String      label;
   128            UInt        id;
   129            String      startMode;
   130            String      runMode;
   131            UInt        period;
   132            String      periodType;
   133            UInt        intNum;
   134            String      tickFxn[];
   135            UArg        arg;
   136            String      extFreq;
   137            UInt32      accuTicks;
   138            String      hwiHandle;
   139        };
   140
   141        /*! @_nodoc */
   142        metaonly struct DeviceView {
   143            UInt        id;
   144            String      device;
   145            String      devAddr;
   146            UInt        intNum;
   147            String      runMode;
   148            UInt        period;
   149            UInt        currCount;
   150            UInt        remainingCount;
   151            String      state;
   152        };
   153
   154        /*! @_nodoc */
   155        metaonly struct ModuleView {
   156            String      availMask;      /* available 32-bit timer halves */
   157        }
   158
   159        /*! @_nodoc */
   160        @Facet
   161        metaonly config ViewInfo.Instance rovViewInfo =
   162            ViewInfo.create({
   163                viewMap: [
   164                [
   165                    'Basic',
   166                    {
   167                        type: ViewInfo.INSTANCE,
   168                        viewInitFxn: 'viewInitBasic',
   169                        structName: 'BasicView'
   170                    }
   171                ],
   172                [
   173                    'Device',
   174                    {
   175                        type: ViewInfo.INSTANCE,
   176                        viewInitFxn: 'viewInitDevice',
   177                        structName: 'DeviceView'
   178                    }
   179                ],
   180                [
   181                    'Module',
   182                    {
   183                        type: ViewInfo.MODULE,
   184                        viewInitFxn: 'viewInitModule',
   185                        structName: 'ModuleView'
   186                    }
   187                ],
   188                ]
   189            });
   190
   191        /*!
   192         *  Error raised when timer id specified is not supported.
   193         */
   194        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   195
   196        /*!
   197         *  Error raised when timer requested is in use
   198         */
   199        config Error.Id E_notAvailable  =
   200            {msg: "E_notAvailable: Timer not available %d"};
   201
   202        /*!
   203         *  Error raised when Hwi Params has mask where self is turned on.
   204         *
   205         *  This is not allowed because the timers on this platform do not
   206         *  support one-shot mode and a stub is used to stop it.
   207         *  Another timer interrupt cannot go off when the ISR is running.
   208         */
   209        config Error.Id E_invalidHwiMask  =
   210            {msg: "E_InvalidMask: Mask in hwiParams cannot enable self"};
   211
   212        /*!
   213         *  Error raised when period requested is not supported
   214         */
   215        config Error.Id E_cannotSupport  =
   216            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   217
   218        /*!
   219         *  ======== anyMask ========
   220         *  Available mask to be used when select = Timer_ANY
   221         */
   222        config UInt anyMask = 0x3;
   223
   224        /*!
   225         *  ======== oneShotStub ========
   226         *  @_nodoc
   227         *  C64 timer does not support one shot mode. This stub stops timer
   228         *  and clears IFR.
   229         *
   230         *  @param(arg)     Unused.
   231         */
   232        Void oneShotStub(UArg arg);
   233
   234        /*!
   235         *  ======== periodicStub ========
   236         *  @_nodoc
   237         *  When accuTicks = true, this stub does the tick accumulation.
   238         *
   239         *  @param(arg)     Unused.
   240         */
   241        Void periodicStub(UArg arg);
   242
   243        /*!
   244         *  ======== getHandle ========
   245         *  @_nodoc
   246         *  Used by TimestampProvider module to get hold of timer handle used by
   247         *  Clock.
   248         *
   249         *  @param(id)      timer Id.
   250         */
   251        Handle getHandle(UInt id);
   252
   253    instance:
   254
   255
   256        /*! Control register configuration. Default cos=0. */
   257        config Control controlRegInit = {cos: 0};
   258
   259        /*! Hwi Params for Hwi Object. Default is null.*/
   260        config Hwi.Params *hwiParams = null;
   261
   262        /*! Hwi intNum to be used by Timer. */
   263        config Int intNum = -1;
   264
   265        /*!
   266         *  ======== reconfig ========
   267         *  Used to modify static timer instances at runtime.
   268         *
   269         *  @param(timerParams)     timer Params
   270         *  @param(tickFxn)         functions that runs when timer expires.
   271         */
   272        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   273
   274
   275        /*!
   276         *  ======== getAccuTicks ========
   277         *  @_nodoc
   278         *  returns accumulated ticks. Used by TimestampProvider.
   279         *
   280         *  @b(returns)     get accumulated ticks
   281         */
   282        UInt32 getAccuTicks();
   283
   284    internal:   /* not for client use */
   285
   286        /*!
   287         *  ======== noStartupNeeded ========
   288         *  Flag used to prevent misc code from being brought in
   289         *  un-necessarily
   290         */
   291        config UInt startupNeeded = false;
   292
   293        struct Instance_State {
   294            Bool                    staticInst;
   295            Int                     id;
   296            UInt                    controlRegInit;
   297            ITimer.RunMode          runMode;
   298            ITimer.StartMode        startMode;
   299            UInt                    period;
   300            ITimer.PeriodType       periodType;
   301            UInt                    intNum;
   302            UArg                    arg;
   303            Hwi.FuncPtr             tickFxn;
   304            Types.FreqHz            extFreq;
   305            volatile UInt32         accuTicks;
   306            Hwi.Handle              hwi;
   307        }
   308
   309        struct Module_State {
   310            UInt            availMask;      /* available peripherals */
   311            Handle          handles[NUM_TIMER_DEVICES];
   312                                            /* array of handles based on id */
   313        }
   314    }
   315    /*
   316     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   317
   318     */
   319


module ti.sysbios.family.c67p.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.c67p;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td colspan="6"> Definitions: <br />
    54     *       <ul>
    55     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    56     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    57     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    58     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    59     *           <ul>
    60     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    61     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    62     *             <li> During main().</li>
    63     *             <li> During BIOS.startupFxns.</li>
    64     *           </ul>
    65     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    66     *           <ul>
    67     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    68     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    69     *           </ul>
    70     *       </ul>
    71     *    </td></tr>
    72     *
    73     *  </table>
    74     *  @p
    75     */
    76
    77    @ModuleStartup          /* To get Clock Timer Handle */
    78
    79    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    80    {
    81        /*! @_nodoc */
    82        @XmlDtd
    83        metaonly struct ModuleView {
    84            Bool    usesClockTimer;
    85        };
    86
    87        /*! TimestampProvider timer id. Max id value is 2 */
    88        config UInt timerId = Timer.ANY;
    89
    90        /*!
    91         *  Set this parameter when you want TimestampProvider is use the same timer
    92         *  as the Clock module
    93         *
    94         *  This parameter overrides the timeId setting.
    95         */
    96        config Bool useClockTimer = true;
    97
    98        /*!@_nodoc
    99         *  Internal use. Function that starts timer before main
   100         */
   101        Void startTimer();
   102
   103    internal:   /* not for client use */
   104
   105        struct Module_State {
   106            Timer.Handle    timer;          /* timer instance used */
   107        }
   108    }
   109    /*
   110     *  @(#) ti.sysbios.family.c67p; 2, 0, 0, 0,496; 6-15-2011 16:25:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   111
   112     */
   113


Supported Texas Instruments Devices and their Proxies

  • C64x+
    • OMAP2431
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • OMAP2530
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • OMAP2531
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • OMAP3425
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3525
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3530
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320C2430
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C3430
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320C6421
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6424
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6452
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6454
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6455
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6457
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6472
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6474
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM415
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM420
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM421
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM425
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM426
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6431
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6433
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6435
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6437
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6441
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6443
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM6446
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320CDM6467
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320CDM647
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CDM648
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CTCI6482
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CTCI6484
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CTCI6486
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CTCI6487
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320CTCI6488
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320TCI6485
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320TCI6489
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
  • C674x
    • OMAPL108
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL118
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL137
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL138
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320C6742
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6743
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6745
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6746
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6747
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6748
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6A8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DA802
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320DA803
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320DA804
        cacheDelegate | ti.sysbios.family.c64p.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320DA805
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA807
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA808
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA810
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA828
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA830
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA840
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA850
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DM8148
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DM8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI814X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI816X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
  • C64T
    • OMAP4430
        cacheDelegate | ti.sysbios.hal.unicache.Cache
        hwiDelegate | ti.sysbios.family.arm.m3.Hwi
        timerDelegate | ti.sysbios.family.arm.ducati.Timer
        timestampDelegate | ti.sysbios.family.arm.ducati.TimestampProvider
  • C66
    • TMS320C6670
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6672
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6674
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320C6678
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320TCI6608
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320TCI6616
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
    • TMS320TCI6618
        cacheDelegate | ti.sysbios.family.c66.Cache
        hwiDelegate | ti.sysbios.family.c64p.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.family.c64p.TimestampProvider
  • C28 large model
    • TMS320C2801 TMS320C28020 TMS320C28021 TMS320C28022 TMS320C28023 TMS320C28026 TMS320C28027 TMS320C28032 TMS320C28033 TMS320C28034 TMS320C28035 TMS320C2806 TMS320C2808 TMS320C2810 TMS320C2811 TMS320C2812 TMS320C28232 TMS320C28234 TMS320C28235
        hwiDelegate | ti.sysbios.family.c28.Hwi
        timerDelegate | ti.sysbios.family.c28.Timer
        timestampDelegate | ti.sysbios.family.c28.TimestampProvider
    • TMS320F2801 TMS320F28015 TMS320F28016 TMS320F2802 TMS320F28020 TMS320F28021 TMS320F28022 TMS320F28023 TMS320F28026 TMS320F28027 TMS320F28030 TMS320F28031 TMS320F28032 TMS320F28033 TMS320F28034 TMS320F28035 TMS320F28044 TMS320F2806 TMS320F2808 TMS320F2809 TMS320F2810 TMS320F2811 TMS320F2812 TMS320F28232 TMS320F28234 TMS320F28235
        hwiDelegate | ti.sysbios.family.c28.Hwi
        timerDelegate | ti.sysbios.family.c28.Timer
        timestampDelegate | ti.sysbios.family.c28.TimestampProvider
  • C28 floating point model
    • TMS320C28332 TMS320C28334 TMS320C28335 TMS320C28341 TMS320C28342 TMS320C28343 TMS320C28344 TMS320C28345 TMS320C28346
        hwiDelegate | ti.sysbios.family.c28.Hwi
        timerDelegate | ti.sysbios.family.c28.Timer
        timestampDelegate | ti.sysbios.family.c28.TimestampProvider
    • TMS320F28062 TMS320F28063 TMS320F28064 TMS320F28065 TMS320F28066 TMS320F28067 TMS320F28068 TMS320F28069 TMS320F28332 TMS320F28334 TMS320F28335
        hwiDelegate | ti.sysbios.family.c28.Hwi
        timerDelegate | ti.sysbios.family.c28.Timer
        timestampDelegate | ti.sysbios.family.c28.TimestampProvider
    • F28M35x
        cacheDelegate | ti.sysbios.hal.CacheNull
        hwiDelegate | ti.sysbios.family.arm.m3.Hwi
        timerDelegate | ti.sysbios.family.arm.lm3.Timer
        timestampDelegate | ti.sysbios.family.arm.f28m35x.TimestampProvider
  • Arm 9
    • AM1705
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • AM1707
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • AM1806
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • AM1808
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL108
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL118
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL137
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • OMAPL138
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320CDM510
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320CDM6446
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320CDM6467
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA805
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA807
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA808
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA810
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA828
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA830
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA840
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DA850
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.da830.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DM355
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
    • TMS320DM365
        cacheDelegate | ti.sysbios.family.arm.arm9.Cache
        hwiDelegate | ti.sysbios.family.arm.dm6446.Hwi
        timerDelegate | ti.sysbios.timers.timer64.Timer
        timestampDelegate | ti.sysbios.timers.timer64.TimestampProvider
  • Cortex-M3
    • LM3S101 LM3S102 LM3S1110 LM3S1133 LM3S1138 LM3S1150 LM3S1162 LM3S1165 LM3S1166 LM3S1332 LM3S1435 LM3S1439 LM3S1512 LM3S1538 LM3S1601 LM3S1607 LM3S1608 LM3S1620 LM3S1621 LM3S1625 LM3S1626 LM3S1627 LM3S1635 LM3S1636 LM3S1637 LM3S1651 LM3S1751 LM3S1776 LM3S1811 LM3S1816 LM3S1850 LM3S1911 LM3S1918 LM3S1937 LM3S1958 LM3S1960 LM3S1968 LM3S1969 LM3S1B21 LM3S1J11 LM3S1J16 LM3S1N11 LM3S1N16 LM3S1P51 LM3S1R21 LM3S1R26 LM3S1W16 LM3S1Z16 LM3S2016 LM3S2108 LM3S2110 LM3S2139 LM3S2276 LM3S2410 LM3S2412 LM3S2432 LM3S2533 LM3S2601 LM3S2608 LM3S2616 LM3S2620 LM3S2637 LM3S2651 LM3S2671 LM3S2678 LM3S2730 LM3S2739 LM3S2776 LM3S2793 LM3S2911 LM3S2918 LM3S2919 LM3S2939 LM3S2948 LM3S2950 LM3S2965 LM3S2B93 LM3S300 LM3S301 LM3S308 LM3S310 LM3S315 LM3S316 LM3S317 LM3S328 LM3S3634 LM3S3651 LM3S3739 LM3S3748 LM3S3749 LM3S3826 LM3S3J26 LM3S3N26 LM3S3W26 LM3S3Z26 LM3S5632 LM3S5651 LM3S5652 LM3S5656 LM3S5662 LM3S5732 LM3S5737 LM3S5739 LM3S5747 LM3S5749 LM3S5752 LM3S5762 LM3S5791 LM3S5951 LM3S5956 LM3S5B91 LM3S5K31 LM3S5K36 LM3S5P31 LM3S5P36 LM3S5P51 LM3S5P56 LM3S5R31 LM3S5R36 LM3S5T36 LM3S5Y36 LM3S600 LM3S601 LM3S608 LM3S610 LM3S6100 LM3S611 LM3S6110 LM3S612 LM3S613 LM3S615 LM3S617 LM3S618 LM3S628 LM3S6420 LM3S6422 LM3S6432 LM3S6537 LM3S6610 LM3S6611 LM3S6618 LM3S6633 LM3S6637 LM3S6730 LM3S6753 LM3S6816 LM3S6911 LM3S6916 LM3S6918 LM3S6938 LM3S6950 LM3S6952 LM3S6965 LM3S800 LM3S801 LM3S808 LM3S811 LM3S812 LM3S815 LM3S817 LM3S818 LM3S828 LM3S8530 LM3S8538 LM3S8630 LM3S8730 LM3S8733 LM3S8738 LM3S8930 LM3S8933 LM3S8938 LM3S8962 LM3S8970 LM3S8971 LM3S9781 LM3S9790 LM3S9792 LM3S9997 LM3S9B81 LM3S9B90 LM3S9B92 LM3S9B95 LM3S9B96 LM3S9L97
        cacheDelegate | ti.sysbios.hal.CacheNull
        hwiDelegate | ti.sysbios.family.arm.m3.Hwi
        timerDelegate | ti.sysbios.family.arm.lm3.Timer
        timestampDelegate | ti.sysbios.family.arm.lm3.TimestampProvider
    • F28M35x
        cacheDelegate | ti.sysbios.hal.CacheNull
        hwiDelegate | ti.sysbios.family.arm.m3.Hwi
        timerDelegate | ti.sysbios.family.arm.lm3.Timer
        timestampDelegate | ti.sysbios.family.arm.f28m35x.TimestampProvider
    • OMAP4430
        cacheDelegate | ti.sysbios.hal.unicache.Cache
        hwiDelegate | ti.sysbios.family.arm.m3.Hwi
        timerDelegate | ti.sysbios.family.arm.ducati.Timer
        timestampDelegate | ti.sysbios.family.arm.ducati.TimestampProvider
    • TMS320C6A8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DM8148
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DM8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI814X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI816X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
  • Cortex-A8
    • OMAP3403
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3405
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3425
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3503
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3505
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3515
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3517
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3525
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • OMAP3530
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TI81XX
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320C3430
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.gptimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320C6A8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DM8148
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320DM8168
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI814X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
    • TMS320TI816X
        cacheDelegate | ti.sysbios.family.arm.a8.Cache
        hwiDelegate | ti.sysbios.family.arm.a8.intcps.Hwi
        timerDelegate | ti.sysbios.timers.dmtimer.Timer
        timestampDelegate | ti.sysbios.family.arm.a8.TimestampProvider
  • MSP430
    • MSP430BT5190 MSP430F5131 MSP430F5132 MSP430F5151 MSP430F5152 MSP430F5171 MSP430F5172 MSP430F5304 MSP430F5308 MSP430F5309 MSP430F5310 MSP430F5324 MSP430F5325 MSP430F5326 MSP430F5327 MSP430F5328 MSP430F5329 MSP430F5340 MSP430F5341 MSP430F5342 MSP430F5418 MSP430F5418A MSP430F5419 MSP430F5419A MSP430F5435 MSP430F5435A MSP430F5436 MSP430F5436A MSP430F5437 MSP430F5437A MSP430F5438 MSP430F5438A MSP430F5500 MSP430F5501 MSP430F5502 MSP430F5503 MSP430F5504 MSP430F5505 MSP430F5506 MSP430F5507 MSP430F5508 MSP430F5509 MSP430F5510 MSP430F5513 MSP430F5514 MSP430F5515 MSP430F5517 MSP430F5519 MSP430F5521 MSP430F5522 MSP430F5524 MSP430F5525 MSP430F5526 MSP430F5527 MSP430F5528 MSP430F5529 MSP430F5630 MSP430F5631 MSP430F5632 MSP430F5633 MSP430F5634 MSP430F5635 MSP430F5636 MSP430F5637 MSP430F5638 MSP430F6630 MSP430F6631 MSP430F6632 MSP430F6633 MSP430F6634 MSP430F6635 MSP430F6636 MSP430F6637 MSP430F6638
        hwiDelegate | ti.sysbios.family.msp430.Hwi
        timerDelegate | ti.sysbios.family.msp430.Timer
        timestampDelegate | ti.sysbios.family.msp430.TimestampProvider
    • CC430F5133 CC430F5135 CC430F5137 CC430F6125 CC430F6126 CC430F6127 CC430F6135 CC430F6137
        hwiDelegate | ti.sysbios.family.msp430.Hwi
        timerDelegate | ti.sysbios.family.msp430.Timer
        timestampDelegate | ti.sysbios.family.msp430.TimestampProvider
    • generated on Wed, 15 Jun 2011 23:02:50 GMT

Supported Targets


Supported Devices

C64x+ | OMAP2431 OMAP2530 OMAP2531 OMAP3425 OMAP3525 OMAP3530 TMS320C2430 TMS320C3430 TMS320C6421 TMS320C6424 TMS320C6452 TMS320C6454 TMS320C6455 TMS320C6457 TMS320C6472 TMS320C6474 TMS320CDM415 TMS320CDM420 TMS320CDM421 TMS320CDM425 TMS320CDM426 TMS320CDM6431 TMS320CDM6433 TMS320CDM6435 TMS320CDM6437 TMS320CDM6441 TMS320CDM6443 TMS320CDM6446 TMS320CDM6467 TMS320CDM647 TMS320CDM648 TMS320CTCI6482 TMS320CTCI6484 TMS320CTCI6486 TMS320CTCI6487 TMS320CTCI6488 TMS320TCI6485 TMS320TCI6489
C674x | OMAPL108 OMAPL118 OMAPL137 OMAPL138 TMS320C6742 TMS320C6743 TMS320C6745 TMS320C6746 TMS320C6747 TMS320C6748 TMS320C6A8168 TMS320DA802 TMS320DA803 TMS320DA804 TMS320DA805 TMS320DA807 TMS320DA808 TMS320DA810 TMS320DA828 TMS320DA830 TMS320DA840 TMS320DA850 TMS320DM8148 TMS320DM8168 TMS320TI814X TMS320TI816X
C64T | OMAP4430
C66 | TMS320C6670 TMS320C6672 TMS320C6674 TMS320C6678 TMS320TCI6608 TMS320TCI6616 TMS320TCI6618
C28 large model | TMS320C2801 TMS320C28020 TMS320C28021 TMS320C28022 TMS320C28023 TMS320C28026 TMS320C28027 TMS320C28032 TMS320C28033 TMS320C28034 TMS320C28035 TMS320C2806 TMS320C2808 TMS320C2810 TMS320C2811 TMS320C2812 TMS320C28232 TMS320C28234 TMS320C28235 TMS320F2801 TMS320F28015 TMS320F28016 TMS320F2802 TMS320F28020 TMS320F28021 TMS320F28022 TMS320F28023 TMS320F28026 TMS320F28027 TMS320F28030 TMS320F28031 TMS320F28032 TMS320F28033 TMS320F28034 TMS320F28035 TMS320F28044 TMS320F2806 TMS320F2808 TMS320F2809 TMS320F2810 TMS320F2811 TMS320F2812 TMS320F28232 TMS320F28234 TMS320F28235
C28 floating point model | F28M35x TMS320C28332 TMS320C28334 TMS320C28335 TMS320C28341 TMS320C28342 TMS320C28343 TMS320C28344 TMS320C28345 TMS320C28346 TMS320F28062 TMS320F28063 TMS320F28064 TMS320F28065 TMS320F28066 TMS320F28067 TMS320F28068 TMS320F28069 TMS320F28332 TMS320F28334 TMS320F28335
Arm 9 | AM1705 AM1707 AM1806 AM1808 OMAPL108 OMAPL118 OMAPL137 OMAPL138 TMS320CDM510 TMS320CDM6446 TMS320CDM6467 TMS320DA805 TMS320DA807 TMS320DA808 TMS320DA810 TMS320DA828 TMS320DA830 TMS320DA840 TMS320DA850 TMS320DM355 TMS320DM365
Cortex-M3 | F28M35x LM3S101 LM3S102 LM3S1110 LM3S1133 LM3S1138 LM3S1150 LM3S1162 LM3S1165 LM3S1166 LM3S1332 LM3S1435 LM3S1439 LM3S1512 LM3S1538 LM3S1601 LM3S1607 LM3S1608 LM3S1620 LM3S1621 LM3S1625 LM3S1626 LM3S1627 LM3S1635 LM3S1636 LM3S1637 LM3S1651 LM3S1751 LM3S1776 LM3S1811 LM3S1816 LM3S1850 LM3S1911 LM3S1918 LM3S1937 LM3S1958 LM3S1960 LM3S1968 LM3S1969 LM3S1B21 LM3S1J11 LM3S1J16 LM3S1N11 LM3S1N16 LM3S1P51 LM3S1R21 LM3S1R26 LM3S1W16 LM3S1Z16 LM3S2016 LM3S2108 LM3S2110 LM3S2139 LM3S2276 LM3S2410 LM3S2412 LM3S2432 LM3S2533 LM3S2601 LM3S2608 LM3S2616 LM3S2620 LM3S2637 LM3S2651 LM3S2671 LM3S2678 LM3S2730 LM3S2739 LM3S2776 LM3S2793 LM3S2911 LM3S2918 LM3S2919 LM3S2939 LM3S2948 LM3S2950 LM3S2965 LM3S2B93 LM3S300 LM3S301 LM3S308 LM3S310 LM3S315 LM3S316 LM3S317 LM3S328 LM3S3634 LM3S3651 LM3S3739 LM3S3748 LM3S3749 LM3S3826 LM3S3J26 LM3S3N26 LM3S3W26 LM3S3Z26 LM3S5632 LM3S5651 LM3S5652 LM3S5656 LM3S5662 LM3S5732 LM3S5737 LM3S5739 LM3S5747 LM3S5749 LM3S5752 LM3S5762 LM3S5791 LM3S5951 LM3S5956 LM3S5B91 LM3S5K31 LM3S5K36 LM3S5P31 LM3S5P36 LM3S5P51 LM3S5P56 LM3S5R31 LM3S5R36 LM3S5T36 LM3S5Y36 LM3S600 LM3S601 LM3S608 LM3S610 LM3S6100 LM3S611 LM3S6110 LM3S612 LM3S613 LM3S615 LM3S617 LM3S618 LM3S628 LM3S6420 LM3S6422 LM3S6432 LM3S6537 LM3S6610 LM3S6611 LM3S6618 LM3S6633 LM3S6637 LM3S6730 LM3S6753 LM3S6816 LM3S6911 LM3S6916 LM3S6918 LM3S6938 LM3S6950 LM3S6952 LM3S6965 LM3S800 LM3S801 LM3S808 LM3S811 LM3S812 LM3S815 LM3S817 LM3S818 LM3S828 LM3S8530 LM3S8538 LM3S8630 LM3S8730 LM3S8733 LM3S8738 LM3S8930 LM3S8933 LM3S8938 LM3S8962 LM3S8970 LM3S8971 LM3S9781 LM3S9790 LM3S9792 LM3S9997 LM3S9B81 LM3S9B90 LM3S9B92 LM3S9B95 LM3S9B96 LM3S9L97 OMAP4430 TMS320C6A8168 TMS320DM8148 TMS320DM8168 TMS320TI814X TMS320TI816X
Cortex-A8 | OMAP3403 OMAP3405 OMAP3425 OMAP3503 OMAP3505 OMAP3515 OMAP3517 OMAP3525 OMAP3530 TI81XX TMS320C3430 TMS320C6A8168 TMS320DM8148 TMS320DM8168 TMS320TI814X TMS320TI816X
MSP430 | CC430F5133 CC430F5135 CC430F5137 CC430F6125 CC430F6126 CC430F6127 CC430F6135 CC430F6137 MSP430BT5190 MSP430F5131 MSP430F5132 MSP430F5151 MSP430F5152 MSP430F5171 MSP430F5172 MSP430F5304 MSP430F5308 MSP430F5309 MSP430F5310 MSP430F5324 MSP430F5325 MSP430F5326 MSP430F5327 MSP430F5328 MSP430F5329 MSP430F5340 MSP430F5341 MSP430F5342 MSP430F5418 MSP430F5418A MSP430F5419 MSP430F5419A MSP430F5435 MSP430F5435A MSP430F5436 MSP430F5436A MSP430F5437 MSP430F5437A MSP430F5438 MSP430F5438A MSP430F5500 MSP430F5501 MSP430F5502 MSP430F5503 MSP430F5504 MSP430F5505 MSP430F5506 MSP430F5507 MSP430F5508 MSP430F5509 MSP430F5510 MSP430F5513 MSP430F5514 MSP430F5515 MSP430F5517 MSP430F5519 MSP430F5521 MSP430F5522 MSP430F5524 MSP430F5525 MSP430F5526 MSP430F5527 MSP430F5528 MSP430F5529 MSP430F5630 MSP430F5631 MSP430F5632 MSP430F5633 MSP430F5634 MSP430F5635 MSP430F5636 MSP430F5637 MSP430F5638 MSP430F6630 MSP430F6631 MSP430F6632 MSP430F6633 MSP430F6634 MSP430F6635 MSP430F6636 MSP430F6637 MSP430F6638

Supported Targets

Target | Codegen Version
ti.targets.C28_large | 5.2.3
ti.targets.C28_float | 5.2.3
ti.targets.C64 | 7.0.0
ti.targets.C64P | 7.0.0
ti.targets.C64P_big_endian | 7.0.0
ti.targets.C674 | 7.0.0
ti.targets.msp430.MSP430 | 3.3.0
ti.targets.msp430.MSP430X | 3.3.0
ti.targets.msp430.MSP430X_small | 3.3.0
ti.targets.elf.C64P | 7.2.0
ti.targets.elf.C64P_big_endian | 7.2.0
ti.targets.elf.C674 | 7.2.0
ti.targets.elf.C64T | 7.2.0
ti.targets.elf.C66 | 7.2.0
ti.targets.elf.C66_big_endian | 7.2.0
ti.targets.arm.elf.Arm9 | 4.9.0
ti.targets.arm.elf.A8F | 4.9.0
ti.targets.arm.elf.M3 | 4.9.0

Delegates for Supported Devices


module ti.sysbios.family.msp430.ClockFreqs

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== ClockFreqs.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.msp430;
    39
    40    /*!
    41     *  ======== ClockFreqs ========
    42     *  ClockFreqs Module.
    43     *
    44     *  This module is used to define the ACLK and SMCLK frequencies in effect when
    45     *  BIOS_start() is called at the end of main().  It also provides a function
    46     *  that can be called by the application at runtime to query individual
    47     *  clock frequencies.
    48     *
    49     *  If the application configuration defines values for these two clocks, it
    50     *  (the application) is responsible for setting up the clocks to the
    51     *  corresponding frequencies.  This module will simply hold the values
    52     *  specified, for reference by other SYS/BIOS modules, or for query by the
    53     *  application.
    54     *
    55     *  If the application configuration specifies a value for one of these
    56     *  two clock frequencies, it must specify values for both clock frequencies;
    57     *  if it does not, a build error will be thrown.
    58     *
    59     *  If the application does not define values for one of these clocks, the
    60     *  values will default either to the device reset values, or the boost values
    61     *  setup by the Boot module (ti.catalog.msp430.init.Boot).  For example, if
    62     *  the application does not configure values for ClockFreq, and does not turn
    63     *  off the Boot module's default frequency boost, then the Boot module boost
    64     *  frequencies are used.
    65     *
    66     *  If the application does not configure values for ClockFreq, and *does* turn
    67     *  off the Boot module's frequency boost (see snippet below), then the default
    68     *  reset frequency values will be used.
    69     *
    70     *  @p(code)
    71     *      var Boot = xdc.module('ti.catalog.msp430.init.Boot');
    72     *      Boot.configureDCO = false;
    73     *  @p
    74     *
    75     *  Currently the reset and Boot module boost values are fixed, as shown below.
    76     *  In future releases these values may made changeable.
    77     *
    78     *  The default reset values are:
    79     *
    80     *  @p(code)
    81     *      ACLK  = 32768 Hz
    82     *      SMCLK = 1000000 Hz
    83     *  @p
    84     *
    85     *  The default Boot module boost values are:
    86     *
    87     *  @p(code)
    88     *      ACLK  = 32768 Hz
    89     *      SMCLK = 8192000 Hz
    90     *  @p
    91     *
    92     *  Note: This module allows query of the CPU clock (MCLK) frequency via the
    93     *  ClockFreqs_getFrequency() API.  But MCLK cannot be configured with this
    94     *  module.  Since MCLK is the CPU frequency, it is configured in the BIOS
    95     *  module.  For example:
    96     *
    97     *  @p(code)
    98     *      var BIOS = xdc.useModule('ti.sysbios.BIOS');
    99     *      BIOS.cpuFreq.lo = 25000000;
   100     *      BIOS.cpuFreq.hi = 0;
   101     *  @p
   102     *
   103     *  @p(html)
   104     *  <h3> Calling Context </h3>
   105     *  <table border="1" cellpadding="3">
   106     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
   107     *
   108     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   109     *    <!-- -->
   110     *    <tr><td> {@link #getFrequency} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
   111     *    <tr><td colspan="6"> Definitions: <br />
   112     *       <ul>
   113     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   114     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   115     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   116     *         <li> <b>Main</b>: API is callable from main(). </li>
   117     *         <li> <b>Startup</b>: API is callable during any module startup. </li>
   118     *       </ul>
   119     *    </td></tr>
   120     *
   121     *  </table>
   122     *  @p
   123     */
   124
   125    module ClockFreqs
   126    {
   127        /*! Clocks */
   128        enum Clock {
   129            Clock_ACLK,             /* ACLK */
   130            Clock_SMCLK,            /* SMCLK */
   131            Clock_MCLK              /* MCLK */
   132        };
   133
   134        /*! ACLK frequency (Hz) */
   135        config UInt32 ACLK;
   136
   137        /*! SMCLK frequency (Hz) */
   138        config UInt32 SMCLK;
   139
   140        /*!
   141         *  ======== getFrequency ========
   142         *  Get the frequency for a clock.
   143         *
   144         */
   145        @DirectCall
   146        UInt32 getFrequency(Clock clock);
   147
   148    }
   149    /*
   150     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   151
   152     */
   153


module ti.sysbios.family.msp430.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.msp430;
    37
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Diags;
    40    import xdc.runtime.Log;
    41    import xdc.runtime.Assert;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.IHwi;
    45
    46    /*!
    47     *  ======== Hwi ========
    48     *  MSP430 Hardware Interrupt Manager
    49     *
    50     *  This module implements the generic Hwi module functions
    51     *  Hwi_enable, Hwi_disable, and Hwi_restore as defined by
    52     *  {@link ti.sysbios.interfaces.IHwi IHwi}.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    58     *
    59     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    60     *    <!--                                                                                                                 -->
    61     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    62     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    64     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    70     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     *
    99     */
   100
   101
   102    @Template("./Hwi.xdt")  /* generates the vector table and the dispatcher */
   103    @ModuleStartup          /* generate a call to startup function */
   104
   105    module Hwi inherits ti.sysbios.interfaces.IHwi
   106    {
   107        /*!
   108         *  The MSP430 supports up to 64 interrupts/exceptions.
   109         *
   110         *  The actual number supported is device specific and provided by
   111         *  the catalog device specification.
   112         */
   113        readonly config Int NUM_INTERRUPTS;
   114
   115        // -------- Module Types --------
   116
   117        /*! Hwi vector function type definition. */
   118        typedef Void (*VectorFuncPtr)(void);
   119
   120         /*! @_nodoc */
   121        metaonly struct BasicView {
   122            Ptr         halHwiHandle;
   123            String      label;
   124            Int         intNum;
   125            String      fxn;
   126            UArg        arg;
   127            Ptr         irp;
   128        };
   129
   130        /*! @_nodoc */
   131        metaonly struct ModuleView {
   132            String      options[4];
   133            SizeT       hwiStackPeak;
   134            SizeT       hwiStackSize;
   135            Ptr         hwiStackBase;
   136        };
   137
   138        /*! @_nodoc */
   139        @Facet
   140        metaonly config ViewInfo.Instance rovViewInfo =
   141            ViewInfo.create({
   142                viewMap: [
   143                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   144                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}]
   145                ]
   146            });
   147
   148        // -------- Module Parameters --------
   149
   150        // Logs
   151
   152        /*!
   153         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   154         */
   155        config Log.Event LM_begin = {
   156            mask: Diags.USER1 | Diags.USER2,
   157            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d, irp: 0x%x"
   158        };
   159
   160        /*!
   161         *  Issued just after return from Hwi function (with interrupts disabled)
   162         */
   163        config Log.Event LD_end = {
   164            mask: Diags.USER2,
   165            msg: "LD_end: hwi: 0x%x"
   166        };
   167
   168        // Asserts
   169
   170        /*! Assert when bad maskSetting parameter provided */
   171        config Assert.Id A_unsupportedMaskingOption = {
   172            msg: "A_unsupportedMaskingOption: unsupported maskSetting."
   173        };
   174
   175        // Errors
   176
   177        /*!
   178         *  Error raised when Hwi is already defined
   179         */
   180        config Error.Id E_alreadyDefined = {
   181            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   182        };
   183
   184        /*!
   185         *  Error raised when an unimplemented Hwi function is called
   186         *
   187         *  The MSP430 does not implement all of the functions defined
   188         *  by {@link ti.sysbios.interfaces.IHwi}.  If applications
   189         *  call such a function, an E_notImplemented error is raised
   190         *  with the name of the unimplemented function passed as an
   191         *  argument.  See {@link xdc.runtime.Error#raise}.
   192         */
   193        config Error.Id E_notImplemented = {
   194            msg: "E_notImplemented: Function not implemented: %s"
   195        };
   196
   197        // configs
   198
   199        /*!
   200         *  ======== fillVectors ========
   201         *  Plug all unused interrupt vectors
   202         *
   203         *  This parameter allows one to plug all unused interrupt vectors
   204         *  a common "stub", {@link #nullIsrFunc}.  This allows one to more
   205         *  easily catch unexpected interrupts and "run away" code.
   206         */
   207        metaonly config Bool fillVectors = true;
   208
   209        /*!
   210         *  ======== nullIsrFunc ========
   211         *  Unused vector handler
   212         *
   213         *  This parameter specifies the interrupt service routine used
   214         *  when filling unused interrupt vectors.  It defaults to a function
   215         *  that simply loops to itself.
   216         */
   217        metaonly config FuncPtr nullIsrFunc;
   218
   219        /*!
   220         *  ======== resetFunc ========
   221         *  Reset handler
   222         *
   223         *  This parameter specifies the interrupt service routine triggered on
   224         *  reset. The default is c_int00.
   225         */
   226        metaonly config VectorFuncPtr resetFunc;
   227
   228        /*!
   229         *  ======== alwaysWake ========
   230         *  Always keep the CPU awake upon return from interrupt?
   231         *
   232         *  This parameter serves as a global 'switch' to control whether the
   233         *  CPU is kept awake (i.e., not allowed to return to a low power mode) at
   234         *  the end of servicing a hardware interrupt (Hwi) managed by SYS/BIOS.
   235         *  The behavior of each interrupt instance can be controlled individually
   236         *  (see {@link #keepAwakeEnabled}); when set to true, this parameter serves
   237         *  as an override of the individual instance selection, to force keep awake
   238         *  of the CPU. This parameter is provided to assist with debug, and to
   239         *  ease use and transition of legacy code to work with SYS/BIOS.
   240         */
   241        metaonly config Bool alwaysWake = false;
   242
   243        /*!
   244         *  ======== alwaysLog ========
   245         *  Always emit Log messages from interrupt stubs?
   246         *
   247         *  This parameter serves as a global 'switch' to control whether Log
   248         *  begin and end messages will be emitted from interrupt stubs.
   249         *  Note that the behavior of each interrupt instance can be controlled
   250         *  individually (see {@link #loggingEnabled}); when set to true, alwaysLog
   251         *  serves as an override of the individual instance selections, forcing
   252         *  logging from the stubs of all configured interrupts.
   253         */
   254        metaonly config Bool alwaysLog = false;
   255
   256        // -------- Module Functions --------
   257
   258        /*!
   259         *  ======== disable ========
   260         */
   261        @Macro
   262        override UInt disable();
   263
   264        /*!
   265         *  ======== enable ========
   266         */
   267        @Macro
   268        override UInt enable();
   269
   270        /*!
   271         *  ======== restore ========
   272         */
   273        @Macro
   274        override Void restore(UInt key);
   275
   276        /*!
   277         *  ======== inUseMeta ========
   278         *  @_nodoc
   279         *  Check for Hwi already in use
   280         *
   281         *  For internal SYS/BIOS use only.
   282         *  Should be called prior to any internal Hwi.create().
   283         *
   284         *  @param(intNum)  interrupt number
   285         */
   286        metaonly Bool inUseMeta(UInt intNum);
   287
   288        /*!
   289         *  ======== plugMeta ========
   290         *  Statically plug an interrupt vector with an ISR address
   291         *
   292         *  @param(intNum)  interrupt number
   293         *  @param(fxn)     pointer to ISR function
   294         */
   295        metaonly Void plugMeta(UInt intNum, Fxn fxn);
   296
   297        /*!
   298         *  @_nodoc
   299         *  ======= logBegin ========
   300         *  Log the LM_begin from within Hwi module scope
   301         */
   302        @DirectCall
   303        Void logBegin(Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
   304
   305        /*!
   306         *  @_nodoc
   307         *  ======= logEnd ========
   308         *  Log the LD_end from within Hwi module scope
   309         */
   310        @DirectCall
   311        Void logEnd(Log.Event evt, IArg a1);
   312
   313    instance:
   314
   315        /*! override maskSetting - Hwi does not manage nesting on 430 */
   316        override config IHwi.MaskingOption maskSetting = IHwi.MaskingOption_ALL;
   317
   318        /*! Does this interrupt support posting of Swis? Default is true. */
   319        metaonly config Bool swiEnabled = true;
   320
   321        /*! Does this interrupt support task pre-emption? Default is true. */
   322        metaonly config Bool taskEnabled = true;
   323
   324        /*! Switch to ISR stack for this interrupt? Default is true. */
   325        metaonly config Bool isrStackEnabled = true;
   326
   327        /*! Does this interrupt allow nesting by other interrupts? Default is false. */
   328        metaonly config Bool nestingEnabled = false;
   329
   330        /*! Does this interrupt support logging?
   331         *
   332         *  If set to true, {@link xdc.runtime.Log Log} statements are inserted
   333         *  into the generated interrupt stub that calls the user's interrupt
   334         *  function.  The stub posts an {@link #LM_begin} event at the beginning
   335         *  of the interrupt service routine and a {@link #LD_end} event after
   336         *  the user's function returns.
   337         *
   338         *  In addition to enabling this flag, you must also enable USER1 and/or
   339         *  USER2 logging for this module.  Otherwise, the events posted by the
   340         *  inserted Log statments will be ignored.
   341         */
   342        metaonly config Bool loggingEnabled = false;
   343
   344        /*! Does this interrupt support thread-type tracking? Default is true. */
   345        metaonly config Bool threadTypeEnabled = true;
   346
   347        /*! Should keep CPU awake following this interrupt? Default is false. */
   348        metaonly config Bool keepAwakeEnabled = false;
   349
   350    internal:   /* not for client use */
   351
   352        /*!
   353         *  ======== init ========
   354         *  Setup Hwi stack
   355         */
   356        Void init();
   357
   358        /*!
   359         *  ======== nonPluggedIsr ========
   360         *  Interrupt service routine that never returns
   361         *
   362         *  This function can be used to plug interrupts that should never
   363         *  occur.  If one does, rather than jumping to an undefined location
   364         *  the program stops with the CPU in a spin lock within this function.
   365         */
   366        Void nonPluggedIsr(UArg intNum);
   367
   368        /*!
   369         *  const array to hold all HookSet objects.
   370         */
   371        config HookSet hooks[length] = [];
   372
   373        /*! Meta World Only Hwi Configuration Object. */
   374        metaonly struct InterruptObj {
   375            String name;            /* symbol used for vector table entry */
   376            Bool used;              /* Interrupt already defined? */
   377            Bool generateStub;      /* handler is generated? */
   378            Bool swiEnabled;
   379            Bool taskEnabled;
   380            Bool nestingEnabled;
   381            Bool isrStackEnabled;
   382            Bool lmBeginEnabled;
   383            Bool ldEndEnabled;
   384            Bool threadTypeEnabled;
   385            Bool keepAwakeEnabled;
   386            String handle;
   387            FuncPtr fxn;            /* "wrapped" ISR function */
   388            Fxn pfxn;               /* non "wrapped" ISR function */
   389            UArg arg;               /* Argument to fxn */
   390        };
   391
   392        /*!
   393         * Meta-only array of interrupt objects.
   394         *
   395         * This meta-only array of Hwi config objects is initialized
   396         * in Hwi.xs:module$meta$init().
   397         */
   398        metaonly config InterruptObj interrupt[];
   399
   400        struct Instance_State {
   401            Int             intNum;         // Interrupt number
   402            Irp             irp;            // current IRP
   403            Ptr             hookEnv[];
   404        };
   405
   406        struct Module_State {
   407            Char        *taskSP;        // Temporary storage of interrupted
   408                                        // Task's SP during ISR execution
   409            /* ROM */
   410            Char        *isrStack;      // Points to isrStack address
   411        };
   412    }
   413    /*
   414     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:26; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   415
   416     */
   417


package ti.sysbios.family.msp430

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    requires ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ti.sysbios.family.msp430 ========
    40     *  Contains specifications for the msp430 family-specific SYS/BIOS functions.
    41     *
    42     */
    43    package ti.sysbios.family.msp430 [1,0,0,0] {
    44        module Hwi;
    45        module IntrinsicsSupport;
    46        module TaskSupport;
    47        module Timer;
    48        module TimestampProvider;
    49        module Power;
    50        module ClockFreqs;
    51        module Settings;
    52    }
    53    /*
    54     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    55
    56     */
    57


module ti.sysbios.family.msp430.Power

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Power.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.msp430;
    39
    40    import xdc.runtime.Error;
    41
    42    /*!
    43     *  ======== Power ========
    44     *  Power Manager Module
    45     *
    46     *  This module provides functions that can be called to reduce MSP430 power
    47     *  consumption.
    48     *
    49     *  @p(html)
    50     *  <h3> Calling Context </h3>
    51     *  <table border="1" cellpadding="3">
    52     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    53     *
    54     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    55     *    <!-- -->
    56     *    <tr><td> {@link #idleCPU} </td><td>   N    </td><td>   N    </td><td>   N </td><td>   N    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #changeIdleMode} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
    58     *    <tr><td> {@link #sleepCPU}  </td><td>   N    </td><td>   N    </td><td>   Y   </td><td>   N    </td><td>   N    </td></tr>
    59     *    <tr><td colspan="6"> Definitions: <br />
    60     *       <ul>
    61     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    62     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    63     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    64     *         <li> <b>Main</b>: API is callable from main(). </li>
    65     *         <li> <b>Startup</b>: API is callable during any module startup. </li>
    66     *       </ul>
    67     *    </td></tr>
    68     *
    69     *  </table>
    70     *  @p
    71     */
    72
    73    module Power
    74    {
    75        /*!
    76         *  ======== SleepPrepFuncPtr ========
    77         *  Sleep mode preparation function type definition
    78         */
    79        typedef Void (*SleepPrepFuncPtr)();
    80
    81        /*!
    82         *  ======== IdleMode ========
    83         *  Available idle modes
    84         */
    85        enum IdleMode {
    86            LPM0 = 0x10,            /* CPUOFF */
    87            LPM1 = 0x50,            /* CPUOFF + SCG0 */
    88            LPM2 = 0x90,            /* CPUOFF + SCG1 */
    89            LPM3 = 0xD0,            /* CPUOFF + SCG0 + SCG1 */
    90            LPM4 = 0xF0             /* CPUOFF + SCG0 + SCG1  + OSCOFF */
    91        };
    92
    93        /*!
    94         *  ======== SleepMode ========
    95         *  Available sleep modes.
    96         */
    97        enum SleepMode {
    98            Sleep_LPM4_5            /*! Shutdown (LPM4.5) */
    99        };
   100
   101        /*!
   102         *  ======== E_dynamicModeNotAllowed ========
   103         *  Dynamic mode change not allowed error
   104         *
   105         *  This Error is raised if there is an attempt to change idleMode at
   106         *  runtime and `{@link #allowDynamicMode}` is set to "false".
   107         */
   108        config Error.Id E_dynamicModeNotAllowed = {
   109            msg: "E_dynamicModeNotAllowed: Dynamic changes to LPM are not allowed (allowDynamicMode=false)"
   110        };
   111
   112        /*!
   113         *  ======== idle ========
   114         *  Idle CPU when threads blocked waiting for an interrupt?
   115         */
   116        config Bool idle = true;
   117
   118        /*!
   119         *  ======== idleMode ========
   120         *  Idle mode for CPU to enter while waiting for an interrupt
   121         */
   122        config IdleMode idleMode = LPM0;
   123
   124        /*!
   125         *  ======== allowDynamicMode ========
   126         *  Allow dynamic changes to idleMode at runtime?
   127         */
   128        config Bool allowDynamicMode = false;
   129
   130        /*!
   131         *  ======== sleepPrepFunction ========
   132         *  I/O preparation function to be called by Power_sleepCPU()
   133         */
   134        config SleepPrepFuncPtr sleepPrepFunction;
   135
   136        /*!
   137         *  ======== idleCPU ========
   138         *  Function to automatically idle the CPU during idle time
   139         *
   140         *  When the `{@link #idle}` configuration parameter is set, this function
   141         *  will be added to the list of Idle loop functions.  When called from the
   142         *  `Idle` loop, it will transition the CPU into the idle mode specified
   143         *  by the `{@link #idleMode}` configuration parameter.  The CPU will stay
   144         *  in the corresponding low power mode until the next interrupt occurs.
   145         */
   146        @DirectCall
   147        Void idleCPU();
   148
   149        /*!
   150         *  ======== changeIdleMode ========
   151         *  Change the idleMode used for idling the CPU
   152         *
   153         *  This function does not immediately affect the state of the CPU, but
   154         *  defines the idleMode that will be invoked at subsequent opportunities
   155         *  SYS/BIOS has to idle the CPU.
   156         *
   157         *  Changing the `idleMode` at runtime requires that `{@link #idle}` be
   158         *  enabled, the initial `{@link #idleMode}` is defined, and
   159         *  `{@link #allowDynamicMode}` is specified in the application
   160         *  configuration.  For example:
   161         *
   162         *  @p(code)
   163         *  var Power = xdc.useModule('ti.sysbios.family.msp430.Power');
   164         *  Power.idle = true;
   165         *  Power.idleMode = Power.LPM3;
   166         *  Power.allowDynamicMode = true;
   167         *  @p
   168         */
   169        @DirectCall
   170        Void changeIdleMode(Power.IdleMode mode);
   171
   172        /*!
   173         *  ======== sleepCPU ========
   174         *  Function called by the application to sleep the CPU
   175         *
   176         *  This function currently supports the `LPM4.5` sleep mode only, and
   177         *  only on MSP430 devices that support this mode.  To be effective, the
   178         *  device I/Os MUST be properly configured before `LPM4.5` is activated,
   179         *  otherwise there may be excessive current draw, which could be higher
   180         *  than before this function is called.  The proper configuration of I/Os
   181         *  is device, application, and board specific.  The caller of this
   182         *  function has two options:
   183         *
   184         *     1) Prepare the device I/Os, and any (non-reset) wakeup interrupts
   185         *        prior to  calling this function, or
   186         *     2) Write a function for this purpose, and configure it as the
   187         *        optional `{@link sleepPrepFunction}`, that `Power_sleepCPU()`
   188         *        should call before transitioning to `LPM4.5`.
   189         */
   190        @DirectCall
   191        Void sleepCPU(SleepMode sleepMode);
   192
   193        /*! @_nodoc
   194         *  ======== getModeChangeFlag ========
   195         *  Retrieve flag indicating whether the application changed the idleMode
   196         */
   197        @DirectCall
   198        UInt getModeChangeFlag();
   199
   200    internal:
   201
   202        /*
   203         *  ======== defaultSleepPrepFunction ========
   204         *  Default (NOP) function to be called to prepare device I/Os for sleep
   205         */
   206        Void defaultSleepPrepFunction();
   207
   208        /*
   209         *  ======== blockedTaskFunction ========
   210         *  Function to call when Idle not used, and plugging Task.allBlockedFunc
   211         */
   212        Void blockedTaskFunction();
   213
   214        /*
   215         *  ======== Module_State ========
   216         */
   217        struct Module_State {
   218            UInt idleMode;          /* idle depth to invoke in Power_idle() */
   219            Bool newMode;           /* flag indicating idleMode has just changed */
   220        }
   221    }
   222    /*
   223     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:26; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   224
   225     */
   226


module ti.sysbios.family.msp430.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.family.msp430;
    37
    38    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    39    {
    40    }
    41
    42
    43    /*
    44     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:26; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    45
    46     */
    47


module ti.sysbios.family.msp430.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.msp430;
    38
    39    /*!
    40     *  ======== TaskSupport ========
    41     *  MSP430 Task Support Module.
    42     */
    43    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    44    {
    45        /*! default Task stack size. */
    46        override readonly config SizeT defaultStackSize = 512;
    47
    48        /*! required stack alignment (in MAUs). */
    49        override readonly config UInt stackAlignment = 2;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:26; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.family.msp430.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.msp430;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43
    44    import ti.sysbios.interfaces.ITimer;
    45
    46    /*!
    47     *  ======== Timer ========
    48     *  MSP430 Timer Peripherals Manager
    49     *
    50     *  This module manages the timer peripherals available on MSP430 devices
    51     *  (see {@link ./doc-files/TimerTables.html Timer Mapping Tables} for
    52     *  supported device information).
    53     *
    54     *  The Timer module supports the timer in 'one shot', 'continuous', and
    55     *  'dynamic' modes.
    56     *
    57     *  In 'one shot' mode, a timer function will "fire" (run) when the timer
    58     *  period expires. In 'one shot' mode this will only happen once.
    59     *
    60     *  In 'continuous' mode, the specified timer function will "fire" every
    61     *  time the period expires, throughout the lifetime of the program.
    62     *
    63     *  In 'dynamic' mode, the specified timer function will "fire" every
    64     *  time the period expires.  But the period of the timer can be changed
    65     *  dynamically, to correspond to the next tick interrupt needed from the
    66     *  timer.  This mode is used by the SYS/BIOS
    67     *  {@link ti.sysbios.knl.Clock Clock} module for implementing
    68     *  dynamic tick suppression, to reduce the number of interrupts from the
    69     *  timer to the minimum required for currently scheduled timeouts.
    70     *
    71     *  NOTE: In the current implementation on MSP430 Timers cannot be
    72     *  created dynamically at runtime by the application.  Timers must be
    73     *  created statically in the application configuration.
    74     *
    75     *  @p(html)
    76     *  <h3> Calling Context </h3>
    77     *  <table border="1" cellpadding="3">
    78     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    79     *  </colgroup>
    80     *
    81     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    82     *  <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    83     *    <!--                                                          -->
    84     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    85     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    87     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #Params_init}             </td><td>   N    </td>
    89     *  <td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #construct}               </td><td>   N    </td>
    91     *  <td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #create}                  </td><td>   N    </td>
    93     *  <td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
    95     *  <td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #destruct}                </td><td>   N    </td>
    97     *  <td>   N    </td><td>   N    </td><td>   N    </td><td>   N    </td></tr>
    98     *    <tr><td> {@link #getCount}                </td><td>   Y    </td>
    99     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   100     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
   101     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #getFunc}                 </td><td>   Y    </td>
   103     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
   105     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td>
   107     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #setFunc}                 </td><td>   Y    </td>
   109     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   110     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   111     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   112     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   113     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   114     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   115     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   116     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   117     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   118     *    <tr><td colspan="6"> Definitions: <br />
   119     *       <ul>
   120     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   121     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   122     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   123     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   124     *           <ul>
   125     *             <li> In your module startup after this module is started
   126     *  (e.g. Timer_Module_startupDone() returns TRUE). </li>
   127     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   128     *             <li> During main().</li>
   129     *             <li> During BIOS.startupFxns.</li>
   130     *           </ul>
   131     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   132     *           <ul>
   133     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   134     *             <li> In your module startup before this module is started
   135     *  (e.g. Timer_Module_startupDone() returns FALSE).</li>
   136     *           </ul>
   137     *       </ul>
   138     *    </td></tr>
   139     *
   140     *  </table>
   141     *  @p
   142     *
   143     *  @p(html)
   144     *  <h3> Timer Mapping Tables </h3>
   145     *  <p>
   146     *  The Timer module allows the user to use and configure the various timers
   147     *  that exist on a particular device.  This is achieved by specifying a timer
   148     *  ID when statically creating the Timer instance.
   149     *  A convention is used to assign logical IDs to physical timers.  ID '0'
   150     *  corresponds to the first Timer_A peripheral (TA0).  ID '1' is assigned to
   151     *  the next Timer_A (TA1), until there are no more Timer_A peripherals.  Then
   152     *  the next ID is assigned to the first Timer_B peripheral (if present), and
   153     *  so on.
   154     *  These tables are provided to show which timers map to which timer IDs.
   155     *  </p>
   156     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables}
   157     *  @p
   158     */
   159    @InstanceFinalize       /* To cleanup */
   160    @InstanceInitError      /* To report unavailability of timer */
   161    @ModuleStartup          /* To configure static timers */
   162
   163    module Timer inherits ti.sysbios.interfaces.ITimer
   164    {
   165        /*! override supportsDynamic - this Timer does support RunMode_DYNAMIC */
   166        override metaonly config Bool supportsDynamic = true;
   167
   168        /*! override defaultMode - use RunMode_DYNAMIC by default */
   169        override metaonly config Bool defaultDynamic = true;
   170
   171        // -------- Module Types --------
   172
   173        /*! Lists of input clock sources for timers */
   174        enum Source {
   175            Source_ACLK,                    /*! ACLK */
   176            Source_SMCLK,                   /*! SMCLK */
   177            Source_EXTERNAL,                /*! External clock */
   178            Source_EXTERNAL_INVERTED        /*! Inverted external clock */
   179        };
   180
   181        /*! Max value of Timer period for PeriodType_COUNTS */
   182        const UInt MAX_PERIOD = 0x0000ffff;
   183
   184        /*! @_nodoc
   185         *  Min instructions to use in trigger().
   186         */
   187        const Int MIN_SWEEP_PERIOD = 1;
   188
   189        /*! Timer Configuration struct.
   190         *
   191         *  @field(source)  Timer clock source.
   192         */
   193        struct Control {
   194            UInt source;   /*! 0x100=ACLK, 0x200=SMCLK, 0=EXT, 0x300=EXT_INVERT */
   195        };
   196
   197        /*! @_nodoc */
   198        @XmlDtd
   199        metaonly struct BasicView {
   200            Ptr         halTimerHandle;
   201            String      label;
   202            UInt        id;
   203            Control     configuration;
   204            String      startMode;
   205            String      runMode;
   206            UInt        period;
   207            String      periodType;
   208            Bool        synchronous;
   209            UInt        intNum;
   210            String      tickFxn[];
   211            UArg        arg;
   212            UInt        frequency;
   213            String      hwiHandle;
   214        };
   215
   216        /*! @_nodoc */
   217        metaonly struct DeviceView {
   218            UInt        id;
   219            String      device;
   220            String      devAddr;
   221            UInt        intNum;
   222            String      runMode;
   223            UInt        period;
   224            UInt        currCount;
   225            UInt        remainingCount;
   226            UInt        prevThreshold;
   227            String      state;
   228        };
   229
   230        /*! @_nodoc */
   231        metaonly struct ModuleView {
   232            String      availMask;      /* available 32-bit timer halves */
   233        }
   234
   235        /*! @_nodoc */
   236        @Facet
   237        metaonly config ViewInfo.Instance rovViewInfo =
   238            ViewInfo.create({
   239                viewMap: [
   240                [
   241                    'Basic',
   242                    {
   243                        type: ViewInfo.INSTANCE,
   244                        viewInitFxn: 'viewInitBasic',
   245                        structName: 'BasicView'
   246                    }
   247                ],
   248                [
   249                    'Device',
   250                    {
   251                        type: ViewInfo.INSTANCE,
   252                        viewInitFxn: 'viewInitDevice',
   253                        structName: 'DeviceView'
   254                    }
   255                ],
   256                [
   257                    'Module',
   258                    {
   259                        type: ViewInfo.MODULE,
   260                        viewInitFxn: 'viewInitModule',
   261                        structName: 'ModuleView'
   262                    }
   263                ],
   264                ]
   265            });
   266
   267        /*!
   268         *  ======== E_invalidTimer ========
   269         *  Error raised when specified timer id is not supported
   270         */
   271        config Error.Id E_invalidTimer = {
   272            msg: "E_invalidTimer: Invalid Timer Id %d"
   273        };
   274
   275        /*!
   276         *  ======== E_notAvailable ========
   277         *  Error raised when requested timer is in use
   278         */
   279        config Error.Id E_notAvailable = {
   280            msg: "E_notAvailable: Timer not available %d"
   281        };
   282
   283        /*!
   284         *  ======== E_cannotSupport ========
   285         *  Error raised when requested period is not supported
   286         */
   287        config Error.Id E_cannotSupport = {
   288            msg: "E_cannotSupport: Timer cannot support requested period %d"
   289        };
   290
   291        /*!
   292         *  ======== E_runtimeCreate ========
   293         *  Error raised when dynamic Timer create is attempted
   294         */
   295        config Error.Id E_runtimeCreate = {
   296            msg: "E_runtimeCreate: Runtime Timer create is not supported %d"
   297        };
   298
   299        /*!
   300         *  ======== anyMask ========
   301         *  Mask of available timers
   302         *
   303         *  This mask is used to identify the timers that can be used when
   304         *  Timer_create() is called with an id equal to
   305         *  {@link Timer#ANY Timer_ANY}.
   306         */
   307        config UInt anyMask = 0x7;
   308
   309        /*!
   310         *  ======== keepAwake ========
   311         *  Wakeup (enable) CPU when Timer ISR returns
   312         *
   313         *  If set to `true`, all Timer instances keep the CPU awake upon
   314         *  return from interrupt.
   315         */
   316        config Bool keepAwake = false;
   317
   318        /*!
   319         *  ======== oneShotStub ========
   320         *  @_nodoc
   321         *
   322         *  @param(arg)     Unused.
   323         */
   324        Void oneShotStub(UArg arg);
   325
   326        /*!
   327         *  ======== oneShotNestStub ========
   328         *  @_nodoc
   329         *
   330         *  @param(arg)     Unused.
   331         */
   332        Void oneShotNestStub(UArg arg);
   333
   334        /*!
   335         *  ======== periodicStub ========
   336         *  @_nodoc
   337         *
   338         *  @param(arg)     Unused.
   339         */
   340        Void periodicStub(UArg arg);
   341
   342        /*!
   343         *  ======== periodicNestStub ========
   344         *  @_nodoc
   345         *
   346         *  @param(arg)     Unused.
   347         */
   348        Void periodicNestStub(UArg arg);
   349
   350        /*!
   351         *  ======== getHandle ========
   352         *  @_nodoc
   353         *  Used by TimestampProvider module to get hold of timer handle used by
   354         *  Clock.
   355         *
   356         *  @param(id)      timer Id.
   357         */
   358        Handle getHandle(UInt id);
   359
   360    instance:
   361
   362        /*! Hwi Params for Hwi Object. Default is null. */
   363        config Hwi.Params *hwiParams = null;
   364
   365        /*! Clock source input select. Default is ACLK. */
   366        config Source clockSource = Source_ACLK;
   367
   368        /*! Selected clock source is synchronous to CPU clock? Default is false. */
   369        config Bool synchronous = false;
   370
   371        /*! Enable nesting of other interrupts on top of this Timer's ISR? */
   372        config Bool nesting = false;
   373
   374        /*! Previous threshold count value. */
   375        config UInt prevThreshold = 0;
   376
   377        /*! Control register configuration. Default source = ACLK. */
   378        config Control controlRegInit = {source: Source_ACLK};
   379
   380        /*!
   381         *  ======== reconfig ========
   382         *  Modify timer instances at runtime
   383         *
   384         *  @param(timerParams)     timer Params
   385         *  @param(tickFxn)         function that runs when timer expires.
   386         */
   387        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   388
   389
   390    internal:   /* not for client use */
   391
   392        /*!
   393         *  ======== noStartupNeeded ========
   394         *  Flag used to prevent misc code from being brought in
   395         *  un-necessarily
   396         */
   397        config UInt startupNeeded = false;
   398
   399        /*! Information about timer */
   400        struct TimerDevice {
   401            UInt intNum;
   402            Ptr  baseAddr;
   403        };
   404
   405        /*!
   406         *  ======== numTimerDevices ========
   407         *  The number of physical timers on the device
   408         */
   409        config Int numTimerDevices;
   410
   411        struct Instance_State {
   412            Bool                    staticInst;
   413            Int                     id;
   414            UInt                    controlRegInit;
   415            ITimer.RunMode          runMode;
   416            ITimer.StartMode        startMode;
   417            UInt                    period;
   418            ITimer.PeriodType       periodType;
   419            UInt                    intNum;
   420            UArg                    arg;
   421            Hwi.FuncPtr             tickFxn;
   422            Types.FreqHz            frequency;
   423            Hwi.Handle              hwi;
   424            UInt                    prevThreshold;
   425            Bool                    synchronous;
   426        }
   427
   428        struct Module_State {
   429            UInt            availMask;      /* available peripherals */
   430            TimerDevice     device[];       /* timer device information */
   431            Handle          handles[];      /* array of handles based on id */
   432        }
   433    }
   434    /*
   435     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   436
   437     */
   438


module ti.sysbios.family.msp430.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.msp430;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *  MSP430 Timestamp Provider
    43     *
    44     *  @p(html)
    45     *  <h3> Calling Context </h3>
    46     *  <table border="1" cellpadding="3">
    47     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    48     *
    49     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    50     *    <!--                                                                                                                 -->
    51     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    54     *
    55     *  </table>
    56     *  @p
    57     */
    58
    59    @ModuleStartup          /* To get Clock Timer Handle */
    60
    61    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    62    {
    63        // -------- Module Types --------
    64
    65        /*! Input clock sources for dedicated Timestamp timer */
    66        enum Source {
    67            Source_ACLK,                    /*! ACLK */
    68            Source_SMCLK                    /*! SMCLK */
    69        };
    70
    71        /*!
    72         *  ======== timerId ========
    73         *  Id of the timer to use for creating timestamps
    74         *
    75         *  A value of {@link Timer#ANY Timer.ANY} (-1) indicates any timer
    76         *  supported by {@link Timer} is ok.
    77         */
    78        config UInt timerId = Timer.ANY;
    79
    80        /*!
    81         *
    82         *  ======== useClockTimer ========
    83         *  Use the same timer as Clock
    84         *
    85         *  Set this parameter when you want TimestampProvider to use the same
    86         *  timer as the BIOS {@link ti.sysbios.knl.Clock Clock} module.
    87         *
    88         *  This parameter overrides the {@link #timerId timeId} setting.
    89         */
    90        config Bool useClockTimer;
    91
    92        /*!
    93         *
    94         *  ======== clockSource ========
    95         *  Input clock source for dedicated timer
    96         *
    97         *  If the TimestampProvider is to use a different timer than the one
    98         *  used by the {@link ti.sysbios.knl.Clock Clock} module, this
    99         *  parameter specifies the input clock source for that dedicated timer.
   100         *
   101         *  For example, to use a dedicated timer for Timestamps, and to have it
   102         *  run off of SMCLK, add the following to the application config script:
   103         *
   104         *  @p(code)
   105         *  var Timestamp = xdc.useModule('ti.sysbios.family.msp430.TimestampProvider');
   106         *  Timestamp.useClockTimer = false;
   107         *  Timestamp.clockSource = Timestamp.Source_SMCLK;
   108         *  @p
   109         */
   110        config Source clockSource = Source_ACLK;
   111
   112        /*!
   113         *  ======== startTimer ========
   114         *  Function that starts timer before main
   115         *
   116         *  @_nodoc Internal use.
   117         */
   118        Void startTimer();
   119
   120        /*!
   121         *  ======== rolloverFunc ========
   122         *  Timer rollover interrupt handler
   123         *
   124         *  @_nodoc Internal use.
   125         */
   126        Void rolloverFunc(UArg unused);
   127
   128    internal:   /* not for client use */
   129
   130        /*
   131         *  ======== Module_State ========
   132         */
   133        struct Module_State {
   134            Timer.Handle    timer;          /* timer instance used */
   135            volatile UInt32 rollovers;      /* timer rollover counts */
   136        }
   137    }
   138    /*
   139     *  @(#) ti.sysbios.family.msp430; 1, 0, 0, 0,157; 6-15-2011 16:25:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   140
   141     */
   142


module ti.sysbios.family.windows.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36
    37
    38    package ti.sysbios.family.windows;
    39
    40    import xdc.runtime.Assert;
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Error;
    43    import xdc.runtime.IHeap;
    44    import xdc.runtime.Log;
    45
    46    /*!
    47     *  ======== Hwi ========
    48     *  Windows emulation Hardware Interrupt Support Module
    49     *
    50     *  This Hwi module provides Windows emulation specific implementations of
    51     *  the APIs defined in {@link ti.sysbios.interfaces.IHwi IHwi}.
    52     *
    53     *  Additional Windows emulation specific APIs are also provided.
    54     *
    55     *  @a(NOTE)
    56     *  In this Hwi module implementation, the instance config parameter value
    57     *  {@link #MaskingOption_LOWER} is equivalent to {@link #MaskingOption_SELF}.
    58     *  Statically configuring a Hwi object's {@link #Params.maskSetting} to
    59     *  {@link #MaskingOption_LOWER} will result in the generation of a benign
    60     *  build warning. Dynamic usages of {@link #MaskingOption_LOWER} will be
    61     *  silently converted to {@link #MaskingOption_SELF}.
    62     *
    63     *  @p(html)
    64     *  <h3> Calling Context </h3>
    65     *  <table border="1" cellpadding="3">
    66     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    67     *
    68     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    69     *    <!--                                                                                                                 -->
    70     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #disableIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enableIER}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #getHandle}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> {@link #plug}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    82     *    <tr><td> {@link #restoreIER}       </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #reconfig}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td colspan="6"> Definitions: <br />
    92     *       <ul>
    93     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    94     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    95     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    96     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    97     *           <ul>
    98     *             <li> In your module startup after this module is started (e.g. Hwi_Module_startupDone() returns TRUE). </li>
    99     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   100     *             <li> During main().</li>
   101     *             <li> During BIOS.startupFxns.</li>
   102     *           </ul>
   103     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   104     *           <ul>
   105     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   106     *             <li> In your module startup before this module is started (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   107     *           </ul>
   108     *       </ul>
   109     *    </td></tr>
   110     *  </table>
   111     *  @p
   112     *
   113     */
   114
   115    @Template("./Hwi.xdt")  /* generates the dispatcher */
   116    @ModuleStartup          /* plugs signals statically plugged using Hwi_plug  */
   117
   118    module Hwi inherits ti.sysbios.interfaces.IHwi
   119    {
   120        // -------- Module Constants --------
   121
   122        //! Dispatcher supports 16 interrupts.
   123        const Int NUM_INTERRUPTS = 16;
   124
   125        // -------- Module Types --------
   126
   127        //! @_nodoc Hwi plug function type definition.
   128        typedef Void (*PlugFuncPtr)(UInt);
   129
   130        //! Isr function type definition.
   131        typedef Void (*IsrFxn)(UInt);
   132
   133        /*! Assert: invalid interrupt number.
   134         *
   135         *  Interrupt number must be greater than or equal to 0 and less
   136         *  than {@link #NUM_INTERRUPTS}.
   137         *
   138         *  @a(Raised_In)
   139         *  @p(html)
   140         *  {@link #disableInterrupt}<br />
   141         *  {@link #enableInterrupt}<br />
   142         *  {@link #plug}<br />
   143         *  {@link ti.sysbios.interfaces.IHwi#post}<br />
   144         *
   145         *  @a(See_Also)
   146         *  @p(html)
   147         *  {@link xdc.runtime.Assert}<br />
   148         *  {@link xdc.runtime.Diags}<br />
   149         *  @p
   150         */
   151        config Assert.Id A_interNum = {
   152            msg: "A_interNum: interrupt number must be less then NUM_INTERRUPTS"
   153        };
   154
   155        /*! Assert: there must be a pending interrupt
   156         *
   157         *  The Hwi module decided to take an interrupt, but upon inspecting
   158         *  the IER and IFR registers did not find an enabled pending interrupt.
   159         */
   160        config Assert.Id A_noPendingIntr = {
   161            msg: "A_noPendingIntr: there must be a pending interrupt"
   162        };
   163
   164        /*! Assert: an unplugged interrupt was raised.
   165         *
   166         *  An interrupt was raised which does not have an ISR plugged into
   167         *  the Interrupt Service Table (IST).
   168         *
   169         *  @a(Raised_In)
   170         *  @p(html)
   171         *  {@link #post}<br />
   172         *  @p
   173         */
   174        config Assert.Id A_pluggedIntr = {
   175            msg: "interrupt must be plugged"
   176        };
   177
   178        /*! Error: memory allocation request failed.
   179         *
   180         *  A request into the Windows runtime library for memory has failed.
   181         *
   182         *  @a(Raised_In)
   183         *  @p(html)
   184         *  {@link #startup}<br />
   185         *  @p
   186         */
   187        config Error.Id E_calloc = {
   188            msg: "calloc failed"
   189        };
   190
   191        /*! Error: CreateEvent failed.
   192         *
   193         *  A CreateEvent call into the Win32 API has failed.
   194         *
   195         *  @a(Raised_In)
   196         *  @p(html)
   197         *  {@link #startup}<br />
   198         *  @p
   199         */
   200        config Error.Id E_event = {
   201            msg: "CreateEvent failed"
   202        };
   203
   204        /*!
   205         *  Error raised when Hwi is already defined
   206         */
   207        config Error.Id E_alreadyDefined = {
   208            msg: "E_alreadyDefined: Hwi already defined: intr# %d"
   209        };
   210
   211        /*!
   212         *  Issued just prior to Hwi function invocation (with interrupts disabled)
   213         */
   214        config Log.Event LM_begin = {
   215            mask: Diags.USER1 | Diags.USER2,
   216            msg: "LM_begin: hwi: 0x%x, func: 0x%x, preThread: %d, intNum: %d"
   217        };
   218
   219        /*!
   220         *  Issued just after return from Hwi function (with interrupts disabled)
   221         */
   222        config Log.Event LD_end = {
   223            mask: Diags.USER2,
   224            msg: "LD_end: hwi: 0x%x"
   225        };
   226
   227        /*! Log: missed interrupt detected
   228         *
   229         *  An interrupt is being raised which has a previous instance
   230         *  recorded in the IFR register still waiting to be serviced.
   231         *
   232         *  @a(Raised_In)
   233         *  @p(html)
   234         *  {@link #post}<br />
   235         *  @p
   236         */
   237        config Log.Event LW_missedIntr = {
   238            mask: Diags.USER3,
   239            msg: "Warning: LW_missedIntr: missed interrupt detected: %d"
   240        };
   241
   242        // -------- Module Parameters --------
   243
   244        /*! Non-dispatched interrupt object.
   245         *
   246         *  Provided so that XGCONF users can easily plug non-dispatched
   247         *  interrupts.
   248         */
   249        metaonly struct NonDispatchedInterrupt {
   250            Int             intNum;         //! interrupt number
   251            PlugFuncPtr     fxn;            //! plugged ISR function
   252            Bool            enableInt;      //! interrupt enable flag
   253            Int             eventId;        //! source event id
   254        };
   255
   256        /*! Non-dispatched interrupt array.
   257         *
   258         *  Provided so that XGCONF users can easily plug non-dispatched
   259         *  interrupts.
   260         */
   261        metaonly config NonDispatchedInterrupt nonDispatchedInterrupts[string];
   262
   263        // -------- Module Functions --------
   264
   265        /*!
   266         *  ======== disableIER ========
   267         *  Disable certain maskable interrupts.
   268         *
   269         *  Atomically disables specific interrupts by clearing the bits
   270         *  specified by mask in the Interrupt Enable Register (IER).
   271         *
   272         *  The IER bits to be cleared should be set to 1 in the mask.
   273         *
   274         *  @param(mask)    Bitmask of interrupts to disable.
   275         *  @b(returns)     Previous IER settings bitmask.
   276         */
   277        Bits16 disableIER(Bits16 mask);
   278
   279        /*!
   280         *  ======== enableIER ========
   281         *  Enable certain maskable interrupts.
   282         *
   283         *  Atomically enables specific interrupts by setting the bits
   284         *  specified by mask in the Interrupt Enable Register (IER).
   285         *
   286         *  The IER bits to be set should be set to 1 in the mask.
   287         *
   288         *  @param(mask)    Bitmask of interrupts to enable.
   289         *  @b(returns)     Previous IER settings bitmask.
   290         */
   291        Bits16 enableIER(Bits16 mask);
   292
   293        /*!
   294         *  ======== restoreIER ========
   295         *  Restore maskable interrupts to the state they were in
   296         *  when either disableIER() or enableIER() was called.
   297         *
   298         *  Atomically writes the given mask to the IER register. Typically used
   299         *  to restore the IER register to the state returned from a call to
   300         *  either {@link #disableIER()} or {@link #enableIER()}.
   301         *
   302         *  @param(mask)    Bitmask of interrupts to restore.
   303         *  @b(returns)     Previous IER settings bitmask.
   304         */
   305        Bits16 restoreIER(Bits16 mask);
   306
   307        /*!
   308         *  ======== getHandle ========
   309         *  Return a pointer to an Hwi instance object.
   310         *
   311         *  @param(intNum)  Interrupt number.
   312         */
   313        Handle getHandle(UInt intNum);
   314
   315        /*!
   316         *  @_nodoc
   317         *  ======== inUseMeta ========
   318         *  Check for Hwi already in use.
   319         *
   320         *  For internal SYS/BIOS use only. Should be called prior
   321         *  to any internal Hwi.create().
   322         *
   323         *  @param(intNum)  Interrupt number.
   324         */
   325        metaonly Bool inUseMeta(UInt intNum);
   326
   327        /*!
   328         *  @_nodoc
   329         *  ======== plug ========
   330         *  Plug an interrupt vector with an ISR address at runtime.
   331         *
   332         *  Writes the ISR address into the Interrupt Service Table (IST)
   333         *  at the address corresponding to the `intNum`. This function
   334         *  does not enable the interrupt. Use {@link #enableIER()} to
   335         *  enable the interrupt.
   336         *
   337         *  @param(intNum) Interrupt number. The interrupt number must be
   338         *      in the range 0 - ({@link #NUM_INTERRUPTS} - 1).
   339         *  @param(fxn) Pointer to ISR function. The ISR function
   340         *      pointer cannot be NULL.
   341         *
   342         *  @a(Asserts)
   343         *  @p(html)
   344         *  {@link #A_interNum}<br />
   345         *  @p
   346         *
   347         *  @a(See_Also)
   348         *  {@link #enableIER()}
   349         */
   350        Void plug(UInt intNum, PlugFuncPtr fxn);
   351
   352        /*!
   353         *  ======== plugMeta ========
   354         *  Plug an interrupt vector with an ISR address at config time.
   355         *
   356         *  @param(intNum) Interrupt number. The interrupt number must be
   357         *      in the range 0 - ({@link #NUM_INTERRUPTS} - 1).
   358         *  @param(fxn) Pointer to ISR function. The ISR function
   359         *      pointer cannot be NULL.
   360         */
   361        metaonly Void plugMeta(UInt intNum, PlugFuncPtr fxn);
   362
   363    instance:
   364
   365        /*!
   366         *  Dispatcher auto-nesting interrupt disable mask.
   367         *
   368         *  When the dispatcher's auto interrupt nesting support feature
   369         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   370         *  this mask defines which IER bits are disabled prior to invoking
   371         *  the user's ISR function with GIE = 1.
   372         *
   373         *  disableMask bits set to 1 correspond to IER bits that will be cleared
   374         *  prior to invoking the ISR.
   375         *
   376         *  The value of this mask is normally auto-calculated based on the
   377         *  value of the maskSetting. However, manual setting of this
   378         *  mask is enabled by setting the maskSetting to
   379         *  {@link #MaskingOption MaskingOption_BITMASK}.
   380         *
   381         *  The default value is derived from the
   382         *  {@link #MaskingOption MaskingOption_SELF}
   383         *  maskSetting.
   384         */
   385        config Bits16 disableMask = 0;
   386
   387        /*!
   388         *  Dispatcher auto-nesting interrupt restore mask.
   389         *
   390         *  When the dispatcher's auto interrupt nesting support feature
   391         *  is enabled (see {@link #dispatcherAutoNestingSupport}),
   392         *  this mask defines which IER bits are restored to their previous
   393         *  setting upon return from the user's ISR function.
   394         *
   395         *  restoreMask bits set to 1 correspond to IER bits that will be restored.
   396         *
   397         *  The value of this mask is normally auto-calculated based on the
   398         *  value of the maskSetting. However, manual setting of this
   399         *  mask is enabled by setting the maskSetting to
   400         *  {@link #MaskingOption MaskingOption_BITMASK}.
   401         *
   402         *  The default value is derived from the
   403         *  {@link #MaskingOption MaskingOption_SELF}
   404         *  maskSetting.
   405         */
   406        config Bits16 restoreMask = 0;
   407
   408        /*!
   409         *  Interrupt priority. Not supported on this target.
   410         */
   411        override config Int priority = 0;
   412
   413        /*!
   414         *  ======== reconfig ========
   415         *  Reconfigure a dispatched interrupt.
   416         */
   417        Void reconfig(FuncPtr fxn, const Params *params);
   418
   419    internal:   /* not for client use */
   420
   421        /*
   422         * Swi and Task module function pointers.
   423         * Used to decouple Hwi from Swi and Task when
   424         * dispatcherSwiSupport or
   425         * dispatcherTaskSupport is false.
   426         */
   427        config UInt (*swiDisable)();
   428        config Void (*swiRestoreHwi)(UInt);
   429        config UInt (*taskDisable)();
   430        config Void (*taskRestoreHwi)(UInt);
   431
   432        /*
   433         *  ======== dispatch ========
   434         *  Interrupt Dispatcher
   435         */
   436        Void dispatch(UInt intNum);
   437
   438        /*
   439         *  ======== init ========
   440         */
   441        Void init();
   442
   443        /*
   444         *  ======== unPluggedInterrupt ========
   445         *  unPlugged interrupt handler
   446         */
   447        Void unPluggedInterrupt(UInt num);
   448
   449        /* const array to hold all HookSet objects */
   450        config HookSet hooks[length] = [];
   451
   452        /*! Meta World Only Hwi Configuration Object. */
   453        metaonly struct InterruptObj {
   454            String name;            /* symbol used for vector table entry */
   455            Bool        used;           /* Interrupt already defined? */
   456            Bool        useDispatcher;  /* Should dispatcher handle this intr?*/
   457            FuncPtr     fxn;            /* Dispatched ISR function. */
   458            PlugFuncPtr pfxn;           /* "Hwi_plug'd" ISR function. */
   459        };
   460
   461        /*!
   462         *  Meta-only array of interrupt objects.
   463         *  This meta-only array of Hwi config objects is initialized
   464         *  in Hwi.xs:module$meta$init().
   465         */
   466        metaonly config InterruptObj interrupt[NUM_INTERRUPTS];
   467
   468        struct PrivateData;
   469
   470        struct Instance_State {
   471            Bits16          disableMask;    /* Interrupts to mask during ISR.   */
   472            Bits16          restoreMask;    /* Interrupts to restore after ISR. */
   473            UArg            arg;            /* Argument to Hwi function.        */
   474            FuncPtr         fxn;            /* Hwi function.                    */
   475            Irp             irp;            /* current IRP                      */
   476            Ptr             hookEnv[];
   477        };
   478
   479        struct Module_State {
   480            Bits16          ierMask;        /* Initial IER mask                 */
   481            Handle          dispatchTable[NUM_INTERRUPTS]; /* dispatch table   */
   482            Bool            GIE;
   483            Bits16          IER;
   484            Bits16          IFR;
   485            UInt            intrNum;
   486            IsrFxn          IST[NUM_INTERRUPTS];
   487            PrivateData     *privateData;   /* Windows types not allowed in xdc */
   488        };
   489    }
   490    /*
   491     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   492
   493     */
   494


package ti.sysbios.family.windows

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39
    40    /*! Native Windows SYS/BIOS Support
    41     *
    42     *  This package supports SYS/BIOS programs which are built and run as
    43     *  native Windows executables. This enables applications to be
    44     *  developed and tested on Windows using native Windows development
    45     *  tools.
    46     *
    47     *  Although this package emulates timers and interrupts, special
    48     *  consideration must be given to the fact that Windows is not a
    49     *  real-time operating system. A program will not run in real-time
    50     *  nor is it cycle equivalent to a target program.
    51     *
    52     *  On Windows, the timer period may be programmed to as little as
    53     *  one millisecond, however, the actual minimum timer period is
    54     *  10 - 15 milliseconds. This latency results from the Windows clock
    55     *  ticking at 10 milliseconds with additional delays in the Windows
    56     *  kernel. See below for more details on clock rate considerations.
    57     *
    58     *  This package emulates the C64+ DSP core with respect to hardware
    59     *  interrupt handling and dispatching. Currently, the only supported
    60     *  platform is host.platform.PC.
    61     *
    62     *  @a(Motivation)
    63     *  You can use SYS/BIOS emulation on Windows to model your application
    64     *  on a high-level operating system before moving to simulators or
    65     *  hardware.
    66     *
    67     *  When developing a software module, such as a codec, a common practice
    68     *  is to first write a "Golden C" version. Once the software is stable,
    69     *  the Golden C version is used as a baseline for porting to specific
    70     *  target platforms.
    71     *
    72     *  When developing the Golden C version, it is often preferable to do
    73     *  this work on a High-Level Operating System (HLOS), such as Windows.
    74     *  This allows the use of HLOS tool-chains for code profiling and
    75     *  validation. Providing a SYS/BIOS Emulation layer that runs on Windows
    76     *  makes this effort more efficient. It allows a native SYS/BIOS application
    77     *  to be built and run as a native Windows executable.
    78     *
    79     *  @a(High_Level_Description)
    80     *  SYS/BIOS emulation is supported by implementing the platform proxy
    81     *  modules for Windows. These modules are contained in the
    82     *  ti.sysbios.family.windows package. These proxy modules provide
    83     *  interfaces for the following:
    84     *
    85     *  @p(blist)
    86     *  - hardware interrupts
    87     *  - thread context switching
    88     *  - general purpose timers
    89     *  - system clock tick counter
    90     *  @p
    91     *
    92     *  To implement these interfaces, some hardware functionality is
    93     *  emulated in the proxy modules because Windows does not allow
    94     *  direct access to the hardware.
    95     *
    96     *  The following figure shows a block diagram of both a C64x+
    97     *  implementation and a Windows implementation.
    98     *
    99     *  @p(html)
   100     *  <img src="./doc-files/emulation.gif" />
   101     *  @p
   102     *
   103     *  Application code written in C that makes only SYS/BIOS API calls
   104     *  should not require any changes. However, any code written for
   105     *  peripheral control will need to be replaced. Peripherals are
   106     *  not modeled in the emulation package.
   107     *
   108     *  The SYS/BIOS Kernel does not require any changes. Through XDC
   109     *  configuration, the kernel binds with the appropriate proxy
   110     *  modules relevant to the target platform (that is, for the
   111     *  Windows platform or a hardware platform).
   112     *
   113     *  When building the application, XDC configuration is used to
   114     *  select the run-time platform. Through configuration options,
   115     *  the application can bind with the appropriate modules that are
   116     *  hardware or emulation specific. This will most likely pertain
   117     *  to peripheral and/or test framework code.
   118     *
   119     *  On hardware platforms, peripheral devices typically raise interrupts
   120     *  to the CPU which then invokes the Hwi dispatcher to service it.
   121     *  To emulate this behavior, the SYS/BIOS emulation package simulates an
   122     *  interrupt that preempts the currently running task and invokes the
   123     *  Hwi dispatcher. This is done asynchronously with respect to SYS/BIOS
   124     *  tasks.
   125     *
   126     *  The Windows emulation package faithfully emulates the SYS/BIOS scheduler
   127     *  behavior. That is to say that task scheduling will occur in the same
   128     *  order on Windows as on hardware. However, interrupts are not real-time.
   129     *  Therefore, interrupt preemption will differ, and this may invoke the
   130     *  scheduler in a different sequence than observed when running on hardware.
   131     *
   132     *  Windows Win32 API functions may be invoked alongside SYS/BIOS API
   133     *  functions. This should be kept to a minimum in order to encourage
   134     *  code encapsulation and to maximize code reuse between hardware and
   135     *  the Windows platform.
   136     *
   137     *  @a(Clock_Rate_Considerations)
   138     *  When running on Windows Emulation, the SYS/BIOS clock is configured to
   139     *  tick much slower. This is necessary because the Windows clock ticks
   140     *  slower than a typical hardware clock. Thus, any code that depends on
   141     *  clock ticks, instead of wall clock duration, should take this into
   142     *  account during the configuration phase.
   143     *
   144     *  For example, if {@link ti.sysbios.knl.Task#sleep Task_sleep(500)} is
   145     *  called on a hardware platform where the SYS/BIOS clock ticks every one
   146     *  millisecond (resulting in a 500 millisecond sleep period), then the
   147     *  sleep period should be normalized for the Windows platform using the
   148     *  following formula:
   149     *
   150     *  @p(code)
   151     *  windowsTicks = 500 / (Clock_tickPeriod / 1000)
   152     *  @p
   153     *
   154     *  where the `Clock_tickPeriod` is the SYS/BIOS clock tick period on Windows.
   155     */
   156    package ti.sysbios.family.windows [2,0,0,0] {
   157        module Hwi;
   158        module IntrinsicsSupport;
   159        module Settings;
   160        module TaskSupport;
   161        module Timer;
   162        module TimestampProvider;
   163    }
   164    /*
   165     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:30; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   166
   167     */
   168


module ti.sysbios.family.windows.Settings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Settings.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.family.windows;
    38
    39
    40    /*!
    41     *  ======== Settings ========
    42     *  Device/Family-specific delegate assignment module for
    43     *  Windows emulation targets.
    44     */
    45    metaonly module Settings inherits ti.sysbios.interfaces.ISettings
    46    {
    47    }
    48    /*
    49     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.family.windows.TaskSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TaskSupport.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.windows;
    39
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Types;
    42
    43
    44    /*!
    45     *  ======== TaskSupport ========
    46     *  Windows Task Support Module.
    47     */
    48
    49    @ModuleStartup  /* generate a call to Task_Module_startup at startup */
    50
    51
    52    module TaskSupport inherits ti.sysbios.interfaces.ITaskSupport
    53    {
    54        // -------- Module Constants --------
    55
    56
    57        // -------- Module Types --------
    58
    59        //! Prototype of task enter and exit functions.
    60        typedef Void (*GlueFxn)();
    61
    62        //! Task function type definition.
    63        typedef Void (*TaskFxn)(UArg, UArg);
    64
    65        //! Isr function type definition.
    66        typedef Void (*IsrFxn)(UInt);
    67
    68        //! Emulation task object.
    69        struct Task;
    70
    71        /*! Error: memory allocation request failed.
    72         *
    73         *  A request into the Windows runtime library for memory has failed.
    74         *
    75         *  @a(Raised_In)
    76         *  @p(html)
    77         *  {@link #start}<br />
    78         *  {@link #startup}<br />
    79         *  @p
    80         */
    81        config Error.Id E_calloc = {
    82            msg: "calloc failed"
    83        };
    84
    85        /*! Error: CreateEvent failed.
    86         *
    87         *  A CreateEvent call into the Win32 API has failed.
    88         *
    89         *  @a(Raised_In)
    90         *  @p(html)
    91         *  {@link #start}<br />
    92         *  {@link #startup}<br />
    93         *  @p
    94         */
    95        config Error.Id E_event = {
    96            msg: "CreateEvent failed"
    97        };
    98
    99        /*! Error: invalid incoming task state.
   100         *
   101         *  A task swap was attempted where the incoming task is in an
   102         *  invalid state.
   103         *
   104         *  @a(Raised_In)
   105         *  @p(html)
   106         *  {@link #swap}<br />
   107         *  @p
   108         */
   109        config Error.Id E_taskState = {
   110            msg: "invalid incoming task state"
   111        };
   112
   113        /*! Error: CreateThread failed.
   114         *
   115         *  A CreateThread call into the Win32 API has failed.
   116         *
   117         *  @a(Raised_In)
   118         *  @p(html)
   119         *  {@link #processInterrupt}<br />
   120         *  {@link #start}<br />
   121         *  @p
   122         */
   123        config Error.Id E_thread = {
   124            msg: "CreateThread failed"
   125        };
   126
   127        /*! Error: WaitForSingleObject failed.
   128         *
   129         *  A WaitForSingleObject call into the Win32 API has failed.
   130         *
   131         *  @a(Raised_In)
   132         *  @p(html)
   133         *  {@link #processInterrupt}<br />
   134         *  {@link #start}<br />
   135         *  @p
   136         */
   137        config Error.Id E_wait = {
   138            msg: "WaitForSingleObject failed"
   139        };
   140
   141
   142        // -------- Module Proxys --------
   143
   144        // -------- Module Parameters --------
   145
   146        //! Default task stack size.
   147        override readonly config SizeT defaultStackSize = 128;
   148
   149        //! Required stack alignment (in MAUs).
   150        override readonly config UInt stackAlignment = 0;
   151
   152        // -------- Module Functions --------
   153
   154
   155    internal:   /* not for client use */
   156
   157        /*
   158         *  ======== enterCS ========
   159         *  Acquire ownership of the emulation gate.
   160         */
   161        Void enterCS();
   162
   163        /*
   164         *  ======== leaveCS ========
   165         *  Release ownership of the emulation gate.
   166         */
   167        Void leaveCS();
   168
   169        /*
   170         *  ======== processInterrupt ========
   171         *  Handle the necessary thread switching and call the interrupt ISR.
   172         */
   173        Void processInterrupt(IsrFxn fxn, UInt intr);
   174
   175
   176        enum State {
   177            State_PREEMPTED,
   178            State_RUNNING,
   179            State_TERMINATING,
   180            State_YIELDED
   181        };
   182
   183        struct PrivateData;
   184
   185        struct TaskData;
   186
   187        struct Module_State {
   188            Task            *currentTask;
   189            PrivateData     *privateData;   /* Windows types not allowed in xdc */
   190        };
   191
   192    }
   193    /*
   194     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   195
   196     */
   197


module ti.sysbios.family.windows.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.windows;
    39
    40    import xdc.runtime.Types;
    41    import xdc.runtime.Error;
    42    import ti.sysbios.interfaces.ITimer;
    43
    44    /*!
    45     *  ======== Timer ========
    46     *  Timer Peripherals Manager for Windows family.
    47     *
    48     *  @p(html)
    49     *  <h3> Calling Context </h3>
    50     *  <table border="1" cellpadding="3">
    51     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    52     *
    53     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    54     *    <!--                                                                                                                 -->
    55     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    56     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    61     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    68     *    <tr><td colspan="6"> Definitions: <br />
    69     *       <ul>
    70     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    71     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    72     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    73     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    74     *           <ul>
    75     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    76     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    77     *             <li> During main().</li>
    78     *             <li> During BIOS.startupFxns.</li>
    79     *           </ul>
    80     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    81     *           <ul>
    82     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    83     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    84     *           </ul>
    85     *       </ul>
    86     *    </td></tr>
    87     *
    88     *  </table>
    89     *  @p
    90     *
    91     */
    92
    93    @ModuleStartup
    94    @InstanceFinalize       /* To cleanup */
    95    @InstanceInitError      /* To report unavailability of timer */
    96
    97    module Timer inherits ti.sysbios.interfaces.ITimer
    98    {
    99        // -------- Module Constants --------
   100
   101        /*! Emulation supports 2 timers. */
   102        const Int NUM_TIMER_DEVICES = 2;
   103
   104        /*! Max value of Timer period for PeriodType_COUNTS*/
   105        const UInt MAX_PERIOD = 0xffffffff;
   106
   107        /*! Error: memory allocation request failed.
   108         *
   109         *  A request into the Windows runtime library for memory has failed.
   110         *
   111         *  @a(Raised_In)
   112         *  @p(html)
   113         *  {@link #startup}<br />
   114         *  @p
   115         */
   116        config Error.Id E_calloc = {
   117            msg: "calloc failed"
   118        };
   119
   120        /*! Error: unsupported timer period
   121         *
   122         *  On Windows, the timer period cannot be less than one millisecond.
   123         *  However, the actual minimum timer period (even when set to one
   124         *  millisecond) is 10 - 15 milliseconds. This latency results from the
   125         *  Windows clock ticking at 10 milliseconds with additional delays in
   126         *  the Windows kernel.
   127         *
   128         *  @a(Raised_In)
   129         *  @p(html)
   130         *  {@link #startup}<br />
   131         *  @p
   132         */
   133        config Error.Id E_cannotSupport = {
   134            msg: "Timer cannot support requested period %d"
   135        };
   136
   137        /*! Error: CreateEvent failed.
   138         *
   139         *  A CreateEvent call into the Win32 API has failed.
   140         *
   141         *  @a(Raised_In)
   142         *  @p(html)
   143         *  {@link #startup}<br />
   144         *  @p
   145         */
   146        config Error.Id E_event = {
   147            msg: "CreateEvent failed"
   148        };
   149
   150        /*! Error: Invalid timer specified.
   151         *
   152         *  An invalid timer id was specified. Timer id must be in the range
   153         *  0 to ({@link #NUM_TIMER_DEVICES} - 1). In the {@link #create()} call,
   154         *  an id of -1 may be used to request any available timer.
   155         *
   156         *  @a(Raised_In)
   157         *  @p(html)
   158         *  {@link #init}<br />
   159         *  {@link #postInit}<br />
   160         *  {@link #start}<br />
   161         *  {@link #stop}<br />
   162         *  @p
   163         */
   164        config Error.Id E_invalidTimer = {
   165            msg: "E_invalidTimer: Invalid Timer Id %d"
   166        };
   167
   168        /*! Error: no timers available.
   169         *
   170         *  A request was made for any available timer, but there are none
   171         *  available at this time.
   172         *
   173         *  @a(Raised_In)
   174         *  @p(html)
   175         *  {@link #postInit}<br />
   176         *  @p
   177         */
   178        config Error.Id E_noneAvailable = {
   179            msg: "no available timer"
   180        };
   181
   182        /*! Error: API not supported on Windows
   183         *
   184         *  This timer API is not supported on Windows.
   185         *
   186         *  @a(Raised_In)
   187         *  @p(html)
   188         *  {@link #trigger}<br />
   189         *  @p
   190         */
   191        config Error.Id E_notSupported = {
   192            msg: "API not supported on Windows"
   193        };
   194
   195        /*! Error: CreateThread failed.
   196         *
   197         *  A CreateThread call into the Win32 API has failed.
   198         *
   199         *  @a(Raised_In)
   200         *  @p(html)
   201         *  {@link #startup}<br />
   202         *  @p
   203         */
   204        config Error.Id E_thread = {
   205            msg: "CreateThread failed"
   206        };
   207
   208        /*! Error: requested timer not available.
   209         *
   210         *  A request was made for a timer, but it is not available at this time.
   211         *  It is currently in use.
   212         *
   213         *  @a(Raised_In)
   214         *  @p(html)
   215         *  {@link #init}<br />
   216         *  {@link #postInit}<br />
   217         *  @p
   218         */
   219        config Error.Id E_notAvailable = {
   220            msg: "E_notAvailable: Timer not available %d"
   221        };
   222
   223        /*! Error: WaitForSingleObject failed.
   224         *
   225         *  A WaitForSingleObject call into the Win32 API has failed.
   226         *
   227         *  @a(Raised_In)
   228         *  @p(html)
   229         *  {@link #processInterrupt}<br />
   230         *  {@link #start}<br />
   231         *  @p
   232         */
   233        config Error.Id E_wait = {
   234            msg: "WaitForSingleObject failed"
   235        };
   236
   237        //! Available mask to be used when select = TIMER_ANY.
   238        config UInt anyMask = 0x3;
   239
   240
   241    internal:   /* not for client use */
   242
   243        struct PrivateData;
   244
   245        struct Instance_State {
   246            Int                     id;
   247            ITimer.RunMode          runMode;
   248            ITimer.StartMode        startMode;
   249            UInt                    period;
   250            ITimer.PeriodType       periodType;
   251            Types.FreqHz            extFreq;
   252            UInt                    intNum;
   253            FuncPtr                 tickFxn;
   254            UArg                    tickFxnArg;
   255            Hwi.Handle              hwi;
   256        };
   257
   258        struct Module_State {
   259            Char            availMask;
   260            Handle          handles[NUM_TIMER_DEVICES];
   261            PrivateData     *privateData;   /* Windows types not allowed in xdc */
   262        };
   263    }
   264    /*
   265     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:30; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   266
   267     */
   268


module ti.sysbios.family.windows.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.family.windows;
    39
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Types;
    42
    43    /*!
    44     *  ======== TimestampProvider ========
    45     *  TimestampProvider implementation for Windows.
    46     *
    47     *  This module provides an implementation on Windows for the
    48     *  {@link xdc.runtime.ITimestampProvider xdc.runtime.ITimestampProvider}
    49     *  interface.
    50     *
    51     *  On Windows, the timestamp counter value is computed from the
    52     *  accumulated CPU user time spent running the SYS/BIOS application.
    53     *  This emulates a hardware timestamp counter by eliminating all
    54     *  the CPU time spent running the Windows kernel and other Windows
    55     *  applications.
    56     *
    57     *  It is important to understand that although Windows uses a
    58     *  real-time counter to accumulate the user time of a process,
    59     *  the accumulated total is updated only once every 10 milliseconds.
    60     *  Therefore, it is quite likely that two consecutive calls to
    61     *  {@link #get32 TimestampProvider_get32()} or
    62     *  {@link #get64 TimestampProvider_get64()} or will return the same
    63     *  value. In fact, the returned value will only change the next time
    64     *  Windows updates the accumulated user time.
    65     *
    66     *  @p(html)
    67     *  <h3> Calling Context </h3>
    68     *  <table border="1" cellpadding="3">
    69     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    70     *
    71     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    72     *    <!--                                                                                                                 -->
    73     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     *
    99     */
   100
   101    module TimestampProvider inherits xdc.runtime.ITimestampProvider
   102    {
   103        /*! Error: GetProcessTimes failed.
   104         *
   105         *  A call to GetProcessTimes in the Win32 API has failed.
   106         *
   107         *  @a(Raised_In)
   108         *  @p(html)
   109         *  {@link #getTimestampCount64}<br />
   110         *  @p
   111         */
   112        config Error.Id E_processTimes = {
   113            msg: "GetProcessTimes failed: %d"
   114        };
   115
   116        /*!
   117         *  ======== get32 ========
   118         *  Return a 32-bit timestamp.
   119         *
   120         *  See the details section above for implementation details.
   121         */
   122        override Bits32 get32();
   123
   124        /*!
   125         *  ======== get64 ========
   126         *  Return a 64-bit timestamp.
   127         *
   128         *  See the details section above for implementation details.
   129         */
   130        override Void get64(Types.Timestamp64* result);
   131
   132        /*!
   133         *  ======== getFreq ========
   134         *  Return the timestamp counter tick rate.
   135         *
   136         *  This function returns the rate, specified in hertz, at which
   137         *  the timestamp counter ticks. In other words, it is how many ticks
   138         *  per second the timestamp counter will tick.
   139         */
   140        override Void getFreq(Types.FreqHz *freq);
   141    }
   142    /*
   143     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,495; 6-15-2011 16:25:30; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   144
   145     */
   146


module ti.sysbios.gates.GateAll

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateAll.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates
    37
    38    import xdc.rov.ViewInfo;
    39
    40    /*!
    41     *  ======== GateAll ========
    42     *  Hwi, Swi & Task Gate
    43     *
    44     *  GateAll uses disabling and enabling of interrupts, Swis and Tasks for the
    45     *  resource locking mechanism. Such a gate guarantees exclusive access to the
    46     *  CPU. This gate can be used whenever the resource is being shared by Tasks,
    47     *  Swis, and/or Hwis.
    48     *
    49     *  The duration between the enter and leave should be as short as possible
    50     *  to minimize Hwi latency.
    51     *
    52     *  GateAll inherits from xdc.runtime.IGateProvider, therefore supports nesting.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    58     *    </colgroup>
    59     *
    60     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    61     *    <th>  Main  </th><th>  Startup  </th></tr>
    62     *    <!--                                                         -->
    63     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    64     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    66     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
    68     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    70     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    72     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
    74     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enter}       </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y**  </td><td>   Y**  </td></tr>
    77     *    <tr><td> {@link #leave}       </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y**  </td><td>   Y**  </td></tr>
    79     *    <tr><td colspan="6"> Definitions: <br />
    80     *       <ul>
    81     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    82     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    83     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    84     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    85     *           <ul>
    86     *             <li> In your module startup after this module is started
    87     *    (e.g. GateAll_Module_startupDone() returns TRUE). </li>
    88     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    89     *             <li> During main().</li>
    90     *             <li> During BIOS.startupFxns.</li>
    91     *           </ul>
    92     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    93     *           <ul>
    94     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    95     *             <li> In your module startup before this module is started
    96     *    (e.g. GateAll_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
    99     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     */
   106
   107    module GateAll inherits xdc.runtime.IGateProvider
   108    {
   109
   110        /*!
   111         *  ======== BasicView ========
   112         *  @_nodoc
   113         */
   114        metaonly struct BasicView {
   115            String label;
   116            Bool    entered;
   117        }
   118
   119        /*!
   120         *  ======== rovViewInfo ========
   121         *  @_nodoc
   122         */
   123        @Facet
   124        metaonly config ViewInfo.Instance rovViewInfo =
   125            ViewInfo.create({
   126                viewMap: [
   127                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   128                ]
   129            });
   130
   131    instance:
   132
   133        /*!
   134         *  @_nodoc
   135         *  ======== enter ========
   136         *  Enter this gate
   137         */
   138        @DirectCall
   139        override IArg enter();
   140
   141        /*!
   142         *  @_nodoc
   143         *  ======== leave ========
   144         *  Leave this gate
   145         */
   146        @DirectCall
   147        override Void leave(IArg key);
   148
   149    internal:
   150
   151        /* -------- Internal Structures -------- */
   152        struct Instance_State {
   153            Bool    entered;        /* set to true on first         */
   154                                    /* GateAll_enter()              */
   155            UInt    hwiKey;         /* storage for key returned     */
   156                                    /* from Hwi_disable()           */
   157            UInt    swiKey;         /* storage for key returned     */
   158                                    /* from Swi_disable()           */
   159        };
   160    }
   161    /*
   162     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   163
   164     */
   165


module ti.sysbios.gates.GateHwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateHwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates
    37
    38    import xdc.rov.ViewInfo;
    39
    40    /*!
    41     *  ======== GateHwi ========
    42     *  Hardware Interrupt Gate.
    43     *
    44     *  GateHwi uses disabling and enabling of interrupts as the resource locking
    45     *  mechanism. Such a gate guarantees exclusive access to the CPU. This gate
    46     *  can be used whenever the resource is being shared by Tasks, Swis, and/or
    47     *  Hwis.
    48     *
    49     *  The duration between the enter and leave should be as short as possible
    50     *  to minimize Hwi latency.
    51     *
    52     *  GateHwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    58     *    </colgroup>
    59     *
    60     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    61     *    <th>  Main  </th><th>  Startup  </th></tr>
    62     *    <!--                                                               -->
    63     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    64     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    66     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
    68     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    70     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    72     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
    74     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enter}       </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y**  </td><td>   Y**  </td></tr>
    77     *    <tr><td> {@link #leave}       </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y**  </td><td>   Y**  </td></tr>
    79     *    <tr><td colspan="6"> Definitions: <br />
    80     *       <ul>
    81     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    82     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    83     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    84     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    85     *           <ul>
    86     *             <li> In your module startup after this module is started
    87     *    (e.g. GateHwi_Module_startupDone() returns TRUE). </li>
    88     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    89     *             <li> During main().</li>
    90     *             <li> During BIOS.startupFxns.</li>
    91     *           </ul>
    92     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    93     *           <ul>
    94     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    95     *             <li> In your module startup before this module is started
    96     *    (e.g. GateHwi_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
    99     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     */
   106
   107    module GateHwi inherits xdc.runtime.IGateProvider
   108    {
   109        /*!
   110         *  ======== BasicView ========
   111         *  @_nodoc
   112         */
   113        metaonly struct BasicView {
   114            String label;
   115        }
   116
   117        /*!
   118         *  ======== rovViewInfo ========
   119         *  @_nodoc
   120         */
   121        @Facet
   122        metaonly config ViewInfo.Instance rovViewInfo =
   123            ViewInfo.create({
   124                viewMap: [
   125                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   126                ]
   127            });
   128
   129    instance:
   130
   131        /*!
   132         *  @_nodoc
   133         *  ======== enter ========
   134         *  Enter this gate
   135         */
   136        @DirectCall
   137        override IArg enter();
   138
   139        /*!
   140         *  @_nodoc
   141         *  ======== leave ========
   142         *  Leave this gate
   143         */
   144        @DirectCall
   145        override Void leave(IArg key);
   146
   147    internal:
   148
   149        /*!
   150         *  @_nodoc
   151         *  ======== Instance_State ========
   152         *  XDC requires this be defined, even though it's empty.
   153         */
   154        struct Instance_State {
   155        };
   156    }
   157    /*
   158     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   159
   160     */
   161


module ti.sysbios.gates.GateMutex

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateMutex.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates;
    37
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Assert;
    40
    41    /*!
    42     *  ======== GateMutex ========
    43     *  Mutex Gate.
    44     *
    45     *  GateMutex uses a Semaphore as the resource locking mechanism. Each
    46     *  GateMutex instance has its own unique Semaphore. This gate can only be
    47     *  used by a Task as a gate can potentially block. This gate cannot be used
    48     *  by a Hwi or Swi.
    49     *
    50     *  The task that uses a gate can call enter() any number of times without risk
    51     *  of being blocked, although relinquishing ownership of the gate requires a
    52     *  balanced number of calls to leave().
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    58     *    </colgroup>
    59     *
    60     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    61     *    <th>  Main  </th><th>  Startup  </th></tr>
    62     *    <!--                                                        -->
    63     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    64     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    66     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td> {@link #construct}   </td><td>   N    </td><td>   N    </td>
    68     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    70     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    72     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #destruct}    </td><td>   N    </td><td>   N    </td>
    74     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   N    </td>
    76     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   N    </td>
    78     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    79     *    <tr><td colspan="6"> Definitions: <br />
    80     *       <ul>
    81     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    82     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    83     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    84     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    85     *           <ul>
    86     *             <li> In your module startup after this module is started
    87     *    (e.g. GateMutex_Module_startupDone() returns TRUE). </li>
    88     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    89     *             <li> During main().</li>
    90     *             <li> During BIOS.startupFxns.</li>
    91     *           </ul>
    92     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    93     *           <ul>
    94     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    95     *             <li> In your module startup before this module is started
    96     *    (e.g. GateMutex_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
    99     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     */
   106
   107    @InstanceFinalize       /* destruct semaphore */
   108
   109    module GateMutex inherits xdc.runtime.IGateProvider
   110    {
   111
   112        /*!
   113         *  ======== BasicView ========
   114         *  @_nodoc
   115         */
   116        metaonly struct BasicView {
   117            String status;
   118            String owner;
   119            String pendedTasks[];
   120        }
   121
   122        /*!
   123         *  ======== rovViewInfo ========
   124         *  @_nodoc
   125         */
   126        @Facet
   127        metaonly config ViewInfo.Instance rovViewInfo =
   128            ViewInfo.create({
   129                viewMap: [
   130                    ['Basic', {type: ViewInfo.INSTANCE,
   131                       viewInitFxn: 'viewInitBasic',
   132                       structName: 'BasicView'}]
   133                ]
   134            });
   135
   136        /*!
   137         *  Assert when GateMutex_enter() is not called from correct context.
   138         *  GateMutex_enter() can only be called from main() or Task context (not
   139         *  Hwi or Swi).
   140         *
   141         *  Common causes and workarounds for hitting this Assert:
   142         *
   143         *  - Calling printf() from a Hwi or Swi thread.
   144         *  @p(blist)
   145         *          - Use xdc.runtime.System_printf (with SysMin) instead.
   146         *  @p
   147         *  - Calling System_printf() from a Hwi or Swi thread when using SysStd.
   148         *  @p(blist)
   149         *          - Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
   150         *          - Use a different type of Gate for
   151         *            {@link ti.sysbios.BIOS#rtsGateType BIOS.rtsGateType}
   152         *            (ie {@link ti.sysbios.BIOS#GateHwi BIOS.GateHwi}
   153         *            or {@link ti.sysbios.BIOS#GateSwi BIOS.GateSwi})
   154         *  @p
   155         *  - Calling Memory_alloc() from a Hwi or Swi thread.
   156         *  @p(blist)
   157         *          - Use a different Heap manager
   158         *  @p
   159         */
   160        config Assert.Id A_badContext = {
   161            msg: "A_badContext: bad calling context. See GateMutex API doc for details."
   162        };
   163
   164    instance:
   165
   166        /*!
   167         *  @_nodoc
   168         *  ======== enter ========
   169         *  Enter this gate
   170         */
   171        @DirectCall
   172        override IArg enter();
   173
   174        /*!
   175         *  @_nodoc
   176         *  ======== leave ========
   177         *  Leave this gate
   178         */
   179        @DirectCall
   180        override Void leave(IArg key);
   181
   182    internal:
   183
   184        /* -------- Internal Structures -------- */
   185        struct Instance_State {
   186            ti.sysbios.knl.Task.Handle         owner;
   187            ti.sysbios.knl.Semaphore.Object    sem;
   188        };
   189
   190    }
   191    /*
   192     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   193
   194     */
   195


module ti.sysbios.gates.GateMutexPri

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateMutexPri.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates;
    37
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Assert;
    40    import ti.sysbios.knl.Queue;
    41    import ti.sysbios.knl.Task;
    42
    43    /*!
    44     *  ======== GateMutexPri ========
    45     *  Mutex Gate with priority inheritance.
    46     *
    47     *  GateMutexPri is a mutex gate (it can only be held by one thread at a time)
    48     *  which implements priority inheritance in order to prevent priority
    49     *  inversion. Priority inversion occurs when a high priority task has its
    50     *  priority effectively 'inverted' because it is waiting on a gate held by a
    51     *  low priority task.
    52     *
    53     *  When multiple tasks wait on this gate, they will receive the gate in order
    54     *  of priority (higher priority tasks will receive the gate first). This is
    55     *  because the queue of tasks waiting on a GateMutexPri is sorted by priority,
    56     *  not FIFO.
    57     *
    58     *  @p(html)
    59     *  <h3> Problem: Priority Inversion </h3>
    60     *  The following example demonstrates priority inversion.
    61     *  A system has three tasks, Low, Med, and High, each with the priority
    62     *  suggested by its name. Task Low runs first and acquires the gate. Task High
    63     *  is scheduled and preempts Low. Task High tries to acquire the gate, and
    64     *  waits on it. Next, task Med is scheduled and preempts task Low. Now task
    65     *  High must wait for both task Med and task Low to finish before it can
    66     *  continue. In this situation, task Low has in effect lowered task High's
    67     *  priority to that of Low.
    68     *
    69     *  <h3> Solution: Priority Inheritance </h3>
    70     *  To guard against priority inversion, GateMutexPri implements priority
    71     *  inheritance: when task High tries to acquire a gate that is owned by task
    72     *  Low, task Low's priority will be temporarily raised to that of High, as
    73     *  long as High is waiting on the gate. Task High will "donate" its priority
    74     *  to task Low.
    75     *
    76     *  When multiple tasks wait on the gate, the gate owner will receive the
    77     *  highest priority of any of the tasks waiting on the gate.
    78     *
    79     *  <h3> Caveats </h3>
    80     *  Priority inheritance is not a complete guard against priority inversion.
    81     *  Tasks only donate priority on the call to gate, so if a task has its
    82     *  priority raised while waiting on a gate, that priority will not carry
    83     *  through to the gate owner.
    84     *  This can occur in situations involving multiple gates. A system has four
    85     *  tasks: VeryLow, Low, Med, and High, each with the priority suggested by its
    86     *  name. Task VeryLow runs first and acquires gate A. Task Low runs next and
    87     *  acquires gate B, then waits on gate A. Task High runs and waits on gate B.
    88     *  Task High has donated its priority to task Low, but Low is blocked on
    89     *  VeryLow, so priority inversion occurs despite the use of the gate.
    90     *  The solution to this problem is to design around it. If gate A may be
    91     *  needed by a high-priority, time-critical task, then it should be a design
    92     *  rule that no task holds this gate for a long time, or blocks while holding
    93     *  this gate.
    94     *
    95     *  <h3> Miscellaneous </h3>
    96     *  Calls to enter() may block, so this gate can only be used in the task
    97     *  context.
    98     *
    99     *  GateMutexPri is non-deterministic on calls to gate because it keeps the
   100     *  queue of waiting tasks sorted by priority.
   101     *
   102     *  @p(html)
   103     *  <h3> Calling Context </h3>
   104     *  <table border="1" cellpadding="3">
   105     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   106     *  </colgroup>
   107     *
   108     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
   109     *  <th>  Main  </th><th>  Startup  </th></tr>
   110     *    <!--                                                          -->
   111     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
   112     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   113     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
   114     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   115     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
   116     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   117     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
   118     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   119     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
   120     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   121     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
   122     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   123     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   N    </td>
   124     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
   125     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   N    </td>
   126     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
   127     *    <tr><td colspan="6"> Definitions: <br />
   128     *       <ul>
   129     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   130     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   131     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   132     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   133     *           <ul>
   134     *             <li> In your module startup after this module is started
   135     *    (e.g. GateMutexPri_Module_startupDone() returns TRUE). </li>
   136     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   137     *             <li> During main().</li>
   138     *             <li> During BIOS.startupFxns.</li>
   139     *           </ul>
   140     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   141     *           <ul>
   142     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   143     *             <li> In your module startup before this module is started
   144     *    (e.g. GateMutexPri_Module_startupDone() returns FALSE).</li>
   145     *           </ul>
   146     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   147     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   148     *       </ul>
   149     *    </td></tr>
   150     *
   151     *  </table>
   152     *  @p
   153     */
   154
   155    @InstanceFinalize       /* To deconstruct the Queue */
   156
   157    module GateMutexPri inherits xdc.runtime.IGateProvider
   158    {
   159
   160        /*!
   161         *  ======== BasicView ========
   162         *  @_nodoc
   163         */
   164        metaonly struct BasicView {
   165            String     status;
   166            String     label;
   167            UInt       mutexCnt;
   168            String     owner;
   169            Int        ownerOrigPri;
   170            Int        ownerCurrPri;
   171        }
   172
   173        /*!
   174         *  ======== DetailedView ========
   175         *  @_nodoc
   176         */
   177        metaonly struct DetailedView {
   178            String     status;
   179            String     label;
   180            UInt       mutexCnt;
   181            String     owner;
   182            Int        ownerOrigPri;
   183            Int        ownerCurrPri;
   184            String     pendedTasks[];
   185        }
   186
   187        /*!
   188         *  ======== rovViewInfo ========
   189         *  @_nodoc
   190         */
   191        @Facet
   192        metaonly config ViewInfo.Instance rovViewInfo =
   193            ViewInfo.create({
   194                viewMap: [
   195                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   196                    ['Detailed', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDetailed', structName: 'DetailedView'}],
   197                ]
   198            });
   199
   200        /*!
   201         *  Assert when GateMutexPri_enter() is not called from correct context.
   202         *  GateMutexPri_enter() can only be called from main() or Task context (not
   203         *  Hwi or Swi).
   204         *
   205         *  Common causes and workarounds for hitting this Assert:
   206         *
   207         *  - Calling printf() from a Hwi or Swi thread.
   208         *  @p(blist)
   209         *          - Use xdc.runtime.System_printf (with SysMin) instead.
   210         *  @p
   211         *  - Calling System_printf() from a Hwi or Swi thread when using SysStd.
   212         *  @p(blist)
   213         *          - Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
   214         *          - Use a different type of Gate for
   215         *            {@link ti.sysbios.BIOS#rtsGateType BIOS.rtsGateType}
   216         *            (ie {@link ti.sysbios.BIOS#GateHwi BIOS.GateHwi}
   217         *            or {@link ti.sysbios.BIOS#GateSwi BIOS.GateSwi})
   218         *  @p
   219         *  - Calling Memory_alloc() from a Hwi or Swi thread.
   220         *  @p(blist)
   221         *          - Use a different Heap manager
   222         *  @p
   223         */
   224        config Assert.Id A_badContext = {
   225            msg: "A_badContext: bad calling context. See GateMutexPri API doc for details."
   226        };
   227
   228    instance:
   229
   230        /*!
   231         *  @_nodoc
   232         *  ======== enter ========
   233         *  Enter this gate
   234         */
   235        @DirectCall
   236        override IArg enter();
   237
   238        /*!
   239         *  @_nodoc
   240         *  ======== leave ========
   241         *  Leave this gate
   242         */
   243        @DirectCall
   244        override Void leave(IArg key);
   245
   246    internal:
   247
   248        Void insertPri(ti.sysbios.knl.Queue.Object *queue,
   249                       ti.sysbios.knl.Queue.Elem *newElem,
   250                       Int newPri);
   251
   252        /* instance object */
   253        struct Instance_State {
   254            UInt            mutexCnt;       /* The mutex, 0 or 1 */
   255            Int             ownerOrigPri;   /* Owner's original pri */
   256            Task.Handle     owner;          /* Gate owner */
   257            Queue.Object    pendQ;          /* Q of pending tasks */
   258        };
   259    }
   260    /*
   261     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   262
   263     */
   264


module ti.sysbios.gates.GateSwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateSwi.xdc ========
    34     *
    35     **! 30-Nov-2006 toddm   Code reviewed
    36     */
    37    package ti.sysbios.gates
    38
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Assert;
    41
    42    /*!
    43     *  ======== GateSwi ========
    44     *  Software Interrupt Gate.
    45     *
    46     *  GateSwi uses disabling and enabling of software interrupts as the
    47     *  resource locking  mechanism. This gate can be used whenever the resource
    48     *  is being shared by Swis or Tasks. This gate cannot be used by a Hwi.
    49     *
    50     *  The duration between the enter and leave should be as short as possible
    51     *  to minimize Swi latency.
    52     *
    53     *  GateSwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    59     *    </colgroup>
    60     *
    61     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    62     *    <th>  Main  </th><th>  Startup  </th></tr>
    63     *    <!--                                           -->
    64     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    65     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    67     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
    69     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    71     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    73     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
    75     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   Y    </td>
    77     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    80     *    <tr><td colspan="6"> Definitions: <br />
    81     *       <ul>
    82     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    83     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    84     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    85     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    86     *           <ul>
    87     *             <li> In your module startup after this module is started
    88     *    (e.g. GateSwi_Module_startupDone() returns TRUE). </li>
    89     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    90     *             <li> During main().</li>
    91     *             <li> During BIOS.startupFxns.</li>
    92     *           </ul>
    93     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    94     *           <ul>
    95     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    96     *             <li> In your module startup before this module is started
    97     *    (e.g. GateSwi_Module_startupDone() returns FALSE).</li>
    98     *           </ul>
    99     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   100     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   101     *       </ul>
   102     *    </td></tr>
   103     *
   104     *  </table>
   105     *  @p
   106     */
   107
   108    module GateSwi inherits xdc.runtime.IGateProvider
   109    {
   110
   111        /*!
   112         *  ======== BasicView ========
   113         *  @_nodoc
   114         */
   115        metaonly struct BasicView {
   116            String label;
   117        }
   118
   119        /*!
   120         *  ======== rovViewInfo ========
   121         *  @_nodoc
   122         */
   123        @Facet
   124        metaonly config ViewInfo.Instance rovViewInfo =
   125            ViewInfo.create({
   126                viewMap: [
   127                [
   128                    'Basic',
   129                    {
   130                        type: ViewInfo.INSTANCE,
   131                        viewInitFxn: 'viewInitBasic',
   132                        structName: 'BasicView'
   133                    }
   134                ],
   135                ]
   136            });
   137
   138        /*!
   139         * Asserted when {@link #enter} or {@link #leave} is called from a
   140         * hardware interrupt thread.
   141         */
   142        config Assert.Id A_badContext = {
   143                msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."
   144        };
   145
   146    instance:
   147
   148        /*!
   149         *  @_nodoc
   150         *  ======== enter ========
   151         *  Enter this gate
   152         */
   153        @DirectCall
   154        override IArg enter();
   155
   156        /*!
   157         *  @_nodoc
   158         *  ======== leave ========
   159         *  Leave this gate
   160         */
   161        @DirectCall
   162        override Void leave(IArg key);
   163
   164    internal:
   165
   166        /*!
   167         *  @_nodoc
   168         *  ======== Instance_State ========
   169         *  XDC requires this be defined, even though it's empty.
   170         */
   171        struct Instance_State {
   172        };
   173    }
   174    /*
   175     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   176
   177     */
   178


module ti.sysbios.gates.GateTask

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== GateTask.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates
    37
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Assert;
    40
    41    /*!
    42     *  ======== GateTask ========
    43     *  Task Gate.
    44     *
    45     *  GateTask uses disabling and enabling of tasks as the resource locking
    46     *  mechanism. This gate can be used whenever the resource is being shared
    47     *  by Tasks. This gate cannot be used by a Hwi or Swi.
    48     *
    49     *  The duration between the enter and leave should be as short as possible
    50     *  to minimize Task latency.
    51     *
    52     *  GateTask inherits from xdc.runtime.IGateProvider, therefore supports
    53     *  nesting.
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    59     *    </colgroup>
    60     *
    61     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    62     *    <th>  Main  </th><th>  Startup  </th></tr>
    63     *    <!--                                                      -->
    64     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    65     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    67     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
    69     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    71     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    73     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
    75     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   N    </td>
    77     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   N    </td>
    79     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    80     *    <tr><td colspan="6"> Definitions: <br />
    81     *       <ul>
    82     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    83     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    84     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    85     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    86     *           <ul>
    87     *             <li> In your module startup after this module is started
    88     *    (e.g. GateTask_Module_startupDone() returns TRUE). </li>
    89     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    90     *             <li> During main().</li>
    91     *             <li> During BIOS.startupFxns.</li>
    92     *           </ul>
    93     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    94     *           <ul>
    95     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    96     *             <li> In your module startup before this module is started
    97     *    (e.g. GateTask_Module_startupDone() returns FALSE).</li>
    98     *           </ul>
    99     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   100     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   101     *       </ul>
   102     *    </td></tr>
   103     *
   104     *  </table>
   105     *  @p
   106     */
   107
   108    module GateTask inherits xdc.runtime.IGateProvider
   109    {
   110        /*!
   111         *  ======== BasicView ========
   112         *  @_nodoc
   113         */
   114        metaonly struct BasicView {
   115            String label;
   116        }
   117
   118        /*!
   119         *  ======== rovViewInfo ========
   120         *  @_nodoc
   121         */
   122        @Facet
   123        metaonly config ViewInfo.Instance rovViewInfo =
   124            ViewInfo.create({
   125                viewMap: [
   126                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
   127                ]
   128            });
   129
   130        /*!
   131         * Asserted when {@link #enter} is called from a hardware/software
   132         * interrupt thread
   133         */
   134        config Assert.Id A_badContext = {
   135                msg: "A_badContext: bad calling context. May not be entered from a software or hardware interrupt thread."
   136        };
   137
   138    instance:
   139
   140        /*!
   141         *  @_nodoc
   142         *  ======== enter ========
   143         *  Enter this gate
   144         */
   145        @DirectCall
   146        override IArg enter();
   147
   148        /*!
   149         *  @_nodoc
   150         *  ======== leave ========
   151         *  Leave this gate
   152         */
   153        @DirectCall
   154        override Void leave(IArg key);
   155
   156    internal:
   157
   158        /*!
   159         *  @_nodoc
   160         *  ======== Instance_State ========
   161         *  XDC requires this be defined, even though it's empty.
   162         */
   163        struct Instance_State {
   164        };
   165    }
   166    /*
   167     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   168
   169     */
   170


package ti.sysbios.gates

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    requires ti.sysbios.knl;
    39
    40    /*!
    41     *  ======== ti.sysbios.gates ========
    42     *  Contains modules that inherit from IGatePovider.
    43     *
    44     *  The {@link xdc.runtime.Gate} module is provided by XDCtools, and
    45     *  is documented in the XDCtools help, but SYS/BIOS provides
    46     *  additional implementations in the {@link ti.sysbios.gates} package.
    47     *
    48     *  A "Gate" is a module that implements the IGateProvider interface.
    49     *  Gates are devices for preventing concurrent accesses to critical
    50     *  regions of code. The various Gate implementations differ in how they
    51     *  attempt to lock the critical regions.
    52     *
    53     *  Threads can be preempted by other threads of higher priority, and
    54     *  some sections of code need to be completed by one thread before they
    55     *  can be executed by another thread. Code that modifies a linked list
    56     *  is a common example of a critical region that may need to be protected
    57     *  by a Gate.
    58     *
    59     *  Gates generally work by either disabling some level of preemption such
    60     *  as disabling task switching or even hardware interrupts, or by using a
    61     *  binary semaphore.
    62     *
    63     *  All Gate implementations support nesting through the use of a "key".
    64     *  For Gates that function by disabling preemption, it is possible that
    65     *  multiple threads would call Gate_enter(), but preemption should not be
    66     *  restored until all of the threads have called Gate_leave().
    67     *  This functionality is provided through the use of a key. A call to
    68     *  Gate_enter() returns a key that must then be passed back to Gate_leave().
    69     *  Only the outermost call to Gate_enter() returns the correct key for
    70     *  restoring preemption. (The actual module name for the implementation
    71     *  is used instead of "Gate" in the function name.)
    72     *
    73     *  @a(Runtime Example)
    74     *  The following C code protects a critical region with
    75     *  a Gate. This example uses a GateHwi, which disables and enables
    76     *  interrupts as the locking mechanism.
    77     *
    78     *  @p(code)
    79     *  UInt gateKey;
    80     *  GateHwi_Handle gateHwi;
    81     *  GateHwi_Params prms;
    82     *  GateHwi_Params_init(&prms);
    83     *
    84     *  gateHwi = GateHwi_create(&prms, NULL);
    85     *
    86     *  // Simultaneous operations on a List by multiple threads could
    87     *  // corrupt the List structure, so modifications to the List
    88     *  // are protected with a Gate.
    89     *  gateKey = GateHwi_enter(gateHwi);
    90     *  List_get(myList);
    91     *  GateHwi_leave(gateHwi, gateKey);
    92     *  @p
    93     *
    94     */
    95
    96    package ti.sysbios.gates [2,0,0,0] {
    97        module GateHwi;
    98        module GateAll;
    99        module GateSwi;
   100        module GateTask;
   101        module GateTest;
   102        module GateMutexPri;
   103        module GateMutex;
   104    }
   105
   106    /*
   107     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,491; 6-15-2011 16:25:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   108
   109     */
   110


module ti.sysbios.hal.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    /*!
    41     *  ======== Cache ========
    42     *  Cache Manager Proxy.
    43     *
    44     *  This module is a proxy to the generic Cache module functions
    45     *  as defined in ICache.xdc.
    46     *
    47     *  The actual implementations of the Cache module functions are
    48     *  provided by the Cache module delegates.
    49     *
    50     *  Additional, family-specific Cache module APIs may also be provided
    51     *  by the Cache module delegates.
    52     *
    53     *  Follow the link below to determine which Cache delegate is used
    54     *  for your Target/Device:
    55     *
    56     *      {@link ./../family/doc-files/delegates.html Delegate Mappings}
    57     *
    58     *  @p(html)
    59     *  <h3> Calling Context </h3>
    60     *  <table border="1" cellpadding="3">
    61     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    62     *    </colgroup>
    63     *
    64     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    65     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    66     *    <!--                                            -->
    67     *    <tr><td> {@link #disable} </td><td>   Y    </td><td>   Y    </td>
    68     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #enable}  </td><td>   Y    </td><td>   Y    </td>
    70     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #inv}     </td><td>   Y    </td><td>   Y    </td>
    72     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #wait}    </td><td>   Y    </td><td>   Y    </td>
    74     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #wb}      </td><td>   Y    </td><td>   Y    </td>
    76     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    77     *    <tr><td> {@link #wbInv}   </td><td>   Y    </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    79     *    <tr><td colspan="6"> Definitions: <br />
    80     *       <ul>
    81     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    82     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    83     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    84     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    85     *           <ul>
    86     *             <li> In your module startup after this module is started
    87     *    (e.g. Cache_Module_startupDone() returns TRUE). </li>
    88     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    89     *             <li> During main().</li>
    90     *             <li> During BIOS.startupFxns.</li>
    91     *           </ul>
    92     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    93     *           <ul>
    94     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    95     *             <li> In your module startup before this module is started
    96     *    (e.g. Cache_Module_startupDone() returns FALSE).</li>
    97     *           </ul>
    98     *       </ul>
    99     *    </td></tr>
   100     *
   101     *  </table>
   102     *  @p
   103     */
   104
   105    module Cache inherits ti.sysbios.interfaces.ICache
   106    {
   107        /*!
   108         *  ======== ModuleView ========
   109         *  @_nodoc
   110         */
   111        metaonly struct ModuleView {
   112            String delegateCacheModule;
   113        };
   114
   115        /*!
   116         *  ======== rovViewInfo ========
   117         *  @_nodoc
   118         */
   119        @Facet
   120        metaonly config ViewInfo.Instance rovViewInfo =
   121            ViewInfo.create({
   122                viewMap: [
   123                    ['Module', {
   124                        type: ViewInfo.MODULE, viewInitFxn: 'viewInitModule',
   125                        structName: 'ModuleView'}]
   126                ]
   127            });
   128
   129    internal:   /* not for client use */
   130
   131        /*!
   132         *  ======== CacheProxy ========
   133         *  Target/device-specific Cache implementation
   134         */
   135        proxy CacheProxy inherits ti.sysbios.interfaces.ICache;
   136    }
   137    /*
   138     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:52; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   139
   140     */
   141


module ti.sysbios.hal.CacheNull

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== CacheNull.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37
    38    /*!
    39     *  ======== CacheNull ========
    40     *  Null Cache module
    41     *
    42     */
    43
    44    module CacheNull inherits ti.sysbios.interfaces.ICache
    45    {
    46    }
    47
    48    /*
    49     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:52; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.hal.Hwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Hwi.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37
    38    import xdc.runtime.Error;
    39
    40    /*!
    41     *  ======== Hwi ========
    42     *  Hardware Interrupt Manager Proxy.
    43     *
    44     *  This module provides APIs for managing hardware interrupts.
    45     *  These APIs are generic across all supported targets and devices
    46     *  and should provide sufficient functionality for most applications.
    47     *
    48     *  The actual implementations of the Hwi module APIs are
    49     *  provided by the Hwi module delegates.
    50     *  Additional, family-specific Hwi module APIs may also be provided by
    51     *  the Hwi module delegates.
    52     *  See the list of
    53     *  {@link ./../family/doc-files/delegates.html Delegate Mappings}
    54     *  to determine which Hwi delegate is used
    55     *  for your target/device.
    56     *
    57     *  You can statically or dynamically assign functions that run when
    58     *  specific hardware interrupts occur. Dynamic assignment of Hwi
    59     *  functions to interrupts at run-time is done
    60     *  using the {@link #create Hwi_create} function.
    61     *
    62     *  Interrupt routines can be written completely in C, completely in
    63     *  assembly, or in a mix of C and assembly. In order to support interrupt
    64     *  routines
    65     *  written completely in C, an interrupt dispatcher is provided that performs
    66     *  the requisite prolog and epilog for an interrupt routine.
    67     *
    68     *  Some routines are assigned to interrupts by the other SYS/BIOS
    69     *  modules. For example, the
    70     *  {@line ti.sysbios.knl.Clock} module configures its own timer interrupt
    71     *  handler.
    72     *
    73     *  @p(html)
    74     *  <h3> Calling Context </h3>
    75     *  <table border="1" cellpadding="3">
    76     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    77     *    </colgroup>
    78     *
    79     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    80     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    81     *    <!--                                                         -->
    82     *    <tr><td> {@link #clearInterrupt}   </td><td>   Y    </td><td>   Y    </td>
    83     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    84     *    <tr><td> {@link #create}           </td><td>   N    </td><td>   N    </td>
    85     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #disable}          </td><td>   Y    </td><td>   Y    </td>
    87     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    88     *    <tr><td> {@link #disableInterrupt} </td><td>   Y    </td><td>   Y    </td>
    89     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #enable}           </td><td>   Y    </td><td>   Y    </td>
    91     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #enableInterrupt}  </td><td>   Y    </td><td>   Y    </td>
    93     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #Params_init}      </td><td>   Y    </td><td>   Y    </td>
    95     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    96     *    <tr><td> {@link #restore}          </td><td>   Y    </td><td>   Y    </td>
    97     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    98     *    <tr><td> {@link #restoreInterrupt} </td><td>   Y    </td><td>   Y    </td>
    99     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   100     *    <tr><td> {@link #construct}        </td><td>   N    </td><td>   N    </td>
   101     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #delete}           </td><td>   N    </td><td>   N    </td>
   103     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #destruct}         </td><td>   N    </td><td>   N    </td>
   105     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #getHookContext}   </td><td>   Y    </td><td>   Y    </td>
   107     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #setFunc}          </td><td>   Y    </td><td>   Y    </td>
   109     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   110     *    <tr><td> {@link #setHookContext}   </td><td>   Y    </td><td>   Y    </td>
   111     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   112     *    <tr><td colspan="6"> Definitions: <br />
   113     *       <ul>
   114     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   115     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   116     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   117     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   118     *           <ul>
   119     *             <li> In your module startup after this module is started
   120     *    (e.g. Hwi_Module_startupDone() returns TRUE). </li>
   121     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   122     *             <li> During main().</li>
   123     *             <li> During BIOS.startupFxns.</li>
   124     *           </ul>
   125     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   126     *           <ul>
   127     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   128     *             <li> In your module startup before this module is started
   129     *    (e.g. Hwi_Module_startupDone() returns FALSE).</li>
   130     *           </ul>
   131     *       </ul>
   132     *    </td></tr>
   133     *
   134     *  </table>
   135     *  @p
   136     *
   137     *  @a(Runtime Hwi Creation)
   138     *
   139     *  Below is an example that configures an interrupt at runtime.
   140     *  Typically such code would be placed in main().
   141     *
   142     *  @p(code)
   143     *  #include <xdc/runtime/Error.h>
   144     *  #include <ti/sysbios/hal/Hwi.h>
   145     *
   146     *  Hwi_Handle myHwi;
   147     *
   148     *  Int main(Int argc, char* argv[])
   149     *  {
   150     *      Hwi_Params hwiParams;
   151     *      Error_Block eb;
   152     *
   153     *      Hwi_Params_init(&hwiParams);
   154     *      Error_init(&eb);
   155     *
   156     *      // set the argument you want passed to your ISR function
   157     *      hwiParams.arg = 1;
   158     *
   159     *      // set the event id of the peripheral assigned to this interrupt
   160     *      hwiParams.eventId = 10;
   161     *
   162     *      // don't allow this interrupt to nest itself
   163     *      hwiParams.maskSetting = Hwi_MaskingOption_SELF;
   164     *
   165     *      //
   166     *      // Configure interrupt 5 to invoke "myIsr".
   167     *      // Automatically enables interrupt 5 by default
   168     *      // set params.enableInt = FALSE if you want to control
   169     *      // when the interrupt is enabled using Hwi_enableInterrupt()
   170     *      //
   171     *
   172     *      myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);
   173     *
   174     *      if (Error_check(&eb)) {
   175     *          // handle the error
   176     *      }
   177     *  }
   178     *
   179     *  Void myIsr(UArg arg)
   180     *  {
   181     *      // this runs when interrupt #5 goes off
   182     *  }
   183     *  @p
   184     *
   185     *  @a(Hook Functions)
   186     *
   187     *  Sets of hook functions can be specified for the Hwi module
   188     *  using the configuration tool.  Each set contains these hook
   189     *  functions:
   190     *  @p(blist)
   191     *  -Register:  A function called before any statically-created Hwis
   192     *      are initialized at runtime.  The register hook is called at boot time
   193     *      before main() and before interrupts are enabled.
   194     *  -Create:    A function that is called when a Hwi is created.
   195     *      This includes hwis that are created statically and those
   196     *      created dynamically using {@link #create Hwi_create}.
   197     *  -Begin:     A function that is called just prior to running a Hwi.
   198     *  -End:       A function that is called just after a Hwi finishes.
   199     *  -Delete:    A function that is called when a Hwi is deleted at
   200     *      run-time with {@link #delete Hwi_delete}.
   201     *  @p
   202     *
   203     *  Register Function
   204     *
   205     *  The Register function is provided to allow a hook set to store its
   206     *  hookset ID.  This id can be passed to
   207     *  {@link #setHookContext Hwi_setHookContext} and
   208     *  {@link #getHookContext Hwi_getHookContext} to set or get
   209     *  hookset-specific context.  The
   210     *  Register function must be specified if the hook implementation
   211     *  needs to use {@link #setHookContext  Hwi_setHookContext} or
   212     *  {@link #getHookContext  Hwi_getHookContext}.
   213     *  The registerFxn hook function is called during system initialization
   214     *  before interrupts have been enabled.
   215     *
   216     *  @p(code)
   217     *  Void myRegisterFxn(Int id);
   218     *  @p
   219     *
   220     *  Create and Delete Functions
   221     *
   222     *  The create and delete functions are called whenever a Hwi is created
   223     *  or deleted.  They are called with interrupts enabled (unless called
   224     *  at boot time or from main()).
   225     *
   226     *  @p(code)
   227     *  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);
   228     *  @p
   229     *
   230     *  @p(code)
   231     *  Void myDeleteFxn(Hwi_Handle hwi);
   232     *  @p
   233     *
   234     *  Begin and End Functions
   235     *
   236     *  The beginFxn and endFxn function hooks are called with interrupts
   237     *  globally disabled, therefore any hook processing function will contribute
   238     *  to the overall system interrupt response latency.  In order to minimize
   239     *  this impact, carefully consider the processing time spent in an Hwi
   240     *  beginFxn or endFxn function hook.
   241     *
   242     *  @p(code)
   243     *  Void myBeginFxn(Hwi_Handle hwi);
   244     *  @p
   245     *
   246     *  @p(code)
   247     *  Void myEndFxn(Hwi_Handle hwi);
   248     *  @p
   249     *
   250     *  Hook functions can only be configured statically.
   251     *
   252     */
   253
   254    @ModuleStartup      /* generate a call to startup function */
   255
   256    @Template("./Hwi.xdt")
   257
   258    module Hwi inherits ti.sysbios.interfaces.IHwi
   259    {
   260        /*!
   261         *  Error raised when a stack overflow (or corruption) is detected.
   262         *
   263         *  This error is raised by kernel's stack checking function.  This
   264         *  function checks the stacks before every task switch to make sure
   265         *  that reserved word at top of stack has not been modified.
   266         *
   267         *  The stack checking logic is enabled by the {@link #initStackFlag} and
   268         *  {@link #checkStackFlag} configuration parameters.  If both of these
   269         *  flags are set to true, the kernel will validate the stacks.
   270         */
   271        config Error.Id E_stackOverflow  = {
   272            msg: "E_stackOverflow: ISR stack overflow."
   273        };
   274
   275        /*!
   276         *  Initialize ISR stack with known value for stack checking at runtime
   277         *
   278         *  This is also useful for inspection of stack in debugger or core
   279         *  dump utilities.
   280         *
   281         *  Default is true.
   282         *  (see {@link #checkStackFlag}).
   283         */
   284        metaonly config Bool initStackFlag = true;
   285
   286        /*!
   287         *  Check for Hwi stack overrun during Idle loop.
   288         *
   289         *  If true, then an idle function is added to the idle loop
   290         *  that checks for a Hwi stack overrun condition and raises
   291         *  an Error if one is detected.
   292         *
   293         *  The check consists of testing the top of stack value against
   294         *  its initial value (see {@link #initStackFlag}). If it is no
   295         *  longer at this value, the assumption is that the ISR stack
   296         *  has been overrun. If the test fails, then the
   297         *  {@link #E_stackOverflow} error is raised.
   298         *
   299         *  Runtime stack checking is only performed if {@link #initStackFlag} is
   300         *  also true.
   301         *
   302         *  Default is true.
   303         *  (see {@link #initStackFlag}).
   304         *
   305         *  To enable or disable full stack checking, you should set both this
   306         *  flag and the {@link ti.sysbios.knl.Task#checkStackFlag}.
   307         */
   308        metaonly config Bool checkStackFlag = true;
   309
   310        /*!
   311         *  ======== disable ========
   312         */
   313        @Macro
   314        override UInt disable();
   315
   316        /*!
   317         *  ======== enable ========
   318         */
   319        @Macro
   320        override UInt enable();
   321
   322        /*!
   323         *  ======== restore ========
   324         */
   325        @Macro
   326        override Void restore(UInt key);
   327
   328        /*!
   329         *  ======== viewGetHandle ========
   330         *  @_nodoc
   331         *  Returns the corresponding hal Hwi handle for a delegate Hwi handle
   332         *
   333         *  @b(returns)     hal Hwi handle
   334         */
   335        metaonly Handle viewGetHandle(Ptr pi);
   336
   337    instance:
   338
   339        /*!
   340         *  ======== create ========
   341         *  Create a dispatched interrupt.
   342         *
   343         *  To cause a C function to run in response to a particular system
   344         *  interrupt, you create a Hwi object that encapsulates information
   345         *  regarding the interrupt required by the Hwi module.
   346         *
   347         *  The standard static and dynamic forms of the "create" function are
   348         *  supported by the ti.sysbios.hal.Hwi module.
   349         *  The following C code configures interrupt 5 with the "myIsr"
   350         *  C function.
   351         *
   352         *  @p(code)
   353         *  #include <ti/sysbios/hal/Hwi>
   354         *
   355         *  Hwi_create(5, myIsr, NULL, NULL);
   356         *  @p
   357         *
   358         *  The NULL, NULL arguments are used when the default instance
   359         *  parameters and generic error handling is satisfactory for creating
   360         *  a Hwi object.
   361         *
   362         *  A Hwi dispatcher table entry is created and filled with the
   363         *  function specified by the fxn parameter and the attributes
   364         *  specified by the params parameter.
   365         *
   366         *  If params is NULL, the Hwi's dispatcher properties are assigned a
   367         *  default set of values. Otherwise, the following properties
   368         *  are specified by a structure of type Hwi_Params.
   369         *
   370         *  @p(blist)
   371         *  - The arg element is a generic argument that is passed to the plugged
   372         *  function as its only parameter. The default value is 0.
   373         *  - The enableInt element determines whether the interrupt should be
   374         *  enabled in the IER by create.
   375         *  - The maskSetting element defines the dispatcherAutoNestingSupport
   376         *  behavior of the interrupt.
   377         *  @p
   378         *
   379         *  Hwi_create returns a pointer to the created Hwi object.
   380         *
   381         *  @param(intNum)  interrupt number
   382         *  @param(hwiFxn)  pointer to ISR function
   383         */
   384        @DirectCall
   385        override create(Int intNum, FuncPtr hwiFxn);
   386
   387        /*!
   388         *  ======== getHookContext ========
   389         *  Get hook instance's context for a Hwi.
   390         *
   391         *  The Handle passed to this API must be the handle passed
   392         *  to any of the Hook functions, not the one returned by
   393         *  {@link #create Hwi_create}.
   394         *
   395         *  @b(returns)     hook instance's context for hwi
   396         */
   397        @DirectCall
   398        override Ptr getHookContext(Int id);
   399
   400        /*!
   401         *  ======== setHookContext ========
   402         *  Set hook instance's context for a Hwi.
   403         *
   404         *  The Handle passed to this API must be the handle passed
   405         *  to any of the Hook functions, not the one returned by
   406         *  {@link #create Hwi_create}.
   407         *
   408         *  @param(id)            hook instance's ID
   409         *  @param(hookContext)   value to write to context
   410         */
   411        @DirectCall
   412        override Void setHookContext(Int id, Ptr hookContext);
   413
   414    internal:   /* not for client use */
   415
   416        /* keep track of the number of hooks defined */
   417        metaonly config UInt numHooks = 0;
   418
   419        /*! target/device-specific Hwi implementation. */
   420        proxy HwiProxy inherits ti.sysbios.interfaces.IHwi;
   421
   422        struct Instance_State {
   423            HwiProxy.Handle pi;
   424        };
   425    }
   426    /*
   427     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:52; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   428
   429     */
   430


package ti.sysbios.hal

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    requires ti.sysbios.family;
    39
    40    /*!
    41     *  ======== ti.sysbios.hal ========
    42     *  Contains Hardware Abstraction Layer (HAL) modules for the SYS/BIOS kernel.
    43     *
    44     *  SYS/BIOS provides services for configuration and management of interrupts,
    45     *  cache, and timers. Unlike other SYS/BIOS services such as threading, these
    46     *  modules directly program aspects of a device's hardware and are grouped
    47     *  together in the Hardware Abstraction Layer (HAL) package. These modules
    48     *  provide services such as enabling and disabling interrupts, plugging of
    49     *  interrupt vectors, multiplexing of multiple interrupts to a single vector,
    50     *  and cache invalidation or writeback.
    51     *
    52     *  The HAL APIs fall into two categories:
    53     *
    54     *  @p(blist)
    55     *  - Generic APIs that are available across all targets and devices.
    56     *  - Target/device-specific APIs that are available only for a specific device
    57     *    or ISA family
    58     *  @p
    59     *
    60     *  The generic APIs are designed to cover the great majority of use cases.
    61     *  If you are concerned with easy portability between
    62     *  different TI devices, you should use the generic APIs as much
    63     *  as possible. However, if the generic APIs cannot enable use of a
    64     *  device-specific hardware feature that is advantageous to the software
    65     *  application, you may choose to use the target/device-specific APIs.
    66     *
    67     *  The {@link ti.sysbios.hal.Hwi}, {@link ti.sysbios.hal.Timer}, and
    68     *  {@link ti.sysbios.hal.Cache} modules require target/device-specific API
    69     *  implementations to achieve their functionality. To provide a common set
    70     *  of APIs for these modules across all supported families/devices, SYS/BIOS
    71     *  uses the RTSC proxy-delegate module mechanism. That is, each of these
    72     *  modules serves as a proxy for a corresponding
    73     *  target/device-specific module implementation.
    74     *
    75     *  During the configuration step of the application build, the
    76     *  modules in the ti.sysbios.hal package locate and bind themselves to
    77     *  appropriate delegate module implementations based on the current target
    78     *  and platform specified in your config.bld file. The delegate binding
    79     *  process is done internally.
    80     *
    81     *  For example, if your config.bld file specifies that one of your build
    82     *  targets is the C64P family, the {@link ti.sysbios.hal.Hwi} knows to
    83     *  bind itself to the {@link ti.sysbios.family.c64p.Hwi} implementation.
    84     */
    85    package ti.sysbios.hal [2,0,0,0] {
    86        module Hwi;
    87        module Timer;
    88        module TimerNull;
    89        module Cache;
    90        module CacheNull;
    91    }
    92    /*
    93     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:54; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    94
    95     */
    96


module ti.sysbios.hal.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37
    38    /*!
    39     *  ======== Timer ========
    40     *  Timer Manager Proxy.
    41     *
    42     *  The ti.sysbios.hal.Timer module presents a standard interface for using
    43     *  the timer peripherals. This module is part of the Hardware Abstraction
    44     *  Layer (HAL) package, which hides target/device-specific characteristics
    45     *  of the hardware.
    46     *
    47     *  You can use this module to create a timer (that is, to mark a timer for
    48     *  use) and configure it to call a tickFxn when the timer expires. Use this
    49     *  module only if you do not need to do any custom configuration of the
    50     *  timer peripheral.
    51     *
    52     *  The timer can be configured as a one-shot or a continuous mode timer.
    53     *  The period can be specified in timer counts or microseconds.
    54     *
    55     *  The timer interrupt always uses the Hwi dispatcher. The Timer tickFxn
    56     *  runs in the context of a Hwi thread. The Timer module automatically
    57     *  creates a Hwi instance for the timer interrupt.
    58     *
    59     *  The actual implementations of the Timer module functions are
    60     *  provided by device/family-specific Timer modules.
    61     *  Additional, family-specific Timer module APIs may also be provided by
    62     *  your Timer module implementation.
    63     *  Follow the link below to determine which Timer implementation is used
    64     *  for your target:
    65     *
    66     *      {@link ./../family/doc-files/delegates.html Delegate Mappings}
    67     *
    68     *  @p(html)
    69     *  <h3> Calling Context </h3>
    70     *  <table border="1" cellpadding="3">
    71     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    72     *    </colgroup>
    73     *
    74     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    75     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    76     *    <!--                                                                  -->
    77     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
    82     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
    84     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    85     *    <tr><td> {@link #create}                  </td><td>   N    </td>
    86     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
    88     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
    96     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
    98     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    99     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   100     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   101     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   102     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   103     *    <tr><td colspan="6"> Definitions: <br />
   104     *       <ul>
   105     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   106     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   107     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   108     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   109     *           <ul>
   110     *             <li> In your module startup after this module is started
   111     *    (e.g. Timer_Module_startupDone() returns TRUE). </li>
   112     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   113     *             <li> During main().</li>
   114     *             <li> During BIOS.startupFxns.</li>
   115     *           </ul>
   116     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   117     *           <ul>
   118     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   119     *             <li> In your module startup before this module is started
   120     *    (e.g. Timer_Module_startupDone() returns FALSE).</li>
   121     *           </ul>
   122     *       </ul>
   123     *    </td></tr>
   124     *
   125     *  </table>
   126     *  @p
   127     */
   128
   129    @ModuleStartup
   130    @InstanceFinalize       /* Needed to forward Timer_delete() call to proxy */
   131    @InstanceInitError      /* To report unavailability of timer */
   132
   133    module Timer inherits ti.sysbios.interfaces.ITimer
   134    {
   135        /*!
   136         *  ======== viewGetHandle ========
   137         *  @_nodoc
   138         *  Returns the corresponding hal Timer handle for a delegate Timer handle
   139         *
   140         *  @b(returns)     hal Timer handle
   141         */
   142        metaonly Handle viewGetHandle(Ptr pi);
   143
   144    instance:
   145
   146        /*!
   147         *  ======== create ========
   148         *  Create a timer.
   149         *
   150         *  Create could fail if timer peripheral is unavailable. To
   151         *  request any available timer use {@link #ANY} as the id.
   152         *  TimerId's are logical ids. The family-specific implementations
   153         *  map the ids to physical peripherals.
   154         *
   155         *  @param(id)      Timer id ranging from 0 to a platform specific value
   156         *  @param(tickFxn) function that runs upon timer expiry.
   157         */
   158        override create(Int id, FuncPtr tickFxn);
   159
   160    internal:   /* not for client use */
   161
   162        /*! target/device-specific Timer implementation. */
   163        proxy TimerProxy inherits ti.sysbios.interfaces.ITimer;
   164
   165        struct Instance_State {
   166            TimerProxy.Handle pi;
   167        };
   168    }
   169    /*
   170     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:53; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   171
   172     */
   173


module ti.sysbios.hal.TimerNull

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimerNull.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal;
    37
    38    /*!
    39     *  ======== TimerNull ========
    40     *  Null Timer module
    41     *
    42     */
    43
    44    module TimerNull inherits ti.sysbios.interfaces.ITimer
    45    {
    46    }
    47
    48    /*
    49     *  @(#) ti.sysbios.hal; 2, 0, 0, 0,497; 6-15-2011 16:25:54; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.hal.ammu.AMMU

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== AMMU.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.hal.ammu;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    /*!
    42     *  ======== AMMU ========
    43     *  Attribute MMU configuration module
    44     *
    45     *  Responsible for initializing the Attribute MMU
    46     *
    47     *  @a(Restrictions)
    48     *  When used within a dual M3 core (Ducati) arrangement, care must be
    49     *  taken when initializing this shared resource.
    50     *  The "Shared Resources" note provided
    51     *  in the {@link ti.sysbios.family.arm.ducati ducati} package discusses
    52     *  the management of the various hardware and software resources
    53     *  shared by the two M3 cores.
    54     *
    55     *  As the AMMU is shared between the two M3 cores, it should only
    56     *  be initialized and enabled once.
    57     *  It is intended that Core 0 will {@link #configureAmmu configure}
    58     *  the AMMU at startup.
    59     *  @a
    60     */
    61
    62    module AMMU
    63    {
    64        // -------- xgconf config filters --------
    65
    66        /*! @_nodoc */
    67        metaonly readonly config xdc.runtime.Types.ViewInfo filteredNameMap$[string] = [
    68            ["Filtered Variables", {viewType: "module", viewFxn: "pageSizeFilter",
    69            fields: [
    70                "largePages", "mediumPages", "smallPages"
    71            ]}],
    72        ];
    73
    74        /*! @_nodoc */
    75        metaonly any pageSizeFilter(int op, string paramName, string value);
    76
    77        // -------- ROV views --------
    78
    79        /*! @_nodoc */
    80        metaonly struct PageView {
    81            String      Page;
    82            Ptr         AddrVirtual;
    83            String      AddrPhysical;
    84            Bool        Enabled;
    85            Bool        L1Cacheable;
    86            String      L1WrPolicy;
    87            String      L1AllocPolicy;
    88            Bool        L1Posted;
    89            Bool        L2Cacheable;
    90            String      L2WrPolicy;
    91            String      L2AllocPolicy;
    92            Bool        L2Posted;
    93            Bool        ReadOnly;
    94            Bool        ExecOnly;
    95        };
    96
    97        /*! @_nodoc */
    98        @Facet
    99        metaonly config ViewInfo.Instance rovViewInfo =
   100            ViewInfo.create({
   101                viewMap: [
   102                    ['PageView',  {type: ViewInfo.MODULE_DATA,
   103                      viewInitFxn: 'viewPages',
   104                      structName: 'PageView'}]
   105               ]
   106           });
   107
   108        /*
   109         * Policy register field definitions
   110         */
   111
   112        metaonly enum Small {
   113            Small_4K,
   114            Small_8K,
   115            Small_16K,
   116            Small_32K
   117        };
   118
   119        metaonly enum Medium {
   120            Medium_128K,
   121            Medium_256K,
   122            Medium_512K,
   123            Medium_1M
   124        };
   125
   126        metaonly enum Large {
   127            Large_2M,
   128            Large_4M,
   129            Large_8M,
   130            Large_16M,
   131            Large_32M,
   132            Large_64M,
   133            Large_128M,
   134            Large_256M,
   135            Large_512M
   136        };
   137
   138        metaonly enum Volatile {
   139            Volatile_DO_NOT_FOLLOW,
   140            Volatile_FOLLOW
   141        };
   142
   143        metaonly enum CachePolicy {
   144            CachePolicy_NON_CACHEABLE,
   145            CachePolicy_CACHEABLE
   146        };
   147
   148        metaonly enum PostedPolicy {
   149            PostedPolicy_NON_POSTED,
   150            PostedPolicy_POSTED
   151        };
   152
   153        metaonly enum AllocatePolicy {
   154            AllocatePolicy_NON_ALLOCATE,
   155            AllocatePolicy_ALLOCATE
   156        };
   157
   158        metaonly enum WritePolicy {
   159            WritePolicy_WRITE_THROUGH,
   160            WritePolicy_WRITE_BACK
   161        };
   162
   163        metaonly enum Enable {
   164            Enable_NO,
   165            Enable_YES
   166        };
   167
   168        /*
   169         * Page Descriptor Definitions
   170         */
   171
   172        metaonly struct LargePage {
   173            Enable          pageEnabled;
   174            Ptr             logicalAddress;
   175
   176            Enable          translationEnabled;
   177            Ptr             translatedAddress;
   178
   179            Large           size;
   180            Volatile        volatileQualifier;
   181            Enable          executeOnly;
   182            Enable          readOnly;
   183            Enable          prefetch;
   184            Enable          exclusion;
   185            CachePolicy     L1_cacheable;
   186            PostedPolicy    L1_posted;
   187            AllocatePolicy  L1_allocate;
   188            WritePolicy     L1_writePolicy;
   189            CachePolicy     L2_cacheable;
   190            PostedPolicy    L2_posted;
   191            AllocatePolicy  L2_allocate;
   192            WritePolicy     L2_writePolicy;
   193        };
   194
   195        metaonly struct MediumPage {
   196            Enable          pageEnabled;
   197            Ptr             logicalAddress;
   198
   199            Enable          translationEnabled;
   200            Ptr             translatedAddress;
   201
   202            Medium          size;
   203            Volatile        volatileQualifier;
   204            Enable          executeOnly;
   205            Enable          readOnly;
   206            Enable          prefetch;
   207            Enable          exclusion;
   208            CachePolicy     L1_cacheable;
   209            PostedPolicy    L1_posted;
   210            AllocatePolicy  L1_allocate;
   211            WritePolicy     L1_writePolicy;
   212            CachePolicy     L2_cacheable;
   213            PostedPolicy    L2_posted;
   214            AllocatePolicy  L2_allocate;
   215            WritePolicy     L2_writePolicy;
   216        };
   217
   218        metaonly struct SmallPage {
   219            Enable          pageEnabled;
   220            Ptr             logicalAddress;
   221
   222            Enable          translationEnabled;
   223            Ptr             translatedAddress;
   224
   225            Small           size;
   226            Volatile        volatileQualifier;
   227            Enable          executeOnly;
   228            Enable          readOnly;
   229            Enable          prefetch;
   230            Enable          exclusion;
   231            CachePolicy     L1_cacheable;
   232            PostedPolicy    L1_posted;
   233            AllocatePolicy  L1_allocate;
   234            WritePolicy     L1_writePolicy;
   235            CachePolicy     L2_cacheable;
   236            PostedPolicy    L2_posted;
   237            AllocatePolicy  L2_allocate;
   238            WritePolicy     L2_writePolicy;
   239        }
   240
   241        metaonly enum Maintenance {
   242            DO_NOT_PERFORM,
   243            PERFORM
   244        };
   245
   246        metaonly enum Invalidate {
   247            DO_NOT_INVALIDATE,
   248            INVALIDATE
   249        };
   250
   251        metaonly enum Unlock {
   252            DO_NOT_UNLOCK,
   253            UNLOCK
   254        };
   255
   256        metaonly enum Lock {
   257            DO_NOT_LOCK,
   258            LOCK
   259        };
   260
   261        metaonly enum Clean {
   262            DO_NOT_CLEAN,
   263            CLEAN
   264        };
   265
   266        metaonly struct SmallPageMaintenance {
   267            Maintenance     maintL2Cache;
   268            Maintenance     maintL1Cache2;
   269            Maintenance     maintL1Cache1;
   270            Enable          cpuInterrupt;
   271            Enable          hostInterrupt;
   272            Invalidate      invalidate;
   273            Clean           clean;
   274            Unlock          unlock;
   275            Lock            lock;
   276            Enable          preload;
   277        };
   278
   279        metaonly struct LinePage {
   280            Enable          pageEnabled;
   281            Ptr             logicalAddress;
   282
   283            Enable          translationEnabled;
   284            Ptr             translatedAddress;
   285        };
   286
   287        metaonly struct DebugPage {
   288            Enable          pageEnabled;
   289            Enable          translationEnabled;
   290            Ptr             translatedAddress;
   291        };
   292
   293        /*! The number of Large Page Desciptors is target/device specific */
   294        metaonly config LargePage largePages[] = [];
   295
   296        /*! The number of Medium Page Desciptors is target/device specific */
   297        metaonly config MediumPage mediumPages[] = [];
   298
   299        /*! The number of Small Page Desciptors is target/device specific */
   300        metaonly config SmallPage smallPages[] = [];
   301
   302        /*! The number of Line Page Desciptors is target/device specific */
   303        metaonly config LinePage linePages[] = [];
   304
   305        metaonly config DebugPage debugPage;
   306
   307        /*
   308         * Runtime representation of the MMU registers
   309         */
   310        struct MMU {
   311            Char *LARGE_ADDR[8];    /* 0800 - 001C */
   312            Char *LARGE_XLTE[8];    /* 0820 - 003C */
   313            UInt32 LARGE_POLICY[8]; /* 0840 - 005C */
   314
   315            Char *MEDIUM_ADDR[16];  /* 0860 - 009C */
   316            Char *MEDIUM_XLTE[16];  /* 08A0 - 00DC */
   317            UInt32 MEDIUM_POLICY[16]; /* 08E0 - 011C */
   318
   319            Char *SMALL_ADDR[32];   /* 0920 - 019C */
   320            Char *SMALL_XLTE[32];   /* 09A0 - 021C */
   321            UInt32 SMALL_POLICY[32];/* 0A20 - 029C */
   322            UInt32 SMALL_MAINT[32]; /* 0AA0 - 031c */
   323
   324            Char *LINE_ADDR[32];    /* 0B20 - 0B9C */
   325            Char *LINE_XLTE[32];    /* 0BA0 - 041C */
   326            UInt32 LINE_POLICY[32]; /* 0C20 - 049C */
   327
   328            Char *DEBUG_XLTE;               /* 0CA0 */
   329            UInt32 DEBUG_POLICY;    /* 0CA4 */
   330
   331            UInt32 MAINT;           /* 0CA8 */
   332            Char *MSTART;           /* 0CAC */
   333            Char *MEND;             /* 0CB0 */
   334            UInt32 MSTAT;           /* 0CB4 */
   335        };
   336
   337        /*!
   338         *  This device's AMMU register set address.
   339         *  Initialized internally according to build target/device.
   340         */
   341        extern volatile MMU mmu;
   342
   343        /*!
   344         * By default the AMMU module will configure the AMMU at startup.
   345         *
   346         * By setting this flag to false (ie for Ducati core1), the AMMU
   347         * module APIs are available but the initialization step is suppressed.
   348         */
   349        config Bool configureAmmu = true;
   350
   351        /*!
   352         *  ======== invAll ========
   353         *  Invalidate entire L1 and L2 caches
   354         *  Waits for completion.
   355         */
   356        Void invAll();
   357
   358        /*!
   359         *  @_nodoc
   360         *  ======== dumpAmmu ========
   361         *  formatted dump of the contents of the AMMU registers
   362         */
   363        Void dumpAmmu();
   364
   365    internal:
   366
   367        config UInt numLargePages;
   368        config UInt numMediumPages;
   369        config UInt numSmallPages;
   370        config UInt numLinePages;
   371
   372        /* base address of mmu registers */
   373        metaonly config Ptr baseAddr;
   374
   375        /* const image of intial mmu register values */
   376        config MMU mmuInitConfig;
   377
   378        /* String names of page sizes */
   379        metaonly config String largePageSizeStrings[];
   380        metaonly config String mediumPageSizeStrings[];
   381        metaonly config String smallPageSizeStrings[];
   382
   383        /* MMU initialization function called at startup */
   384        Void init();
   385    }
   386
   387    /*
   388     *  @(#) ti.sysbios.hal.ammu; 2, 0, 0, 0,216; 6-15-2011 16:25:51; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   389
   390     */
   391


package ti.sysbios.hal.ammu

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.hal.ammu ========
    39     *  Contains the AMMU module.
    40     *
    41     *  Designed for initial use in the omap4 Ducati and Tesla
    42     *  cpu domains.
    43     *
    44     */
    45    package ti.sysbios.hal.ammu [2,0,0,0] {
    46        module AMMU;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.hal.ammu; 2, 0, 0, 0,216; 6-15-2011 16:25:51; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.hal.unicache.Cache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Cache.xdc ========
    34     *
    35     */
    36    package ti.sysbios.hal.unicache;
    37
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Error;
    40    import xdc.runtime.Types;
    41
    42    import ti.sysbios.interfaces.ICache;
    43    import ti.sysbios.hal.Hwi;
    44
    45    /*!
    46     *  ======== Cache ========
    47     *  The unicache Cache module used by the omap4 Tesla and Ducati cores
    48     *
    49     *  The Tesla and Ducati UniCaches do not support separate program and
    50     *  data caches. Therefore none of the unique Cache_Type L1P/L1D/L2P/L2D
    51     *  operations can be precisely supported. The APIs in this module ignore
    52     *  the P/D and observe only the L1/L2 designations (ie Cache_Type_L1P
    53     *  is functionally equivalent to Cache_Type_L1D and Cache_Type_L1).
    54     *
    55     *  @a(Restrictions)
    56     *  When used within a dual M3 core (Ducati arrangement), care must be
    57     *  taken when initializing this shared resource.
    58     *  The "Shared Resources" note provided
    59     *  in the {@link ti.sysbios.family.arm.ducati ducati} package discusses
    60     *  the management of the various hardware and software resources
    61     *  shared by the two M3 cores.
    62     *
    63     *  As the unicache is shared between the two M3 cores, it should only
    64     *  be initialized and enabled once.
    65     *  It is intended that Core 0 will {@link #configureCache configure}
    66     *  the unicache at startup and then either {@link #enableCache enable}
    67     *  it at that time or later on by manually invoking
    68     *  {@link #enable Cache_enable()}.
    69     *
    70     *  The unicache Cache module is a Gated module. In a dual M3 core (Ducati)
    71     *  environment, the unicache Cache module employs a
    72     *  {@link ti.sysbios.family.arm.ducati.GateDualCore GateDualCore} gate
    73     *  to arbitrate the usage of the shared unicache registers. In a non
    74     *  shared environment such as the C64T core in an OMAP4 device, a
    75     *  {@link ti.sysbios.gates.GateHwi GateHwi} gate is used to avoid multi
    76     *  thread conflicts.
    77     *
    78     *  @a
    79     *
    80     *  @p(html)
    81     *  <h3> Calling Context </h3>
    82     *  <table border="1" cellpadding="3">
    83     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    84     *    </colgroup>
    85     *
    86     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    87     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    88     *    <!--                                                                  -->
    89     *    <tr><td> {@link #disable}     </td><td>   Y    </td><td>   Y    </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    91     *    <tr><td> {@link #enable}      </td><td>   Y    </td><td>   Y    </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    93     *    <tr><td> {@link #inv}         </td><td>   Y    </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td> {@link #wb}          </td><td>   Y    </td><td>   Y    </td>
    96     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    97     *    <tr><td> {@link #wbInv}       </td><td>   Y    </td><td>   Y    </td>
    98     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    99     *    <tr><td> {@link #wait}        </td><td>   Y    </td><td>   Y    </td>
   100     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   101     *    <tr><td colspan="6"> Definitions: <br />
   102     *       <ul>
   103     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   104     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   105     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   106     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   107     *           <ul>
   108     *             <li> In your module startup after this module is started
   109     *    (e.g. Cache_Module_startupDone() returns TRUE). </li>
   110     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   111     *             <li> During main().</li>
   112     *             <li> During BIOS.startupFxns.</li>
   113     *           </ul>
   114     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   115     *           <ul>
   116     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   117     *             <li> In your module startup before this module is started
   118     *    (e.g. Cache_Module_startupDone() returns FALSE).</li>
   119     *           </ul>
   120     *       </ul>
   121     *    </td></tr>
   122     *
   123     *  </table>
   124     *  @p
   125     */
   126
   127    @ModuleStartup
   128    @Gated
   129
   130    module Cache inherits ti.sysbios.interfaces.ICache
   131    {
   132
   133        // -------- Module Types --------
   134
   135        /*!
   136         *  Runtime representation of the Cache registers
   137         */
   138        struct CACHE {
   139            UInt32 L1_INFO;         /* 0000 */
   140            UInt32 L1_CONFIG;       /* 0004 */
   141            UInt32 L1_INT;          /* 0008 */
   142            UInt32 L1_OCP;          /* 000C */
   143            UInt32 L1_MAINT;        /* 0010 */
   144            Ptr    L1_MTSTART;      /* 0014 */
   145            Ptr    L1_MTEND;        /* 0018 */
   146            Ptr    L1_CTADDR;       /* 001c */
   147            UInt32 L1_CTDATA;       /* 0020 */
   148
   149            UInt32 Reserved[0x77];  /* 0024 - 001fc */
   150
   151            UInt32 L2_INFO;         /* 0200 */
   152            UInt32 L2_CONFIG;       /* 0204 */
   153            UInt32 L2_INT;          /* 0208 */
   154            UInt32 L2_OCP;          /* 020C */
   155            UInt32 L2_MAINT;        /* 0210 */
   156            Ptr    L2_MTSTART;      /* 0214 */
   157            Ptr    L2_MTEND;        /* 0218 */
   158            Ptr    L2_CTADDR;       /* 021c */
   159            UInt32 L2_CTDATA;       /* 0220 */
   160        };
   161
   162        /*!
   163         *  This device's unicache register set address.
   164         *  Initialized internally according to build target/device.
   165         */
   166        extern volatile CACHE cache;
   167
   168        /*!
   169         *  OCP Interface Configuration Register Settings.
   170         */
   171        struct OCPConfig {
   172            UInt8 wrap;
   173            UInt8 wrbuffer;
   174            UInt8 prefetch;
   175            UInt8 cleanbuf;
   176        }
   177
   178        /*!
   179         *  CONFIG Configuration Register Settings.
   180         */
   181        struct SecurityConfig {
   182            UInt8 secure;
   183            UInt8 nbypass;
   184            UInt8 secint;
   185            UInt8 secport;
   186            UInt8 secmain;
   187        }
   188
   189        // -------- ROV view --------
   190
   191        /*! @_nodoc */
   192        metaonly struct ModuleView {
   193            Bool        cacheEnabled;
   194        };
   195
   196        /*! @_nodoc */
   197        @Facet
   198        metaonly config ViewInfo.Instance rovViewInfo =
   199            ViewInfo.create({
   200                viewMap: [
   201                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}],
   202               ]
   203           });
   204
   205        // Errors
   206
   207        /*!
   208         *  Error raised when a Cache interrupt occurs
   209         *  Reason bits are contents of Cache Interrupt Register
   210         */
   211        config Error.Id E_exception = {
   212            msg: "E_exception: L%d reason: 0x%x"
   213        };
   214
   215        // -------- Configuration Parameters --------
   216
   217        /*!
   218         *  L1_OCP register settings
   219         */
   220        metaonly config OCPConfig ocpL1 = {
   221            wrap : 0,
   222            wrbuffer : 0,
   223            prefetch : 0
   224        };
   225
   226        /*!
   227         *  L1_CONFIG register settings
   228         */
   229        metaonly config SecurityConfig configL1 = {
   230            secure : 0,
   231            nbypass : 0,
   232            secint : 1,
   233            secport : 1,
   234            secmain : 1
   235        };
   236
   237        /*!
   238         *  L2_OCP register settings
   239         */
   240        metaonly config OCPConfig ocpL2 = {
   241            wrap : 0,
   242            wrbuffer : 0,
   243            prefetch : 0,
   244            cleanbuf : 0
   245        };
   246
   247        /*!
   248         *  L2_CONFIG register settings
   249         */
   250        metaonly config SecurityConfig configL2 = {
   251            secure : 0,
   252            nbypass : 0,
   253            secint : 1,
   254            secport : 1,
   255            secmain : 1
   256        };
   257
   258        /*!
   259         *  Configure cache at startup?
   260         *
   261         *  It is possible to configure the Cache at startup and not
   262         *  {@link #enableCache enable} it.
   263         *  However, it is not possible to enable the Cache at startup
   264         *  without configuring it.
   265         *
   266         *  Enabling the Cache will automatically enable configuring
   267         *  the Cache.
   268         */
   269        config Bool configureCache = false;
   270
   271        /*!
   272         *  Enable cache at startup?
   273         *
   274         *  Enabling the Cache at startup will force
   275         *  {@link #configureCache configuring} the Cache at startup.
   276         */
   277        config Bool enableCache = false;
   278
   279        /*!
   280         *  Maximum buffer size to use discrete cache line operations with.
   281         *
   282         *  For buffers below a certain size, cache maintenance operations are
   283         *  more efficient if performed on single cache lines at a time
   284         *  rather than on an entire region.
   285         *
   286         *  For buffer sizes equal to or less than this setting, the {@link #inv},
   287         *  {@link #wb}, and {@link #wbInv} APIs will use a series of individual
   288         *  cache line operations. For buffer sizes large than this setting, a
   289         *  a single block mode operation will be performed.
   290         *
   291         *  For M3 cores, the default setting is 1024 bytes.
   292         *  For 64T cores, the default setting is 4096 bytes.
   293         */
   294        config SizeT maxLineModeBufSize;
   295
   296        /*!
   297         *  L1 Interrupt Handler.
   298         *  Default is set to an internal L1 interrupt handler
   299         */
   300        metaonly config Hwi.FuncPtr l1InterruptHandler;
   301
   302        /*!
   303         *  L1 Interrupt number.
   304         *  Default is device unique but can be set in the user config file.
   305         */
   306        metaonly config UInt l1InterruptNumber;
   307
   308        /*!
   309         *  L1 Interrupt priority.
   310         *  Default is device unique but can be set in the user config file.
   311         */
   312        metaonly config UInt l1InterruptPriority;
   313
   314        /*!
   315         *  L2 Interrupt Handler.
   316         *  Default is set to an internal L2 interrupt handler
   317         */
   318        metaonly config Hwi.FuncPtr l2InterruptHandler;
   319
   320        /*!
   321         *  L2 Interrupt number.
   322         *  Default is device unique but can be set in the user config file.
   323         */
   324        metaonly config UInt l2InterruptNumber;
   325
   326        /*!
   327         *  L2 Interrupt priority.
   328         *  Default is device unique but can be set in the user config file.
   329         */
   330        metaonly config UInt l2InterruptPriority;
   331
   332        // -------- Module Functions --------
   333
   334        /*!
   335         *  ======== lock ========
   336         *  Locks a memory block into the cache.
   337         *
   338         *  @param(blockPtr) start address of range to be locked
   339         *  @param(byteCnt)  number of bytes to be locked
   340         *  @param(type)     bit mask of Cache type
   341         *  @param(wait)     wait until the operation is completed
   342         */
   343        @DirectCall
   344        Void lock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   345
   346        /*!
   347         *  ======== unlock ========
   348         *  Unlocks a cached memory block.
   349         *
   350         *  @param(blockPtr) start address of range to be locked
   351         *  @param(byteCnt)  number of bytes to be locked
   352         *  @param(type)     bit mask of Cache type
   353         *  @param(wait)     wait until the operation is completed
   354         */
   355        @DirectCall
   356        Void unlock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   357
   358        /*!
   359         *  ======== preload ========
   360         *  Loads a memory block into the cache.
   361         *
   362         *  @param(blockPtr) start address of range to be loaded
   363         *  @param(byteCnt)  number of bytes to be loaded
   364         *  @param(type)     bit mask of Cache type
   365         *  @param(wait)     wait until the operation is completed
   366         */
   367        @DirectCall
   368        Void preload(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   369
   370        /*!
   371         *  ======== preloadLock ========
   372         *  Loads and locks a memory block into the cache.
   373         *
   374         *  @param(blockPtr) start address of range to be loaded
   375         *  @param(byteCnt)  number of bytes to be loaded
   376         *  @param(type)     bit mask of Cache type
   377         *  @param(wait)     wait until the operation is completed
   378         */
   379        @DirectCall
   380        Void preloadLock(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   381
   382        /*!
   383         *  ======== wbAll ========
   384         *  Write back all caches
   385         *
   386         *  Perform a global write back.
   387         *  All cache lines are left valid in L1 and L2 caches and the data in L1
   388         *  cache is written back to L2 or external.  All cache lines are left
   389         *  valid in L2 cache and the data in L2 cache is written back to
   390         *  external.
   391         *  Waits for completion.
   392         */
   393        @DirectCall
   394        override Void wbAll();
   395
   396        /*!
   397         *  ======== invAll ========
   398         *  Invalidate all caches
   399         *
   400         *  Perform a global invalidate.  All cache lines are
   401         *  invalidated in L1 and L2 caches.
   402         *  Waits for completion.
   403         */
   404        @DirectCall
   405        Void invAll();
   406
   407        /*!
   408         *  ======== wbInvAll ========
   409         *  Write back invalidate all caches
   410         *
   411         *  Perform a global write back.
   412         *  Then perform a global invalidate.
   413         *  All cache lines are invalidated in L1 and L2 caches.
   414         *  Waits for completion.
   415         */
   416        @DirectCall
   417        override Void wbInvAll();
   418
   419        /*!
   420         *  ======== read ========
   421         *  Read a block of memory from the cache.
   422         *  Only whole numbers of 32 bit words are transferred.
   423         *  byteCnt is divided by 4 to convert to number of words.
   424         *
   425         *  @param(blockPtr) start address of range to be loaded
   426         *  @param(byteCnt)  number of bytes to be loaded
   427         *  @param(type)     bit mask of Cache type
   428         *  @param(destBuf)  address of destination buffer
   429         */
   430        @DirectCall
   431        Void read(Ptr blockPtr, SizeT byteCnt, Bits16 type, Ptr destBuf);
   432
   433        /*!
   434         *  @_nodoc
   435         *  ======== dumpRegs ========
   436         *  formatted dump of cache registers
   437         */
   438        Void dumpRegs();
   439
   440    internal:
   441
   442        /* initial L1 register settings */
   443        config Bits32 l1ocpConfig;
   444        config Bits32 l1secConfig;
   445
   446        /* initial L2 register settings */
   447        config Bits32 l2ocpConfig;
   448        config Bits32 l2secConfig;
   449
   450        /* device-specific L2 support enabled flag */
   451        readonly config Bool l2CacheSupported;
   452
   453        /* base address of Cache registers */
   454        metaonly config Ptr baseAddr;
   455
   456        /*!
   457         *  ======== seizeRegs ========
   458         *  seize the cache registers
   459         */
   460        UInt seizeRegs();
   461
   462        /*!
   463         *  ======== releaseRegs ========
   464         *  release the cache registers
   465         */
   466        Void releaseRegs(UInt key);
   467
   468        /*
   469         *  ======== ISR ========
   470         *  Cache Interrupt Service Routine
   471         */
   472        Void ISR(UArg level);
   473
   474        /*!
   475         *  ======== printInfo ========
   476         *  formatted dump of cache registers helper
   477         */
   478        Void printInfo(UInt info, UInt level);
   479
   480        /*!
   481         *  ======== printConfig ========
   482         *  formatted dump of cache registers helper
   483         */
   484        Void printConfig(UInt cfg, UInt level);
   485
   486        /*!
   487         *  ======== printOCP ========
   488         *  formatted dump of cache registers helper
   489         */
   490        Void printOCP(UInt cfg, UInt level);
   491    }
   492
   493    /*
   494     *  @(#) ti.sysbios.hal.unicache; 2, 0, 0, 0,215; 6-15-2011 16:25:56; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   495
   496     */
   497


package ti.sysbios.hal.unicache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.hal.unicache ========
    39     *  Contains the unicache Cache module.
    40     *
    41     *  Designed for initial use in the omap4 Ducati and Tesla
    42     *  cpu domains.
    43     *
    44     */
    45    package ti.sysbios.hal.unicache [2,0,0,0] {
    46        module Cache;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.hal.unicache; 2, 0, 0, 0,215; 6-15-2011 16:25:56; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.heaps.HeapBuf

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== HeapBuf.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.heaps;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    /*!
    42     *  ======== HeapBuf ========
    43     *  Fixed size buffer heap manager
    44     *
    45     *  The HeapBuf manager provides functions to allocate and free storage from a
    46     *  heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single
    47     *  fixed-size buffer, split into equally sized allocable blocks.
    48     *
    49     *  The HeapBuf manager is intended as a very fast and deterministic memory
    50     *  manager which can only allocate blocks of a single size. It is ideal for
    51     *  managing a heap that is only used for allocating a single type of object,
    52     *  or for objects that have very similar sizes.
    53     *
    54     *  Allocation from and freeing to a HeapBuf instance is non-blocking and
    55     *  deterministic: a call to alloc or free will always take the same amount of
    56     *  time.
    57     *
    58     *  Constraints:
    59     *  @p(blist)
    60     *  - Align parameter must be set to 0 for default, or be a power of 2 that is
    61     *    greater than or equal to the value returned by
    62     *    {@link xdc.runtime.Memory#getMaxDefaultTypeAlign}.
    63     *  - The buffer passed to dynamically create a HeapBuf must be aligned
    64     *    according to the alignment parameter, and must be large enough to account
    65     *    for the actual block size after it has been rounded up to a multiple of
    66     *    the alignment.
    67     *  @p
    68     *
    69     *  @p(html)
    70     *  <h3> Calling Context </h3>
    71     *  <table border="1" cellpadding="3">
    72     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    73     *    </colgroup>
    74     *
    75     *    <tr><th> Function    </th><th>  Hwi   </th><th>  Swi   </th>
    76     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    77     *    <!--                                       -->
    78     *    <tr><td> Params_init      </td><td>   Y    </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    80     *    <tr><td> alloc            </td><td>   Y    </td><td>   Y    </td>
    81     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> construct        </td><td>   Y    </td><td>   Y    </td>
    83     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> create           </td><td>   N*   </td><td>   N*   </td>
    85     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> delete           </td><td>   N*   </td><td>   N*   </td>
    87     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> destruct         </td><td>   Y    </td><td>   Y    </td>
    89     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> free             </td><td>   Y    </td><td>   Y    </td>
    91     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    92     *    <tr><td> getStats         </td><td>   Y    </td><td>   Y    </td>
    93     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> getExtendedStats </td><td>   Y    </td><td>   Y    </td>
    95     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> isBlocking       </td><td>   Y    </td><td>   Y    </td>
    97     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td colspan="6"> Definitions: <br />
    99     *       <ul>
   100     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   101     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   102     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   103     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   104     *           <ul>
   105     *             <li> In your module startup after this module is started
   106     *    (e.g. HeapBuf_Module_startupDone() returns TRUE). </li>
   107     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   108     *             <li> During main().</li>
   109     *             <li> During BIOS.startupFxns.</li>
   110     *           </ul>
   111     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   112     *           <ul>
   113     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   114     *             <li> In your module startup before this module is started
   115     *    (e.g. HeapBuf_Module_startupDone() returns FALSE).</li>
   116     *           </ul>
   117     *       </ul>
   118     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   119     *       <li> <b>**</b>: Assuming GateMutex is used as HeapMem's Gate. </li>
   120     *       <li> <b>+</b> : Cannot use HeapMem object while it is being
   121     *    restored. </li>
   122     *    </td></tr>
   123     *
   124     *  </table>
   125     *  @p
   126     */
   127
   128    @InstanceInitError /* Initialization may throw errors */
   129    @ModuleStartup     /* Instances require more initialization at startup */
   130    @InstanceFinalize  /* Destroys the freeList Q */
   131
   132    module HeapBuf inherits xdc.runtime.IHeap {
   133
   134        /*!
   135         *  ======== BasicView ========
   136         *  @_nodoc
   137         */
   138        metaonly struct BasicView {
   139            String    label;
   140            xdc.runtime.Memory.Size bufSize;    /* Size of the entire buffer */
   141            SizeT     blockSize;
   142            UInt      numBlocks;
   143            Int       totalFreeSize;
   144            UInt      numberAllocatedBlocks;
   145            UInt      numFreeBlocks;
   146            UInt      maxAllocatedBlocks;
   147            Ptr       buf;
   148
   149            /* statStr contains "quick" info 4 HeapBuf that other mods will
   150             * display. statStr won't be displayed by the HeapBuf ROV view itself.
   151             */
   152            String    statStr;
   153        }
   154
   155        /*!
   156         *  ======== DetailedView ========
   157         *  @_nodoc
   158         */
   159        metaonly struct DetailedView {
   160            String    label;
   161            xdc.runtime.Memory.Size bufSize;    /* Size of the entire buffer */
   162            SizeT     blockSize;
   163            UInt      numBlocks;
   164            Int       totalFreeSize;
   165            UInt      numberAllocatedBlocks;
   166            UInt      numFreeBlocks;
   167            UInt      maxAllocatedBlocks;
   168            Ptr       buf;
   169            Ptr       freeList;
   170
   171            /* statStr contains "quick" info 4 HeapBuf that other mods will
   172             * display. statStr won't be displayed by the HeapBuf ROV view itself.
   173             */
   174            String    statStr;
   175        }
   176
   177        /*! @_nodoc */
   178        @Facet
   179        metaonly config ViewInfo.Instance rovViewInfo =
   180            ViewInfo.create({
   181                viewMap: [
   182                        ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitInstance', structName: 'BasicView'}],
   183                        ['Detailed', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDetailed', structName: 'DetailedView'}]
   184                ]
   185            });
   186
   187        /*!
   188         *  ======== ExtendedStats ========
   189         *  Stat structure for the HeapBuf_getExtendedStats function
   190         *
   191         *  @field(maxAllocatedBlocks) The maximum number of blocks allocated from
   192         *                             this heap at any single point in time, during
   193         *                             the lifetime of this HeapBuf instance.
   194         *
   195         *  @field(numAllocatedBlocks) The total number of blocks currently
   196         *                             allocated in this HeapBuf instance.
   197         */
   198        struct ExtendedStats {
   199            UInt maxAllocatedBlocks;
   200            UInt numAllocatedBlocks;
   201        }
   202
   203        /*!
   204         *  ======== A_nullBuf ========
   205         *  Null buf parameter
   206         *
   207         *  This Assert is raised when the buf parameter has been omitted (null)
   208         *  for a dynamic create.
   209         */
   210        config xdc.runtime.Assert.Id A_nullBuf =
   211            {msg: "buf parameter cannot be null"};
   212
   213        /*!
   214         *  ======== A_bufAlign ========
   215         *  Misalligned buffer
   216         *
   217         *  This Assert is raised when the buf parameter has not been aligned
   218         *  on the requested alignment.
   219         */
   220        config xdc.runtime.Assert.Id A_bufAlign =
   221            {msg: "buf not properly aligned"};
   222
   223        /*!
   224         *  ======== A_invalidAlign ========
   225         *  Invalid alignment
   226         *
   227         *  This Assert is raised when the align parameter is not the default
   228         *  value of zero, or a power of 2 that is greater than or equal to
   229         *  the value defined by
   230         *  {@link xdc.runtime.Memory#getMaxDefaultTypeAlign}.
   231         */
   232        config xdc.runtime.Assert.Id A_invalidAlign =
   233            {msg: "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"};
   234
   235        /*!
   236         *  ======== A_zeroBlockSize ========
   237         *  Assert raised when the blockSize parameter is 0
   238         */
   239        config xdc.runtime.Assert.Id A_zeroBlockSize =
   240            {msg: "blockSize cannot be zero"};
   241
   242        /*!
   243         *  ======== A_zeroBlocks ========
   244         *  Assert raised when the numBlocks parameter is 0
   245         */
   246        config xdc.runtime.Assert.Id A_zeroBlocks =
   247            {msg: "numBlocks cannot be zero"};
   248
   249        /*!
   250         *  ======== A_zeroBufSize ========
   251         *  Assert raised when the bufSize parameter is 0
   252         */
   253        config xdc.runtime.Assert.Id A_zeroBufSize =
   254            {msg: "bufSize cannot be zero"};
   255
   256        /*!
   257         *  ======== A_invalidBufSize ========
   258         *  Invalid buffer size
   259         *
   260         *  This Assert is raised when the bufSize parameter is too small
   261         *  to handle requested blocks.
   262         */
   263        config xdc.runtime.Assert.Id A_invalidBufSize =
   264            {msg: "HeapBuf_create's bufSize parameter is invalid (too small)"};
   265
   266        /*!
   267         *  ======== A_noBlocksToFree ========
   268         *  No allocated blocks
   269         *
   270         *  This Assert is raised when free is called and there are no blocks
   271         *  allocated.
   272         */
   273        config xdc.runtime.Assert.Id A_noBlocksToFree =
   274            {msg: "Cannot call HeapBuf_free when no blocks have been allocated"};
   275
   276        /*!
   277         *  ======== A_invalidFree ========
   278         *  Assert raised when an invalid free occurs
   279         *
   280         *  This assert can be caused when passing a NULL pointer to the free.
   281         */
   282        config xdc.runtime.Assert.Id A_invalidFree =
   283            {msg: "A_invalidFree: Invalid free"};
   284
   285        /*!
   286         *  ======== E_size ========
   287         *  Raised when requested size exceeds blockSize
   288         */
   289        config xdc.runtime.Error.Id E_size =
   290            {msg: "requested size is too big: handle=0x%x, size=%u"};
   291
   292        /*!
   293         *  ======== trackMaxAllocs ========
   294         *  Track maximum number of allocations
   295         *
   296         *  This will enable/disable the tracking of the maximum number of
   297         *  allocations for a HeapBuf instance.  This maximum refers to the "all
   298         *  time" maximum number of allocations for the history of a HeapBuf
   299         *  instance, not the current number of allocations.
   300         */
   301        config Bool trackMaxAllocs = false;
   302
   303    instance:
   304
   305        /*!
   306         *  ======== align ========
   307         *  Alignment (in MAUs) of each block
   308         *
   309         *  The alignment must be a power of 2 that is greater than or equal to
   310         *  the target dependent value defined by
   311         *  {@link xdc.runtime.Memory#getMaxDefaultTypeAlign}. If the default value
   312         *  of 0 is specified, this value will be changed to be the minimum
   313         *  structure alignment requirement, as defined by
   314         *  {@link xdc.runtime.Memory#getMaxDefaultTypeAlign}.
   315         *
   316         *  For static creates, the HeapBuf module will allocate space for the
   317         *  buffer and will align it on this requested alignment.
   318         *
   319         *  For dynamic creates, this parameter is used solely for error checking.
   320         *  The buffer provided to a dynamically created HeapBuf must be aligned
   321         *  manually, and an assert will be raised if the buffer is not properly
   322         *  aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to
   323         *  satisfy the alignment.
   324         *
   325         */
   326        config SizeT align = 0;
   327
   328        /*!
   329         *  ======== sectionName ========
   330         *  Section name for the buffer managed by the instance
   331         *
   332         *  The buffer allocated for a statically created HeapBuf instance will be
   333         *  placed in this section.
   334         *
   335         *  The default section is the 'dataSection' in the platform.
   336         */
   337        metaonly config String sectionName = null;
   338
   339        /*!
   340         *  ======== numBlocks ========
   341         *  Number of fixed-size blocks
   342         *
   343         *  Required parameter.
   344         *
   345         *  The default number of blocks is 0.
   346         */
   347        config UInt numBlocks = 0;
   348
   349        /*!
   350         *  ======== blockSize ========
   351         *  Size (in MAUs) of each block
   352         *
   353         *  HeapBuf will round the blockSize up to the nearest multiple of the
   354         *  alignment, so the actual blockSize may be larger. When creating a
   355         *  HeapBuf dynamically, this needs to be taken into account to determine
   356         *  the proper buffer size to pass in.
   357         *
   358         *  Required parameter.
   359         *
   360         *  The default size of the blocks is 0 MAUs.
   361         */
   362        config SizeT blockSize = 0;
   363
   364        /*!
   365         *  ======== bufSize ========
   366         *  Size (in MAUs) of the entire buffer; for dynamic creates only
   367         *
   368         *  When dynamically creating a HeapBuf, this should be the actual size
   369         *  of the memory buffer provided for HeapBuf to manage.
   370         *
   371         *  This parameter is used solely for error checking; an Error is raised
   372         *  if the bufSize is too small for the requested blockSize and numBlocks.
   373         *  Because of minimum alignment considerations, it's easy to provide too
   374         *  small of a buffer to manage, and difficult to detect if it happened.
   375         *
   376         *  This parameter is required for dynamic creates and ignored for static
   377         *  creates.
   378         *
   379         *  The default buffer size is 0 MAUs.
   380         */
   381        config xdc.runtime.Memory.Size bufSize = 0;
   382
   383        /*!
   384         *  ======== buf ========
   385         *  User supplied buffer; for dynamic creates only
   386         *
   387         *  The caller must supply the memory buffer for a dynamically created
   388         *  HeapBuf to manage. The provided buffer must be aligned according to the
   389         *  HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter
   390         *  is 128, then the buffer's start address must be a multiple of 128.
   391         *
   392         *  For static creates, the buffer is allocated automatically based on the
   393         *  blockSize and numBlocks parameters.
   394         *
   395         *  This parameter is required for dynamic creates and ignored for static
   396         *  creates.
   397         *
   398         */
   399        config Ptr buf = 0;
   400
   401        /*!
   402         *  ======== alloc ========
   403         *  @HeapBuf All alignment is handled in the create, therefore the
   404         *  align argument in alloc is ignored.
   405         *
   406         *  HeapBuf_alloc will only fail if there are no available blocks or if the
   407         *  requested block size is larger than the HeapBuf's blockSize. All other
   408         *  requests, regardless of size, will succeed.
   409         */
   410        @DirectCall
   411        override Ptr alloc(SizeT size, SizeT align, xdc.runtime.Error.Block *eb);
   412
   413        /*!
   414         *  ======== isBlocking ========
   415         *  @HeapBuf This function always returns FALSE since the alloc/free
   416         *  never block on a resource.
   417         */
   418        @DirectCall
   419        override Bool isBlocking();
   420
   421        /*!
   422         *  ======== getBlockSize ========
   423         *  @_nodoc
   424         *  Returns the HeapBuf's actual blockSize (adjusted for alignment)
   425         *
   426         *  This getter is provided to allow other memory managers to build off
   427         *  of HeapBuf.
   428         *
   429         *  The blockSize returned has been adjusted to match the alignment,
   430         *  so it may be larger than the user-specified blockSize.
   431         */
   432        @DirectCall
   433        SizeT getBlockSize();
   434
   435        /*!
   436         *  ======== getAlign ========
   437         *  @_nodoc
   438         *  Returns the HeapBuf's actual alignment (adjusted for minimum
   439         *  alignment requirements)
   440         *
   441         *  This getter is provided to allow other memory managers to build off
   442         *  of HeapBuf.
   443         */
   444        @DirectCall
   445        SizeT getAlign();
   446
   447        /*!
   448         *  ======== getEndAddr ========
   449         *  @_nodoc
   450         *  Returns the last address in the buffer managed by the HeapBuf
   451         *
   452         *  This getter is provided to allow other memory managers to build off
   453         *  of HeapBuf:  Compare a block's address to the end address of the buffer
   454         *  to determine which buffer the block came from. The end address is the
   455         *  last address in the buffer, not the next address after the buffer.
   456         *
   457         *  This will not return the correct value after addMemory has been called
   458         *  to add a noncontiguous buffer of memory to the HeapBuf.
   459         *
   460         */
   461        @DirectCall
   462        Ptr getEndAddr();
   463
   464        /*! ======== getExtendedStats ========
   465         *  Retrieves the extended statistics for a HeapBuf instance.
   466         *
   467         *  This function retrieves the extended statistics for a HeapBuf instance.
   468         *  It does not retrieve the standard xdc.runtime.Memory.Stats information.
   469         *
   470         *  @param(stats)  Location for the returned extended statistics.
   471         */
   472        @DirectCall
   473        Void getExtendedStats(ExtendedStats *stats);
   474
   475        /*!
   476         *  ======== mergeHeapBufs ========
   477         *  @_nodoc
   478         */
   479        @DirectCall
   480        Void mergeHeapBufs(HeapBuf.Handle heapBuf2);
   481
   482    internal:   /* not for client use */
   483        /*!
   484         *  ======== numConstructedHeaps ========
   485         *  @_nodoc
   486         *  Number of statically constructed Heap objects.
   487         *  Shouldn't be set directly by the user's
   488         *  config (it gets set by instance$static$init).
   489         */
   490        config UInt numConstructedHeaps = 0;
   491
   492        /*
   493         *  ======== Instance_State ========
   494         *  Instance state
   495         */
   496        struct Instance_State {
   497            SizeT        blockSize;             /* True size of each block       */
   498            SizeT        align;                 /* Alignment of each block       */
   499            UInt         numBlocks;             /* Number of individual blocks.  */
   500            xdc.runtime.Memory.Size bufSize;    /* Size of the entire buffer     */
   501            Char         buf[];                 /* Memory managed by instance    */
   502            ti.sysbios.knl.Queue.Object freeList;  /* List of free buffers      */
   503            UInt         numFreeBlocks;
   504            UInt         minFreeBlocks;         /* used to compute max # allocs  */
   505        };
   506
   507        /*
   508         *  ======== Module_State ========
   509         *  Module state
   510         */
   511        struct Module_State {
   512            Handle  constructedHeaps[];         /* array of statically */
   513                                                /* constructed Heaps */
   514        };
   515    }
   516    /*
   517     *  @(#) ti.sysbios.heaps; 2, 0, 0, 0,494; 6-15-2011 16:26:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   518
   519     */
   520


module ti.sysbios.heaps.HeapMem

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== HeapMem.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.heaps;
    38
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Memory;
    41    import xdc.runtime.Error;
    42
    43    /*!
    44     *  ======== HeapMem ========
    45     *  Variable size buffer heap manager
    46     *
    47     *  HeapMem manager provides functions to allocate and free storage from a
    48     *  heap of type HeapMem which inherits from IHeap.
    49     *
    50     *  @p(html)
    51     *  <h3> HeapMem Gate </h3>
    52     *  A HeapMem instance will use the HeapMem module Gate to protect any accesses
    53     *  to its list of free memory blocks. The HeapMem instance will enter and
    54     *  leave the module Gate when allocating blocks, freeing blocks, and
    55     *  retrieving statistics about the HeapMem.
    56     *
    57     *  By default, the Gate is of type GateMutex.
    58     *
    59     *  A different Gate can be specified using the common$.gate parameter.
    60     *  For example, to use a GateTask to protect HeapMem:
    61     *      HeapMem.common$.gate = GateTask.create();
    62     *
    63     *  To save on overhead, HeapMem does not create additional Gate instances on a
    64     *  per-instance basis; there is only one Gate instance shared across all of
    65     *  the HeapMem instances. Therefore, the HeapMem.common$.gateParams parameter
    66     *  (used for configuring per-instance Gates) is ignored.
    67     *
    68     *  The type of Gate used should be chosen based on the type of threads (Hwi,
    69     *  Swi, Task, etc.) using the heap. It should also consider the
    70     *  non-deterministic nature of the HeapMem. A call to alloc or free will
    71     *  traverse a list of free blocks, so a GateHwi, for example, is likely an
    72     *  inappropriate Gate for HeapMem.
    73     *
    74     *  @p(html)
    75     *  <h3> Calling Context </h3>
    76     *  <table border="1" cellpadding="3">
    77     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    78     *    </colgroup>
    79     *
    80     *    <tr><th> Function    </th><th>  Hwi   </th><th>  Swi   </th>
    81     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    82     *    <!--                                     -->
    83     *    <tr><td> Params_init         </td><td>   Y    </td><td>   Y    </td>
    84     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    85     *    <tr><td> alloc               </td><td>   N**  </td><td>   N**  </td>
    86     *    <td>   Y**  </td><td>   Y    </td><td>   N    </td></tr>
    87     *    <tr><td> construct           </td><td>   Y    </td><td>   Y    </td>
    88     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> create              </td><td>   N*   </td><td>   N*   </td>
    90     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> delete              </td><td>   N*   </td><td>   N*   </td>
    92     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> destruct            </td><td>   Y    </td><td>   Y    </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> free                </td><td>   N**  </td><td>   N**  </td>
    96     *    <td>   Y**  </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> getExtendedStats    </td><td>   Y    </td><td>   Y    </td>
    98     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    99     *    <tr><td> getStats            </td><td>   N**  </td><td>   N**  </td>
   100     *    <td>   Y**  </td><td>   Y    </td><td>   N    </td></tr>
   101     *    <tr><td> isBlocking          </td><td>   Y    </td><td>   Y    </td>
   102     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   103     *    <tr><td> restore             </td><td>   Y+   </td><td>   Y+   </td>
   104     *    <td>   Y+   </td><td>   Y    </td><td>   N    </td></tr>
   105     *    <tr><td colspan="6"> Definitions: <br />
   106     *       <ul>
   107     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   108     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   109     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   110     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   111     *           <ul>
   112     *             <li> In your module startup after this module is started
   113     *    (e.g. HeapMem_Module_startupDone() returns TRUE). </li>
   114     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   115     *             <li> During main().</li>
   116     *             <li> During BIOS.startupFxns.</li>
   117     *           </ul>
   118     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   119     *           <ul>
   120     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   121     *             <li> In your module startup before this module is started
   122     *    (e.g. HeapMem_Module_startupDone() returns FALSE).</li>
   123     *           </ul>
   124     *       <li> <b>*</b> : Assuming blocking Heap is used for creation. </li>
   125     *       <li> <b>**</b>: Assuming GateMutex is used as HeapMem's Gate. </li>
   126     *       <li> <b>+</b> : Cannot use HeapMem object while it is being
   127     *    restored. </li>
   128     *       </ul>
   129     *    </td></tr>
   130     *
   131     *  </table>
   132     *  @p
   133     */
   134    @Gated
   135    module HeapMem inherits xdc.runtime.IHeap {
   136
   137        /*! @_nodoc */
   138        @XmlDtd
   139        metaonly struct BasicView {
   140            String            label;
   141            Ptr               buf;
   142            String            sectionName;
   143        }
   144
   145        /*! @_nodoc */
   146        @XmlDtd
   147        metaonly struct DetailedView {
   148            String            label;
   149            Ptr               buf;
   150            String            sectionName;
   151            Memory.Size       totalSize;
   152            Memory.Size       totalFreeSize;
   153            Memory.Size       largestFreeSize;
   154        }
   155
   156        /*!
   157         *  ======== FreeBlockView ========
   158         *  @_nodoc
   159         */
   160        metaonly struct FreeBlockView {
   161            String         Address;
   162            String         size;
   163            String         status;
   164        }
   165
   166        /*! @_nodoc */
   167        @Facet
   168        metaonly config ViewInfo.Instance rovViewInfo =
   169            ViewInfo.create({
   170                viewMap: [
   171                [
   172                    'Basic',
   173                    {
   174                        type: ViewInfo.INSTANCE,
   175                        viewInitFxn: 'viewInitBasic',
   176                        structName: 'BasicView'
   177                    }
   178                ],
   179                [
   180                    'Detailed',
   181                    {
   182                        type: ViewInfo.INSTANCE,
   183                        viewInitFxn: 'viewInitDetailed',
   184                        structName: 'DetailedView'
   185                    }
   186                ],
   187                [
   188                    'FreeList',
   189                    {
   190                        type: ViewInfo.INSTANCE_DATA,
   191                        viewInitFxn: 'viewInitData',
   192                        structName: 'FreeBlockView'
   193                    }
   194                ]
   195                ]
   196            });
   197
   198
   199        /*!
   200         *  ======== ExtendedStats ========
   201         *  Stat structure for the HeapMem_getExtendedStats function
   202         *
   203         *  @field(buf)           Base address of the internal buffer.
   204         *                        This may be different from the original buf
   205         *                        parameter due to alignment requirements.
   206         *  @field(size)          Size of the internal buffer.
   207         *                        This may be different from the original size
   208         *                        parameter due to alignment requirements.
   209         */
   210        struct ExtendedStats {
   211            Ptr   buf;
   212            SizeT size;
   213        }
   214
   215        /*!
   216         *  ======== A_zeroBlock ========
   217         *  Assert raised when a block of size 0 is requested
   218         *
   219         *  This error can also be raised if the requested size wraps
   220         *  the contents of a SizeT type when it is adjusted for a minimum
   221         *  alignment. For example, when SizeT is 16-bits and a size request
   222         *  is made for 0xFFFB.
   223         */
   224        config xdc.runtime.Assert.Id A_zeroBlock =
   225            {msg: "A_zeroBlock: Cannot allocate size 0"};
   226
   227        /*!
   228         *  ======== A_heapSize ========
   229         *  Assert raised when the requested heap size is too small
   230         */
   231        config xdc.runtime.Assert.Id A_heapSize =
   232            {msg: "A_heapSize: Requested heap size is too small"};
   233
   234        /*!
   235         *  ======== A_align ========
   236         *  Assert raised when the requested alignment is not a power of 2
   237         */
   238        config xdc.runtime.Assert.Id A_align =
   239            {msg: "A_align: Requested align is not a power of 2"};
   240
   241        /*!
   242         *  ======== E_memory ========
   243         *  Raised when requested size exceeds largest free block
   244         */
   245        config Error.Id E_memory = {msg: "out of memory: handle=0x%x, size=%u"};
   246
   247        /*!
   248         *  ======== A_invalidFree ========
   249         *  Assert raised when the free detects that an invalid addr or size
   250         *
   251         *  This could arise when multiple frees are done on the same buffer or
   252         *  if corruption occurred.
   253         *
   254         *  This also could occur when an alloc is made with size N and the
   255         *  free for this buffer specifies size M where M > N. Note: not every
   256         *  case is detectable.
   257         *
   258         *  This assert can also be caused when passing an invalid addr to free
   259         *  or if the size is causing the end of the buffer to be
   260         *  out of the expected range.
   261         */
   262        config xdc.runtime.Assert.Id A_invalidFree =
   263            {msg: "A_invalidFree: Invalid free"};
   264
   265        /*!
   266         *  ======== enter ========
   267         *  @_nodoc
   268         *  Enter the module's gate. This is needed to support
   269         *  the legacy MEM module. It allows MEM to use the same
   270         *  gate for thread-safety.
   271         */
   272        @DirectCall
   273        IArg enter();
   274
   275        /*!
   276         *  ======== leave ========
   277         *  @_nodoc
   278         *  Leave the module's gate. This is needed to support
   279         *  the legacy MEM module. It allows MEM to use the same
   280         *  gate for thread-safety.
   281         */
   282        @DirectCall
   283        Void leave(IArg key);
   284
   285    instance:
   286
   287       /*!
   288        *  ======== align ========
   289        *  Alignment of the buffer being managed by this heap instance
   290        *
   291        *  In the static HeapMem.create() call, the buffer allocated for the
   292        *  HeapMem instance will have the alignment specified by this parameter.
   293        *
   294        *  In the dynamic case, the client must supply the buffer, so it is the
   295        *  client's responsibility to manage the buffer's alignment, and there is
   296        *  no 'align' parameter.
   297        *
   298        *  The specified alignment must be a power of 2.
   299        *
   300        *  HeapMem requires that the buffer be aligned on a target-specific minimum
   301        *  alignment, and will adjust (round up) the requested alignment as
   302        *  necessary to satisfy this requirement.
   303        *
   304        *  The default alignment is 0.
   305        */
   306       metaonly config SizeT align = 0;
   307
   308       /*!
   309        *  ======== sectionName ========
   310        *  Section name for the buffer managed by the instance
   311        *
   312        *  The default section is the 'dataSection' in the platform.
   313        */
   314       metaonly config String sectionName = null;
   315
   316       /*!
   317        *  ======== buf ========
   318        *  Buffer being managed by this heap instance
   319        *
   320        *  This parameter is ignored in the static HeapMem.create() call. It is a
   321        *  required parameter in the dynamic HeapMem_create() call.
   322        *
   323        *  HeapMem requires that the buffer be aligned on a target-specific minimum
   324        *  alignment, and will adjust the buffer's start address and size as
   325        *  necessary to satisfy this requirement.
   326        */
   327       config Ptr buf = 0;
   328
   329       /*!
   330        *  ======== size ========
   331        *  Size of buffer being managed by this heap instance
   332        *
   333        *  The usable size may be smaller depending on alignment requirements.
   334        */
   335       config Memory.Size size = 0;
   336
   337        /*!
   338         *  ======== alloc ========
   339         *
   340         *  @HeapMem
   341         *  The actual block returned may be larger than requested to satisfy
   342         *  alignment requirements
   343         *
   344         *  HeapMem_alloc() will lock the heap using the HeapMem Gate while it
   345         *  traverses the list of free blocks to find a large enough block for
   346         *  the request.
   347         *
   348         *  Guidelines for using large heaps and multiple alloc() calls.
   349         *  @p(blist)
   350         *          - If possible, allocate larger blocks first. Previous
   351         *            allocations of small memory blocks can reduce the size
   352         *            of the blocks available for larger memory allocations.
   353         *          - Realize that alloc() can fail even if the heap contains a
   354         *            sufficient absolute amount of unallocated space. This is
   355         *            because the largest free memory block may be smaller than
   356         *            total amount of unallocated memory.
   357         *  @p
   358         */
   359        @DirectCall
   360        override Ptr alloc(SizeT size, SizeT align, xdc.runtime.Error.Block *eb);
   361
   362        /*!
   363         *  ======== free ========
   364         *
   365         *  @HeapMem
   366         *  free() places the memory block specified by addr and size back into the
   367         *  free pool of the heap specified. The newly freed block is combined with
   368         *  any adjacent free blocks. The space is then available for further
   369         *  allocation by alloc().
   370         *
   371         *  free() will lock the heap using the HeapMem Gate, if one is specified
   372         *  using 'HeapMem.common$.gate'.
   373         */
   374        @DirectCall
   375        override Void free(Ptr block, SizeT size);
   376
   377        /*!
   378         *  ======== isBlocking ========
   379         *
   380         *  @HeapMem
   381         *  This function queries the gate (as specified by 'HeapMem.common$.gate')
   382         *  to determine if the alloc/free can be blocking.
   383         */
   384        @DirectCall
   385        override Bool isBlocking();
   386
   387        /*!
   388         *  ======== getStats ========
   389         *
   390         *  @HeapMem
   391         *  getStats() will lock the heap using the HeapMem Gate while it retrieves
   392         *  the HeapMem's statistics.
   393         *
   394         *  The returned totalSize reflects the usable size of the buffer, not
   395         *  necessarily the size specified during create.
   396         */
   397        @DirectCall
   398        override Void getStats(xdc.runtime.Memory.Stats *stats);
   399
   400
   401        /*!
   402         *  ======== restore ========
   403         *  Restores an instance to its original created state
   404         *
   405         *  This function restores a static or dynamically created instance to
   406         *  its original created state. Any memory previously allocated from the
   407         *  heap is no longer valid after this API is called. This function
   408         *  does not check whether there is allocated memory or not.
   409         */
   410        @DirectCall
   411        Void restore();
   412
   413        /*!
   414         *  ======== getExtendedStats ========
   415         *  Retrieves the extended statistics for a HeapMem instance
   416         *
   417         *  This function retrieves the extended statistics for a HeapMem instance.
   418         *  It does not retrieve the standard xdc.runtime.Memory.Stats information.
   419         *
   420         *  @param(stats)  Location for the returned extended statistics.
   421         */
   422        @DirectCall
   423        Void getExtendedStats(ExtendedStats *stats);
   424
   425    internal:   /* not for client use */
   426
   427        /*!
   428         *  ======== init ========
   429         *  Initialize instance at runtime
   430         *
   431         *  This function is plugged as a Startup.firstFxn so that the
   432         *  HeapMem objects are ready and usable by malloc() and
   433         *  Memory_alloc() by the time the module startup functions
   434         *  get called so that any calls to atexit(), which in some targets
   435         *  invokes malloc(), will be handled cleanly.
   436         */
   437        Void init();
   438
   439        /* Required alignment. Must be a power of 2 */
   440        config Int reqAlign;
   441
   442        /* Required alignment mask. reqAlign - 1 */
   443        config Int reqAlignMask;
   444
   445        /* Header maintained at the lower address of every free block */
   446        struct Header {
   447            Header *next;
   448            Memory.Size size;
   449        };
   450
   451        struct Instance_State {
   452            xdc.runtime.Memory.Size align;
   453            Char                    buf[];      /* The heap used by HeapMem. */
   454            Header                  head;       /* First free block pointer.
   455                                                 * The size field will be used
   456                                                 * to store original heap size.
   457                                                 */
   458        };
   459    }
   460
   461    /*
   462     *  @(#) ti.sysbios.heaps; 2, 0, 0, 0,494; 6-15-2011 16:26:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   463
   464     */
   465


module ti.sysbios.heaps.HeapMultiBuf

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== HeapMultiBuf.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.heaps;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    /*!
    42     *  ======== HeapMultiBuf ========
    43     *  Multiple fixed size buffer heap manager
    44     *
    45     *  The HeapMultiBuf manager provides functions to allocate and free storage
    46     *  from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf
    47     *  manages multiple fixed-size memory buffers. Each buffer contains a fixed
    48     *  number of allocable memory 'blocks' of the same size. Simply put, a
    49     *  HeapMultiBuf instance manages a collection of HeapBuf instances.
    50     *  HeapMultiBuf is intended as a fast and deterministic memory manager which
    51     *  can service requests for blocks of arbitrary size.
    52     *
    53     *  An example HeapMultiBuf instance might have sixteen 32-byte blocks in one
    54     *  buffer, and four 128-byte blocks in another buffer. A request for memory
    55     *  will be serviced by the smallest possible block, so a request for 100
    56     *  bytes would receive a 128-byte block in our example.
    57     *
    58     *  Allocating from HeapMultiBuf will try to return a block from the first
    59     *  buffer which has:
    60     *
    61     *    1. A block size that is >= to the requested size
    62     *
    63     *    AND
    64     *
    65     *    2. An alignment that is >= to the requested alignment
    66     *
    67     *  If the first matching buffer is empty, HeapMultiBuf will only continue
    68     *  searching for a block if 'block borrowing' is enabled (see Block
    69     *  Borrowing).
    70     *
    71     *  @p(html)
    72     *  <h4>HeapMultiBuf and HeapBuf</h4>
    73     *  The HeapMultiBuf module is built on top of the HeapBuf module. Each buffer
    74     *  in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration
    75     *  of a HeapMultiBuf is done by providing an array of configured HeapBuf
    76     *  parameter structures. Refer to the HeapBuf documentation for information on
    77     *  the buffer parameters. All of the documentation and parameters for HeapBuf
    78     *  apply equally to HeapMultiBuf.
    79     *  Another consequence of this is that configuration checking is left to the
    80     *  HeapBuf module. If a buffer in a HeapMultiBuf has been incorrectly
    81     *  configured (with blockSize = 0, for example), HeapBuf, not HeapMultiBuf,
    82     *  will raise an Assert.
    83     *  Since HeapMultiBuf is built on HeapBuf, it simply performs the logic to
    84     *  determine which HeapBuf to allocate a block from or which HeapBuf to free
    85     *  a block to.
    86     *
    87     *  @p(html)
    88     *  <h4>Configuration Example</h4>
    89     *  The following configuration code creates a HeapMultiBuf instance which
    90     *  manages 3 pools of 10 blocks each, with block sizes of 64, 128 and 256.
    91     *
    92     *  @p(code)
    93     *  var HeapMultiBuf = xdc.useModule('ti.sysbios.heaps.HeapMultiBuf');
    94     *  var HeapBuf = xdc.useModule('ti.sysbios.heaps.HeapBuf');
    95     *
    96     *  // Create parameter structure for HeapMultiBuf instance.
    97     *  var hmbParams = new HeapMultiBuf.Params();
    98     *  hmbParams.numBufs = 3;
    99     *
   100     *  // Create the parameter structures for each of the three
   101     *  // HeapBufs to be managed by the HeapMultiBuf instance.
   102     *  hmbParams.bufParams.$add(new HeapBuf.Params());
   103     *  hmbParams.bufParams[0].blockSize = 64;
   104     *  hmbParams.bufParams[0].numBlocks = 10;
   105     *
   106     *  hmbParams.bufParams.$add(new HeapBuf.Params());
   107     *  hmbParams.bufParams[1].blockSize = 128;
   108     *  hmbParams.bufParams[1].numBlocks = 10;
   109     *
   110     *  hmbParams.bufParams.$add(new HeapBuf.Params());
   111     *  hmbParams.bufParams[2].blockSize = 256;
   112     *  hmbParams.bufParams[2].numBlocks = 10;
   113     *
   114     *
   115     *  // Create the HeapMultiBuf instance, and assign the global handle
   116     *  // 'multiBufHeap' to it. Add '#include <xdc/cfg/global.h>' to your
   117     *  // .c file to reference the instance by this handle.
   118     *  Program.global.multiBufHeap = HeapMultiBuf.create(hmbParams);
   119     *  @p
   120     *
   121     *  @p(html)
   122     *  <h4>Block Borrowing</h4>
   123     *  HeapMultiBuf can support "block borrowing". With this feature turned on,
   124     *  if a request is made for a 32-byte block and none are available,
   125     *  HeapMultiBuf will continue looking for an available block in other buffers.
   126     *  When a borrowed block is freed, it will be returned back to its original
   127     *  buffer. Enabling Block Borrowing changes the determinism of alloc, since it
   128     *  may have to check any number of buffers to find an available block.
   129     *
   130     *  Block borrowing may also occur, even if it is disabled, if a block of a
   131     *  particular size is requested with an alignment that is greater than the
   132     *  configured alignment for that block size. For example, a HeapMultiBuf is
   133     *  configured with a buffer of 32-byte blocks with an alignment of 8, and
   134     *  a buffer of 64-byte blocks with an alignment of 16. If a request is made
   135     *  for a 32-byte block with an alignment of 16, it will be serviced by the
   136     *  buffer of 64-byte blocks.
   137     *
   138     *  <h4>Static vs. Dynamic Creation</h4>
   139     *  As with HeapBuf, a statically created HeapMultiBuf instance will ignore the
   140     *  bufSize and buf parameters. Dynamic creates require all of the parameters.
   141     *
   142     *  It should be noted that static creates are ideal if code space is a
   143     *  concern; dynamically creating a HeapMultiBuf requires a relatively large
   144     *  amount of initialization code to be pulled in to the executable.
   145     *
   146     *  <h4>Block Sizes and Alignment</h4>
   147     *  @p(blist)
   148     *      - A buffer with a requested alignment of 0 will receive the target-
   149     *        specific minimum alignment.
   150     *      - The actual block sizes will be a multiple of the alignment. For
   151     *        example, if a buffer is configured to have 56-byte blocks with an
   152     *        alignment of 32, HeapMultiBuf will actually create 64-byte blocks.
   153     *        When providing the buffer for a dynamic create, make sure it is
   154     *        large enough to take this into account.
   155     *      - Multiple buffers with the same block size ARE allowed. This may
   156     *        occur, for example, if sizeof is used to specify the block sizes.
   157     *      - If any buffers have both the same block size and alignment, they
   158     *        will be merged. If this is a problem, consider managing these buffers
   159     *        directly with HeapBuf objects.
   160     *  @p
   161     *
   162     *  @p(html)
   163     *  <h4>Real-Time Concerns</h4>
   164     *  Allocation from and freeing to a HeapMultiBuf instance is non-blocking.
   165     *
   166     *  HeapMultiBuf is deterministic:
   167     *  @p(blist)
   168     *    - A call to alloc will always take the same amount of time for a given
   169     *      block size (with block borrowing disabled).
   170     *    - The worst case call to free is constant and proportional to the number
   171     *      of buffers managed.
   172     *  @p
   173     *
   174     *  @p(html)
   175     *  <h4>Restrictions</h4>
   176     *  @p(blist)
   177     *  - Align parameters must be a power of 2.
   178     *  - The buffers passed to dynamically create a HeapMultiBuf must be aligned
   179     *    according to the alignment parameter, and must be large enough to account
   180     *    for the actual block size after it has been rounded up to a multiple of
   181     *    the alignment.
   182     *  - Buffers must be provided to dynamically create a HeapMultiBuf, and cannot
   183     *    be provided to statically create a HeapMultiBuf.
   184     *  @p
   185     *
   186     *  @p(html)
   187     *  <h4>Unconstrained Functions</h4>
   188     *  All functions
   189     *
   190     *  @p(html)
   191     *  <h3> Calling Context </h3>
   192     *  <table border="1" cellpadding="3">
   193     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   194     *    </colgroup>
   195     *
   196     *    <tr><th> Function    </th><th>  Hwi   </th><th>  Swi   </th>
   197     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   198     *    <!--                                                         -->
   199     *    <tr><td> Params_init      </td><td>   Y    </td><td>   Y    </td>
   200     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   201     *    <tr><td> alloc            </td><td>   Y    </td><td>   Y    </td>
   202     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   203     *    <tr><td> construct        </td><td>   N*   </td><td>   N*   </td>
   204     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   205     *    <tr><td> create           </td><td>   N*   </td><td>   N*   </td>
   206     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   207     *    <tr><td> delete           </td><td>   N*   </td><td>   N*   </td>
   208     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   209     *    <tr><td> destruct         </td><td>   N*   </td><td>   N*   </td>
   210     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   211     *    <tr><td> free             </td><td>   Y    </td><td>   Y    </td>
   212     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   213     *    <tr><td> getStats         </td><td>   Y    </td><td>   Y    </td>
   214     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   215     *    <tr><td> isBlocking       </td><td>   Y    </td><td>   Y    </td>
   216     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   217     *    <tr><td colspan="6"> Definitions: <br />
   218     *       <ul>
   219     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   220     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   221     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   222     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   223     *           <ul>
   224     *             <li> In your module startup after this module is started
   225     *    (e.g. HeapMultiBuf_Module_startupDone() returns TRUE). </li>
   226     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   227     *             <li> During main().</li>
   228     *             <li> During BIOS.startupFxns.</li>
   229     *           </ul>
   230     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   231     *           <ul>
   232     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   233     *             <li> In your module startup before this module is started
   234     *    (e.g. HeapMultiBuf_Module_startupDone() returns FALSE).</li>
   235     *           </ul>
   236     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   237     *       <li> <b>**</b>: Assuming GateMutex is used as HeapMem's Gate. </li>
   238     *       <li> <b>+</b> : Cannot use HeapMem object while it is being
   239     *    restored. </li>
   240     *       </ul>
   241     *    </td></tr>
   242     *
   243     *  </table>
   244     *  @p
   245     */
   246
   247    @InstanceInitError     /* Instance_init may throw an error */
   248    @InstanceFinalize      /* to destruct HeapBufs */
   249    @ModuleStartup         /* to determine buffer addresses */
   250
   251    module HeapMultiBuf inherits xdc.runtime.IHeap {
   252
   253        /*!
   254         *  ======== BasicView ========
   255         *  @_nodoc
   256         */
   257        metaonly struct BasicView {
   258            String            label;
   259            Bool              blockBorrow;
   260            Int               numHeapBufs;
   261        }
   262
   263        /*!
   264         *  ======== DetailedView ========
   265         *  @_nodoc
   266         */
   267        metaonly struct DetailedView {
   268            String                  label;
   269            Bool              blockBorrow;
   270            Int               numHeapBufs;
   271            String       HeapBufHandles[];
   272        }
   273
   274
   275        /*! @_nodoc */
   276        @Facet
   277        metaonly config ViewInfo.Instance rovViewInfo =
   278            ViewInfo.create({
   279                viewMap: [
   280                [
   281                    'Basic',
   282                    {
   283                        type: ViewInfo.INSTANCE,
   284                        viewInitFxn: 'viewInitBasic',
   285                        structName: 'BasicView'
   286                    }
   287                ],
   288                [
   289                    'Detailed',
   290                    {
   291                        type: ViewInfo.INSTANCE,
   292                        viewInitFxn: 'viewInitDetailed',
   293                        structName: 'DetailedView'
   294                    }
   295                ],
   296                ]
   297            });
   298
   299        /*!
   300         *  ======== A_blockNotFreed ========
   301         *  Invalid block pointer
   302         *
   303         *  This Assert is raised if a call to free does not successfully
   304         *  free the block back to any of the buffers. Indicates that the
   305         *  block pointer is invalid, or that the HeapMultiBuf state has been
   306         *  corrupted.
   307         */
   308        config xdc.runtime.Assert.Id A_blockNotFreed =
   309            {msg: "Invalid block address on the free. Failed to free block back to heap."};
   310
   311        /*!
   312         *  ======== E_size ========
   313         *  Raised when requested size exceeds all blockSizes
   314         */
   315        config xdc.runtime.Error.Id E_size =
   316            {msg: "requested size is too big: handle=0x%x, size=%u"};
   317
   318    instance:
   319
   320        /*!
   321         *  ======== numBufs ========
   322         *  Number of memory buffers
   323         *
   324         *  The number of different fixed size memory buffers that are managed
   325         *  by the heap instance. The bufParams array has length numBufs.
   326         *
   327         *  The default number of buffers is 0.
   328         */
   329        config Int numBufs = 0;
   330
   331        /*!
   332         *  ======== blockBorrow ========
   333         *  Turn block borrowing on (true) or off (false)
   334         *
   335         *  With block borrowing on, if there are no blocks available of the
   336         *  requested size, then alloc will look for a larger block to return.
   337         *  Calls to alloc which borrow blocks will be slower, and will cause
   338         *  internal fragmentation of the heap (until the block is freed), so it
   339         *  is ideal to configure a HeapMultiBuf such that block borrowing is not
   340         *  needed.
   341         */
   342        config Bool blockBorrow = false;
   343
   344        /*!
   345         *  ======== bufParams ========
   346         *  Config parameters for each buffer
   347         *
   348         *  Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance.
   349         *  Configuration of a HeapMultiBuf is done by providing an array of
   350         *  configured HeapBuf parameter structures. Refer to the HeapBuf
   351         *  documentation for information on the buffer parameters. All of the
   352         *  documentation and parameters for HeapBuf apply to HeapMultiBuf.
   353         *  If a buffer is configured incorrectly, HeapBuf, not HeapMultiBuf,
   354         *  will raise an Assert.
   355         */
   356        config HeapBuf.Params bufParams[];
   357
   358        /*!
   359         *  ======== alloc ========
   360         *
   361         *  @HeapMultiBuf
   362         *  HeapMultiBuf will return a block that is >= 'size' with
   363         *  an alignment that is >= 'align'.
   364         *  The HeapMultiBuf will attempt to service a request for any size; the
   365         *  specified size does not need to match the configured block sizes of
   366         *  the buffers.
   367         */
   368        @DirectCall
   369        override Ptr alloc(SizeT size, SizeT align, xdc.runtime.Error.Block *eb);
   370
   371        /*!
   372         *  ======== free ========
   373         *
   374         *  @HeapMultiBuf
   375         *  HeapMultiBuf ignores the 'size' parameter to free. It
   376         *  determines the correct buffer to free the block to by comparing
   377         *  addresses.
   378         */
   379        @DirectCall
   380        override Void free(Ptr block, SizeT size);
   381
   382        /*!
   383         *  ======== isBlocking ========
   384         *
   385         *  @HeapMultiBuf
   386         *  This function always returns FALSE since the alloc/free
   387         *  never block on a resource.
   388         */
   389        @DirectCall
   390        override Bool isBlocking();
   391
   392    internal:   /* not for client use */
   393
   394        /*
   395         *  ======== AddrPair ========
   396         *  Used to sort bufs by address
   397         *
   398         *  A dynamically created HeapMultiBuf may have multiple AddrPairs
   399         *  per HeapBuf because of merging.
   400         */
   401        struct AddrPair {
   402            HeapBuf.Handle      heapBuf;  /* The heapBuf that manages lastAddr */
   403            Ptr                 lastAddr; /* The last address in the buffer */
   404        }
   405
   406        /*
   407         *  ======== addrPairCompare ========
   408         */
   409        Int addrPairCompare(const Void *a, const Void *b);
   410
   411        /*
   412         *  ======== sizeAlignCompare ========
   413         */
   414        Int sizeAlignCompare(const Void *a, const Void *b);
   415
   416        /*
   417         *  ======== moveToEnd ========
   418         */
   419        Void moveToEnd(HeapBuf.Handle *heapBufs, UInt numHeapBufs, UInt index);
   420
   421        /*
   422         *  ======== borrowBlock ========
   423         */
   424        Void *borrowBlock(HeapMultiBuf.Object *obj, SizeT size, SizeT align,
   425                          Int startIndex);
   426        /*
   427         *  ======== Instance_State ========
   428         * The bufsBySize array has length numHeapBufs and is used for alloc.
   429         * The bufsyByAddr array has length numBufs and is used for free.
   430         */
   431        struct Instance_State {
   432            Bool              blockBorrow;  /* Enable/Disable block borrowing */
   433            Int               numHeapBufs;  /* Number of HeapBuf instances    */
   434            HeapBuf.Handle    bufsBySize[]; /* HeapBufs, sorted by size       */
   435            Int               numBufs;      /* Number of memory buffers       */
   436            AddrPair          bufsByAddr[]; /* HeapBufs, sorted by address    */
   437        };
   438    }
   439    /*
   440     *  @(#) ti.sysbios.heaps; 2, 0, 0, 0,494; 6-15-2011 16:26:02; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   441
   442     */
   443


module ti.sysbios.heaps.HeapNull

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== HeapNull.xdc ========
    34     */
    35
    36    import xdc.runtime.Assert;
    37    import xdc.runtime.Error;
    38
    39    /*!
    40     *  ======== HeapNull ========
    41     *  Empty heap
    42     */
    43    module HeapNull inherits xdc.runtime.IHeap {
    44
    45    instance:
    46
    47        /*!
    48         *  ======== create ========
    49         *  Create a `HeapNull` heap
    50         */
    51        create();
    52    }
    53    /*
    54     *  @(#) ti.sysbios.heaps; 2, 0, 0, 0,494; 6-15-2011 16:26:03; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    55
    56     */
    57


package ti.sysbios.heaps

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.heaps ========
    41     *  Contains modules that inherit from IHeap.
    42     *
    43     *  A "Heap" is a module that implements the IHeap interface. Heaps are
    44     *  dynamic memory managers: they manage a specific piece of memory and
    45     *  support allocating and freeing pieces ("blocks") of that memory.
    46     *
    47     *  The {@link xdc.runtime.Memory} module is the common interface for all
    48     *  memory operations. Actual memory management is performed by a Heap
    49     *  instance, such as an instance of HeapMem or HeapBuf. For example,
    50     *  Memory_alloc() is used at runtime to dynamically allocate memory.
    51     *  All of the Memory APIs take a Heap instance as one of their parameters.
    52     *  Internally, the Memory module calls into the heap?s interface functions.
    53     *
    54     *  The xdc.runtime.Memory module is documented in the XDCtools online help.
    55     *  Implementations of Heaps provided by SYS/BIOS are discussed here.
    56     *
    57     *  Memory allocation sizes are measured in "Minimum Addressable Units"
    58     *  (MAUs) of memory. An MAU is the smallest unit of data storage that can
    59     *  be read or written by the CPU. For the C5000, this is a 16-bit word.
    60     *  For the C28x, this is an 16-bit word. For the all other currently
    61     *  supported target families?including C6000, ARM, and MSP430?this is an
    62     *  8-bit byte.
    63     *
    64     */
    65    package ti.sysbios.heaps [2,0,0,0] {
    66        module HeapBuf;
    67        module HeapMem;
    68        module HeapMultiBuf;
    69        module HeapNull;
    70    }
    71    /*
    72     *  @(#) ti.sysbios.heaps; 2, 0, 0, 0,494; 6-15-2011 16:26:03; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    73
    74     */
    75


interface ti.sysbios.interfaces.ICache

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== ICache.xdc ========
    34     *
    35     *
    36     */
    37
    38    /*!
    39     *  ======== ICache ========
    40     *  Cache Interface
    41     */
    42
    43    interface ICache
    44    {
    45        /*! Lists of bitmask cache types */
    46        enum Type {
    47            Type_L1P = 0x1,         /*! Level 1 Program cache */
    48            Type_L1D = 0x2,         /*! Level 1 Data cache */
    49            Type_L1  = 0x3,         /*! Level 1 caches */
    50            Type_L2P = 0x4,         /*! Level 2 Program cache */
    51            Type_L2D = 0x8,         /*! Level 2 Data cache */
    52            Type_L2  = 0xC,         /*! Level 2 caches */
    53            Type_ALLP = 0x5,        /*! All Program caches */
    54            Type_ALLD = 0xA,        /*! All Data caches */
    55            Type_ALL = 0x7fff       /*! All caches */
    56        };
    57
    58        /*!
    59         *  ======== enable ========
    60         *  Enables all cache(s)
    61         *
    62         *  @param(type)    bit mask of Cache type
    63         */
    64        @DirectCall
    65        Void enable(Bits16 type);
    66
    67        /*!
    68         *  ======== disable ========
    69         *  Disables the 'type' cache(s)
    70         *
    71         *  @param(type)    bit mask of Cache type
    72         */
    73        @DirectCall
    74        Void disable(Bits16 type);
    75
    76        /*!
    77         *  ======== inv ========
    78         *  Invalidate the range of memory within the specified starting
    79         *  address and byte count.  The range of addresses operated on
    80         *  gets quantized to whole cache lines in each cache.  All lines
    81         *  in range are invalidated for all the 'type' caches.
    82         *
    83         *  @param(blockPtr) start address of range to be invalidated
    84         *  @param(byteCnt)  number of bytes to be invalidated
    85         *  @param(type)     bit mask of Cache type
    86         *  @param(wait)     wait until the operation is completed
    87         */
    88        @DirectCall
    89        Void inv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
    90
    91        /*!
    92         *  ======== wb ========
    93         *  Writes back a range of memory from all cache(s)
    94         *
    95         *  Writes back the range of memory within the specified starting
    96         *  address and byte count.  The range of addresses operated on
    97         *  gets quantized to whole cache lines in each cache.  All lines
    98         *  within the range are left valid in the 'type' caches and the data
    99         *  within the range will be written back to the source memory.
   100         *
   101         *  @param(blockPtr) start address of range to be invalidated
   102         *  @param(byteCnt)  number of bytes to be invalidated
   103         *  @param(type)     bit mask of Cache type
   104         *  @param(wait)     wait until the operation is completed
   105         */
   106        @DirectCall
   107        Void wb(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   108
   109        /*!
   110         *  ======== wbInv ========
   111         *  Writes back and invalidates the range of memory within the
   112         *  specified starting address and byte count.  The range of
   113         *  addresses operated on gets quantized to whole cache lines in
   114         *  each cache.  All lines within the range are written back to the
   115         *  source memory and then invalidated for all 'type' caches.
   116         *
   117         *  @param(blockPtr) start address of range to be invalidated
   118         *  @param(byteCnt)  number of bytes to be invalidated
   119         *  @param(type)     bit mask of Cache type
   120         *  @param(wait)     wait until the operation is completed
   121         */
   122        @DirectCall
   123        Void wbInv(Ptr blockPtr, SizeT byteCnt, Bits16 type, Bool wait);
   124
   125        /*!
   126         *  ======== wbAll ========
   127         *  Write back all caches
   128         *
   129         *  Perform a global write back.  There is no effect on program cache.
   130         *  All data cache lines are left valid.
   131         */
   132        @DirectCall
   133        Void wbAll();
   134
   135        /*!
   136         *  ======== wbInvAll ========
   137         *  Write back invalidate all caches
   138         *
   139         *  Performs a global write back and invalidate.  All cache lines
   140         *  are written out to physical memory and then invalidated.
   141         */
   142        @DirectCall
   143        Void wbInvAll();
   144
   145        /*!
   146         *  ======== wait ========
   147         *  Wait for a previous cache operation to complete
   148         *
   149         *  Wait for the cache wb/wbInv/inv operation to complete.  A cache
   150         *  operation is not truly complete until it has worked its way
   151         *  through all buffering and all memory writes have landed in the
   152         *  source memory.
   153         */
   154        @DirectCall
   155        Void wait();
   156
   157    }
   158
   159    /*
   160     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   161
   162     */
   163


interface ti.sysbios.interfaces.IHwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== IHwi.xdc ========
    34     *
    35     */
    36
    37    import xdc.runtime.Error;
    38
    39
    40    /*!
    41     *  ======== Hwi ========
    42     *  Hardware Interrupt Support Module.
    43     *
    44     *  The IHwi interface specifies APIs for globally enabling, disabling, and
    45     *  restoring interrupts.
    46     *
    47     *  Additionally, management of individual, device-specific hardware
    48     *  interrupts is provided.
    49     *
    50     *  The user can statically or dynamically assign routines that run when
    51     *  specific hardware interrupts occur.
    52     *
    53     *  Dynamic assignment of Hwi routines to interrupts at run-time is done
    54     *  using the Hwi_create function.
    55     *
    56     *  Interrupt routines can be written completely in C, completely in
    57     *  assembly, or in a mix of C and assembly. In order to support interrupt
    58     *  routines
    59     *  written completely in C, an interrupt dispatcher is provided that performs
    60     *  the requisite prolog and epilog for an interrupt routine.
    61     *
    62     *  Some routines are assigned to interrupts by the other SYS/BIOS
    63     *  modules. For example, the Clock module configures its own timer interrupt
    64     *  handler. See the Clock Module for more details.
    65     *
    66     *  @a(Runtime Hwi Creation)
    67     *
    68     *  Below is an example of configuring an interrupt at runtime.
    69     *  Usually this code would be placed in main().
    70     *
    71     *  @p(code)
    72     *  #include <xdc/runtime/Error.h>
    73     *  #include <ti/sysbios/hal/Hwi.h>
    74     *
    75     *  Hwi_Handle myHwi;
    76     *
    77     *  Int main(Int argc, char* argv[])
    78     *  {
    79     *      Hwi_Params hwiParams;
    80     *      Error_Block eb;
    81     *
    82     *      Hwi_Params_init(&hwiParams);
    83     *      Error_init(&eb);
    84     *
    85     *      // set the argument you want passed to your ISR function
    86     *      hwiParams.arg = 1;
    87     *
    88     *      // set the event id of the peripheral assigned to this interrupt
    89     *      hwiParams.eventId = 10;
    90     *
    91     *      // don't allow this interrupt to nest itself
    92     *      hwiParams.maskSetting = Hwi_MaskingOption_SELF;
    93     *
    94     *      //
    95     *      // Configure interrupt 5 to invoke "myIsr".
    96     *      // Automatically enables interrupt 5 by default
    97     *      // set params.enableInt = FALSE if you want to control
    98     *      // when the interrupt is enabled using Hwi_enableInterrupt()
    99     *      //
   100     *
   101     *      myHwi = Hwi_create(5, myIsr, &hwiParams, &eb);
   102     *
   103     *      if (Error_check(&eb)) {
   104     *          // handle the error
   105     *      }
   106     *  }
   107     *
   108     *  Void myIsr(UArg arg)
   109     *  {
   110     *      // here when interrupt #5 goes off
   111     *  }
   112     *  @p
   113     *
   114     *  @a(Hook Functions)
   115     *
   116     *  Sets of hook functions can be specified for the Hwi module
   117     *  using the configuration tool.  Each set contains these hook
   118     *  functions:
   119     *  @p(blist)
   120     *  -Register:  A function called before any statically-created Hwis
   121     *      are initialized at runtime.  The register hook is called at boot time
   122     *      before main() and before interrupts are enabled.
   123     *  -Create:    A function that is called when a Hwi is created.
   124     *      This includes hwis that are created statically and those
   125     *      created dynamically using {@link #create Hwi_create}.
   126     *  -Begin:     A function that is called just prior to running a Hwi.
   127     *  -End:       A function that is called just after a Hwi finishes.
   128     *  -Delete:    A function that is called when a Hwi is deleted at
   129     *      run-time with {@link #delete Hwi_delete}.
   130     *  @p
   131     *
   132     *  Register Function
   133     *
   134     *  The Register function is provided to allow a hook set to store its
   135     *  hookset ID.  This id can be passed to
   136     *  {@link #setHookContext Hwi_setHookContext} and
   137     *  {@link #getHookContext Hwi_getHookContext} to set or get
   138     *  hookset-specific context.  The
   139     *  Register function must be specified if the hook implementation
   140     *  needs to use {@link #setHookContext  Hwi_setHookContext} or
   141     *  {@link #getHookContext  Hwi_getHookContext}.
   142     *  The registerFxn hook function is called during system initialization
   143     *  before interrupts have been enabled.
   144     *
   145     *  @p(code)
   146     *  Void myRegisterFxn(Int id);
   147     *  @p
   148     *
   149     *  Create and Delete Functions
   150     *
   151     *  The create and delete functions are called whenever a Hwi is created
   152     *  or deleted.  They are called with interrupts enabled (unless called
   153     *  at boot time or from main()).
   154     *
   155     *  @p(code)
   156     *  Void myCreateFxn(Hwi_Handle hwi, Error_Block *eb);
   157     *  @p
   158     *
   159     *  @p(code)
   160     *  Void myDeleteFxn(Hwi_Handle hwi);
   161     *  @p
   162     *
   163     *  Begin and End Functions
   164     *
   165     *  The beginFxn and endFxn function hooks are called with interrupts
   166     *  globally disabled, therefore any hook processing function will contribute
   167     *  to the overall system interrupt response latency.  In order to minimize
   168     *  this impact, carefully consider the processing time spent in an Hwi
   169     *  beginFxn or endFxn function hook.
   170     *
   171     *  @p(code)
   172     *  Void myBeginFxn(Hwi_Handle hwi);
   173     *  @p
   174     *
   175     *  @p(code)
   176     *  Void myEndFxn(Hwi_Handle hwi);
   177     *  @p
   178     *
   179     *  Hook functions can only be configured statically.
   180     */
   181
   182    @InstanceFinalize
   183    @InstanceInitError
   184
   185    interface IHwi {
   186
   187        // -------- Module Types --------
   188
   189        /*! Hwi create function type definition. */
   190        typedef Void (*FuncPtr)(UArg);
   191
   192        /*!
   193         * Interrupt Return Pointer.
   194         *
   195         * This is the address of the interrupted instruction.
   196         */
   197        typedef UArg Irp;
   198
   199        /*!
   200         *  Hwi hook set type definition.
   201         *
   202         *  The functions that make up a hookSet have certain restrictions. They
   203         *  cannot call any Hwi instance functions other than Hwi_getHookContext()
   204         *  and Hwi_setHookContext(). For all practical purposes, they should treat
   205         *  the Hwi_Handle passed to these functions as an opaque handle.
   206         */
   207        struct HookSet {
   208            Void (*registerFxn)(Int);
   209            Void (*createFxn)(Handle, Error.Block *);
   210            Void (*beginFxn)(Handle);
   211            Void (*endFxn)(Handle);
   212            Void (*deleteFxn)(Handle);
   213        };
   214
   215        /*!
   216         *  ======== MaskingOption ========
   217         *  Shorthand interrupt masking options
   218         *
   219         *  @value(MaskingOption_NONE)      No interrupts are disabled
   220         *
   221         *  @value(MaskingOption_ALL)       All interrupts are disabled
   222         *
   223         *  @value(MaskingOption_SELF)      Only this interrupt is disabled
   224         *
   225         *  @value(MaskingOption_BITMASK)   User supplies interrupt enable masks
   226         *
   227         *  @value(MaskingOption_LOWER)     All current and lower priority
   228         *                                  interrupts are disabled.
   229         *
   230         *                                  Only a few targets/devices truly
   231         *                                  support this masking option. For those
   232         *                                  that don't, this setting is treated
   233         *                                  the same as MaskingOption_SELF.
   234         */
   235        enum MaskingOption {
   236            MaskingOption_NONE,
   237            MaskingOption_ALL,
   238            MaskingOption_SELF,
   239            MaskingOption_BITMASK,
   240            MaskingOption_LOWER
   241        };
   242
   243        /*!
   244         *  @_nodoc
   245         *  returned by viewGetStackInfo()
   246         */
   247        metaonly struct StackInfo {
   248            SizeT hwiStackPeak;
   249            SizeT hwiStackSize;
   250            Ptr hwiStackBase;
   251        };
   252
   253        // -------- Module Parameters --------
   254
   255        /*!
   256         *  Include interrupt nesting logic in interrupt dispatcher?
   257         *
   258         *  Default is true.
   259         *
   260         *  This option provides the user with the ability to optimize
   261         *  interrupt dispatcher performance when support for interrupt
   262         *  nesting is not required.
   263         *
   264         *  Setting this parameter to false will disable the logic in
   265         *  the interrupt dispatcher that manipulates interrupt mask
   266         *  registers and enables and disables interrupts before and
   267         *  after invoking the user's Hwi function.
   268         *
   269         *  Set this parameter to false if you don't need interrupts
   270         *  enabled during the execution of your Hwi functions.
   271         */
   272        config Bool dispatcherAutoNestingSupport = true;
   273
   274        /*!
   275         *  Include Swi scheduling logic in interrupt dispatcher?
   276         *
   277         *  Default is inherited from {@link ti.sysbios.BIOS#swiEnabled
   278         *  BIOS.swiEnabled}, which is true by default.
   279         *
   280         *  This option provides the user with the ability to optimize
   281         *  interrupt dispatcher performance when it is known that Swis
   282         *  will not be posted from any of their Hwi threads.
   283         *
   284         *  Setting this parameter to false will disable the logic in
   285         *  the interrupt dispatcher that invokes the Swi scheduler
   286         *  prior to returning from an interrupt.
   287         */
   288        config Bool dispatcherSwiSupport;
   289
   290        /*!
   291         *  Include Task scheduling logic in interrupt dispatcher?
   292         *
   293         *  Default is inherited from {@link ti.sysbios.BIOS#taskEnabled
   294         *  BIOS.taskEnabled}, which is true by default.
   295         *
   296         *  This option provides the user with the ability to optimize
   297         *  interrupt dispatcher performance when it is known that no
   298         *  Task scheduling APIs (ie {@link ti.sysbios.knl.Semaphore#post
   299         *  Semaphore_post()}) will be executed from any of their Hwi threads.
   300         *
   301         *  Setting this parameter to false will disable the logic in
   302         *  the interrupt dispatcher that invokes the Task scheduler
   303         *  prior to returning from an interrupt.
   304         */
   305        config Bool dispatcherTaskSupport;
   306
   307        /*!
   308         *  Controls whether the
   309         *  dispatcher retains the interrupted thread's return address.
   310         *
   311         *  This option is enabled by default.
   312         *
   313         *  Setting this parameter to false will disable the logic in
   314         *  the interrupt dispatcher that keeps track of the interrupt's
   315         *  return address and provide a small savings in interrupt latency.
   316         *
   317         *  The application can get an interrupt's most recent return
   318         *  address using the {@link #getIrp} API.
   319         */
   320        config Bool dispatcherIrpTrackingSupport = true;
   321
   322        // -------- Module Functions --------
   323
   324        /*!
   325         *  ======== addHookSet ========
   326         *  addHookSet is used in a config file to add a hook set (defined
   327         *  by struct HookSet).
   328         *
   329         *  HookSet structure elements may be omitted, in which case those
   330         *  elements will not exist.
   331         *
   332         *  @param(hook)    structure of type HookSet
   333         */
   334        metaonly Void addHookSet(HookSet hook);
   335
   336        /*!
   337         *  ======== viewGetStackInfo ========
   338         *  @_nodoc
   339         *  Returns the Hwi stack usage info. Used at ROV time.
   340         *
   341         *  @b(returns)     Hwi stack base, size, peak
   342         */
   343        metaonly StackInfo viewGetStackInfo();
   344
   345        /*!
   346         *  ======== startup ========
   347         *  Initially enable interrupts
   348         *
   349         *  Called within BIOS_start
   350         */
   351        @DirectCall
   352        Void startup();
   353
   354        /*!
   355         *  ======== disable ========
   356         *  Globally disable interrupts.
   357         *
   358         *  Hwi_disable globally disables hardware interrupts and returns an
   359         *  opaque key indicating whether interrupts were globally enabled or
   360         *  disabled on entry to Hwi_disable().
   361         *  The actual value of the key is target/device specific and is meant
   362         *  to be passed to Hwi_restore().
   363         *
   364         *  Call Hwi_disable before a portion of a function that needs
   365         *  to run without interruption. When critical processing is complete, call
   366         *  Hwi_restore or Hwi_enable to reenable hardware interrupts.
   367         *
   368         *  Servicing of interrupts that occur while interrupts are disabled is
   369         *  postponed until interrupts are reenabled. However, if the same type
   370         *  of interrupt occurs several times while interrupts are disabled,
   371         *  the interrupt's function is executed only once when interrupts are
   372         *  reenabled.
   373         *
   374         *  A context switch can occur when calling Hwi_enable or Hwi_restore if
   375         *  an enabled interrupt occurred while interrupts are disabled.
   376         *
   377         *  Hwi_disable may be called from main(). However, since Hwi interrupts
   378         *  are already disabled in main(), such a call has no effect.
   379         *
   380         *  @a(constraints)
   381         *  If a Task switching API such as
   382         *  {@link ti.sysbios.knl.Semaphore#pend Semaphore_pend()},
   383         *  {@link ti.sysbios.knl.Semaphore#post Semaphore_post()},
   384         *  {@link ti.sysbios.knl.Task#sleep Task_sleep()}, or
   385         *  {@link ti.sysbios.knl.Task#yield Task_yield()}
   386         *  is invoked which results in a context switch while
   387         *  interrupts are disabled, an embedded call to
   388         *  {@link #enable Hwi_enable} occurs
   389         *  on the way to the new thread context which unconditionally re-enables
   390         *  interrupts. Interrupts will remain enabled until a subsequent
   391         *  {@link #disable Hwi_disable}
   392         *  invocation.
   393         *
   394         *  Swis always run with interrupts enabled.
   395         *  See {@link ti.sysbios.knl.Swi#post Swi_post()} for a discussion Swis and
   396         *  interrupts.
   397         *
   398         *  @b(returns)     opaque key for use by Hwi_restore()
   399         */
   400        UInt disable();
   401
   402        /*!
   403         *  ======== enable ========
   404         *  Globally enable interrupts.
   405         *
   406         *  Hwi_enable globally enables hardware interrupts and returns an
   407         *  opaque key indicating whether interrupts were globally enabled or
   408         *  disabled on entry to Hwi_enable().
   409         *  The actual value of the key is target/device specific and is meant
   410         *  to be passed to Hwi_restore().
   411         *
   412         *
   413         *  This function is
   414         *  called as part of SYS/BIOS Startup_POST_APP_MAIN phase.
   415         *
   416         *  Hardware interrupts are enabled unless a call to Hwi_disable disables
   417         *  them.
   418         *
   419         *  Servicing of interrupts that occur while interrupts are disabled is
   420         *  postponed until interrupts are reenabled. However, if the same type
   421         *  of interrupt occurs several times while interrupts are disabled,
   422         *  the interrupt's function is executed only once when interrupts are
   423         *  reenabled.
   424         *
   425         *  A context switch can occur when calling Hwi_enable or Hwi_restore if
   426         *  an enabled interrupt occurred while interrupts are disabled.
   427         *
   428         *  Any call to Hwi_enable enables interrupts, even if Hwi_disable has
   429         *  been called several times.
   430         *
   431         *  Hwi_enable must not be called from main().
   432         *
   433         *  @b(returns)     opaque key for use by Hwi_restore()
   434         */
   435        UInt enable();
   436
   437        /*!
   438         *  ======== restore ========
   439         *  Globally restore interrupts.
   440         *
   441         *  Hwi_restore globally restores interrupts to the state determined
   442         *  by the key argument provided by a previous invocation of Hwi_disable.
   443         *
   444         *  A context switch may occur when calling Hwi_restore if Hwi_restore
   445         *  reenables interrupts and another Hwi occurred while interrupts were
   446         *  disabled.
   447         *
   448         *  Hwi_restore may be called from main(). However, since Hwi_enable
   449         *  cannot be called from main(), interrupts are always disabled in
   450         *  main(), and a call to Hwi_restore has no effect.
   451         *
   452         *  @param(key)     enable/disable state to restore
   453         */
   454        Void restore(UInt key);
   455
   456        /*!
   457         *  @_nodoc
   458         *  ======== switchFromBootStack ========
   459         *  Indicate that we are leaving the boot stack and
   460         *  are about to switch to a task stack.
   461         *  Used by Task_startup()
   462         */
   463        @DirectCall
   464        Void switchFromBootStack();
   465
   466        /*!
   467         *  @_nodoc
   468         *  ======== post ========
   469         *  Generate an interrupt for test purposes.
   470         *
   471         *  @param(intNum)      ID of interrupt to generate
   472         */
   473        @DirectCall
   474        Void post(UInt intNum);
   475
   476        /*!
   477         *  @_nodoc
   478         *  ======== getTaskSP ========
   479         *  retrieve interrupted task's SP
   480         *
   481         *  Used for benchmarking the SYS/BIOS Hwi dispatcher's task
   482         *  stack utilization.
   483         *
   484         *  @b(returns)     interrupted task's SP
   485         */
   486        @DirectCall
   487        Char *getTaskSP();
   488
   489        /*
   490         *  @_nodoc
   491         *  The following two target-unique Hwi APIs must be called
   492         *  directly in order to work properly. Thus they are not
   493         *  published here in order to bypass the multi-layered indirect function
   494         *  calls (__E, __F) that would arise if they appeared in this spec file.
   495         *
   496         *  These APIs must be implemented by the target Hwi modules and must be
   497         *  given these EXACT names.
   498         *
   499         *  The two functions, switchToIsrStack() and switchToTaskStack() must
   500         *  work in tandem to insure that only the first order (ie non nested)
   501         *  invocation of these APIs result in the switch to the ISR stack and
   502         *  the switch back to the task stack. The opaque char * token returned
   503         *  by switchToIsrStack() and passed to switchToTaskStack() is provided
   504         *  purely for implementation efficiency and thus can have implementation
   505         *  dependent definitions.
   506         */
   507
   508        /*
   509         *  @_nodoc
   510         *  ======== switchToIsrStack ========
   511         *  If not on ISR stack already, switch to it.
   512         *  Used by the Swi scheduler and interrupt dispatcher.
   513         *
   514         *  This function must be implemented by all Hwi modules
   515         *  name) because it can't be _E and _F'd due to its
   516         *  inherent stack switching behavior.
   517         *
   518         *  @b(returns)     token to use with
   519         *                  switchToTaskStack()
   520         */
   521        /*  Char *ti_bios_family_xxx_Hwi_switchToIsrStack(); */
   522
   523        /*
   524         *  @_nodoc
   525         *  ======== switchToTaskStack ========
   526         *  If at bottom of ISR stack, switch to Task stack.
   527         *  Used by the Swi scheduler and interrupt dispatcher.
   528         *
   529         *  This function must be implemented by all Hwi modules
   530         *  and be given this exact name (without a target-specific
   531         *  name) because it can't be _E and _F'd due to its
   532         *  inherent stack switching behavior.
   533         *
   534         *  @param(key)     token returned by
   535         *                  switchToIsrStack()
   536         */
   537        /*  Void ti_bios_family_xxx_Hwi_switchToTaskStack(Char *key); */
   538
   539        /*!
   540         *  ======== disableInterrupt ========
   541         *  Disable a specific interrupt.
   542         *
   543         *  Disable a specific interrupt identified by an interrupt number.
   544         *
   545         *  @param(intNum)  interrupt number to disable
   546         *  @b(returns)     key to restore previous enable/disable state
   547         */
   548        @DirectCall
   549        UInt disableInterrupt(UInt intNum);
   550
   551        /*!
   552         *  ======== enableInterrupt ========
   553         *  Enable a specific interrupt.
   554         *
   555         *  Enables a specific interrupt identified by an interrupt number.
   556         *
   557         *  @param(intNum)  interrupt number to enable
   558         *  @b(returns)     key to restore previous enable/disable state
   559         */
   560        @DirectCall
   561        UInt enableInterrupt(UInt intNum);
   562
   563        /*!
   564         *  ======== restoreInterrupt ========
   565         *  Restore a specific interrupt's enabled/disabled state.
   566         *
   567         *  Restores a specific interrupt identified by an interrupt number.
   568         *  restoreInterrupt is generally used to restore an interrupt to its state
   569         *  before {@link #disableInterrupt} or {@link #enableInterrupt} was
   570         *  invoked
   571         *
   572         *  @param(intNum)  interrupt number to restore
   573         *  @param(key)     key returned from enableInt or disableInt
   574         */
   575        @DirectCall
   576        Void restoreInterrupt(UInt intNum, UInt key);
   577
   578        /*!
   579         *  ======== clearInterrupt ========
   580         *  Clear a specific interrupt.
   581         *
   582         *  Clears a specific interrupt's pending status.
   583         *  The implementation is family-specific.
   584         *
   585         *  @param(intNum)  interrupt number to clear
   586         */
   587        @DirectCall
   588        Void clearInterrupt(UInt intNum);
   589
   590    instance:
   591
   592        /*!
   593         *  Create a dispatched interrupt.
   594         *
   595         *  A Hwi dispatcher table entry is created and filled with the
   596         *  function specified by the fxn parameter and the attributes
   597         *  specified by the params parameter.
   598         *
   599         *  If params is NULL, the Hwi's dispatcher properties are assigned a
   600         *  default set of values. Otherwise, the following properties
   601         *  are specified by a structure of type Hwi_Params.
   602         *
   603         *  @p(blist)
   604         *  - The arg element is a generic argument that is passed to the plugged
   605         *  function as its only parameter. The default value is 0.
   606         *  - The enableInt element determines whether the interrupt should be
   607         *  enabled in the IER by create.
   608         *  - The maskSetting element defines the dispatcherAutoNestingSupport
   609         *  behavior of the interrupt.
   610         *  @p
   611         *
   612         *  Hwi_create returns a pointer to the created Hwi object.
   613         *
   614         *  @param(intNum)  interrupt number
   615         *  @param(hwiFxn)  pointer to ISR function
   616         *
   617         */
   618        @DirectCall
   619        create(Int intNum, FuncPtr hwiFxn);
   620
   621        /*! maskSetting. Default is {@link #MaskingOption Hwi_MaskingOption_SELF} */
   622        config MaskingOption maskSetting = MaskingOption_SELF;
   623
   624        /*! ISR function argument. Default is 0. */
   625        config UArg arg = 0;
   626
   627        /*! Enable this interrupt now? Default is true. */
   628        config Bool enableInt = true;
   629
   630        /*!
   631         *  Interrupt event ID (Interrupt Selection Number)
   632         *
   633         *  Default is -1.
   634         *  Not all targets/devices support this instance parameter.
   635         *  On those that don't, this parameter is ignored.
   636         */
   637        config Int eventId = -1;
   638
   639        /*!
   640         *  Interrupt priority.
   641         *
   642         *  Default is -1.
   643         *  Not all targets/devices support this instance parameter.
   644         *  On those that don't, this parameter is ignored.
   645         */
   646        config Int priority = -1;
   647
   648        /*!
   649         *  ======== getFunc ========
   650         *  Get Hwi function and arg
   651         *
   652         *  @param(arg)     pointer for returning hwi's ISR function argument
   653         *  @b(returns)     hwi's ISR function
   654         */
   655        @DirectCall
   656        FuncPtr getFunc(UArg *arg);
   657
   658        /*!
   659         *  ======== setFunc ========
   660         *  Overwrite Hwi function and arg
   661         *
   662         *  Replaces a Hwi object's hwiFxn function originally
   663         *  provided in {@link #create}.
   664         *
   665         *  @param(fxn)     pointer to ISR function
   666         *  @param(arg)     argument to ISR function
   667         */
   668        @DirectCall
   669        Void setFunc(FuncPtr fxn, UArg arg);
   670
   671        /*!
   672         *  ======== getHookContext ========
   673         *  Get hook instance's context for a Hwi.
   674         *
   675         *  @b(returns)     hook instance's context for hwi
   676         */
   677        @DirectCall
   678        Ptr getHookContext(Int id);
   679
   680        /*!
   681         *  ======== setHookContext ========
   682         *  Set hook instance's context for a Hwi.
   683         *
   684         *  @param(id)            hook instance's ID
   685         *  @param(hookContext)   value to write to context
   686         */
   687        @DirectCall
   688        Void setHookContext(Int id, Ptr hookContext);
   689
   690        /*!
   691         *  ======== getIrp ========
   692         *  Get address of interrupted instruction.
   693         *
   694         *  @b(returns)     most current IRP of a Hwi
   695         */
   696        @DirectCall
   697        Irp getIrp();
   698    }
   699    /*
   700     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   701
   702     */
   703


interface ti.sysbios.interfaces.ISettings

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== ISettings.xdc ========
    34     *
    35     */
    36    package ti.sysbios.interfaces;
    37
    38    /*!
    39     *  ======== ISettings ========
    40     *  Interface for family-specific Settings modules.
    41     *
    42     *  Every new device family must implement this interface.
    43     */
    44    metaonly interface ISettings
    45    {
    46        /*! returns the family-specific Hwi module delegate */
    47        String getDefaultHwiDelegate();
    48
    49        /*! returns the family-specific Timer module delegate */
    50        String getDefaultTimerDelegate();
    51
    52        /*! returns the family-specific Timer Support module delegate */
    53        String getDefaultTimerSupportDelegate();
    54
    55        /*! returns the family-specific Timestamp module delegate */
    56        String getDefaultTimestampDelegate();
    57
    58        /*! returns the family-specific TaskSupport module delegate */
    59        String getDefaultTaskSupportDelegate();
    60
    61        /*! returns the family-specific IntrinsicsSupport module delegate */
    62        String getDefaultIntrinsicsSupportDelegate();
    63
    64        /*! returns the family-specific CacheSupport module delegate */
    65        String getDefaultCacheDelegate();
    66
    67        /*! returns the family-specific Boot module. */
    68        String getDefaultBootModule();
    69
    70        /*! Returns the path to the family-specific Grace page. */
    71        String getFamilySettingsXml();
    72
    73        /*! returns the family-specific Clock tickPeriod */
    74        UInt32 getDefaultClockTickPeriod();
    75    }
    76
    77
    78    /*
    79     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    80
    81     */
    82


interface ti.sysbios.interfaces.ITimer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== ITimer.xdc ========
    34     *
    35     *
    36     */
    37
    38    /*
    39     * See SequenceInTimerAPIs.txt for details on how to implement
    40     * this interface
    41     */
    42
    43    /*!
    44     *  ======== ITimer ========
    45     *  Interface for Timer Peripherals Manager.
    46     */
    47
    48    interface ITimer
    49    {
    50        /*! Timer tick function prototype */
    51        typedef Void (*FuncPtr)(UArg);
    52
    53        /*! Const used to specify any timer */
    54        const UInt ANY = ~0;
    55
    56        /*!
    57         *  Timer Start Modes
    58         *
    59         *  @c(StartMode_AUTO)
    60         *  Statically created/constructed Timers will be started in BIOS_start().
    61         *  Dynamically created Timers will start at create() time. This includes
    62         *  timers created before BIOS_start().
    63         *
    64         *  @c(StartMode_USER)
    65         *  Timer will be started by the user using start().
    66         */
    67        enum StartMode {
    68            StartMode_AUTO,         /*! timer starts automatically */
    69            StartMode_USER          /*! timer will be started by user */
    70        };
    71
    72        /*!
    73         *  Timer Run Modes
    74         *
    75         *  @c(RunMode_CONTINUOUS)
    76         *  Timer is periodic and runs continuously.
    77         *
    78         *  @c(RunMode_ONESHOT)
    79         *  Timer runs for a single period value and stops.
    80         *
    81         *  @c(RunMode_DYNAMIC)
    82         *  Timer is dynamically reprogrammed for the next required tick.
    83         *
    84         */
    85        enum RunMode {
    86            RunMode_CONTINUOUS,     /*! periodic and continuous */
    87            RunMode_ONESHOT,        /*! one-shot */
    88            RunMode_DYNAMIC         /*! dynamically reprogrammed */
    89        };
    90
    91        /*!
    92         *  Timer Status
    93         *
    94         *  @c(Status_INUSE)
    95         *  Timer is in use. A timer is marked in use from the time it gets
    96         *  created to the time it gets deleted.
    97         *
    98         *  @c(Status_FREE)
    99         *  Timer is free and can be acquired using create.
   100         */
   101        enum Status {
   102            Status_INUSE,           /*! timer in use */
   103            Status_FREE             /*! timer is free */
   104        };
   105
   106        /*!
   107         *  ======== PeriodType ========
   108         *  Timer period units
   109         *
   110         *  @c(PeriodType_MICROSECS)
   111         *  Period value is in microseconds.
   112         *
   113         *  @c(PeriodType_COUNTS)
   114         *  Period value is in counts.
   115         */
   116        enum PeriodType {
   117            PeriodType_MICROSECS,   /*! period in microsecs */
   118            PeriodType_COUNTS       /*! period in counts */
   119        };
   120
   121        /*!
   122         *  @_nodoc
   123         *  Timer supports RunMode_DYNAMIC?
   124         *
   125         *  Default is false.  Can be overriden by Timer drivers that indeed
   126         *  support RunMode_DYNAMIC.
   127         */
   128        metaonly config Bool supportsDynamic = false;
   129
   130        /*!
   131         *  @_nodoc
   132         *  Default to RunMode_DYNAMIC?
   133         *
   134         *  Default is false.  Can be overriden by Timer drivers that support
   135         *  RunMode_DYNAMIC, who want DYNAMIC mode to be used by default.
   136         */
   137        metaonly config Bool defaultDynamic = false;
   138
   139        /*!
   140         *  ======== getNumTimers ========
   141         *  Returns number of timer peripherals on the platform.
   142         *
   143         *  @b(returns)     Number of timer peripherals.
   144         */
   145        @DirectCall
   146        UInt getNumTimers();
   147
   148        /*!
   149         *  ======== getStatus ========
   150         *  Returns timer status (free or in use).
   151         *
   152         *  @b(returns)     timer status
   153         */
   154        @DirectCall
   155        Status getStatus(UInt id);
   156
   157        /*!
   158         *  ======== startup ========
   159         *  @_nodoc
   160         *  Startup function to be called during BIOS_start
   161         *
   162         *  This function starts statically created timers with
   163         *  startMode = StartMode_AUTO.
   164         */
   165        @DirectCall
   166        Void startup();
   167
   168    instance:
   169
   170        /*!
   171         *  ======== create ========
   172         *  Create a timer.
   173         *
   174         *  Create could fail if timer peripheral is unavailable. To
   175         *  request any available timer use {@link #ANY} as the id.
   176         *  TimerId's are logical ids. The family-specific implementations
   177         *  map the ids to physical peripherals.
   178         *
   179         *  @param(id)      Timer id ranging from 0 to a platform specific value,
   180         *                  or {@link #ANY}
   181         *  @param(tickFxn) function that runs upon timer expiry.
   182         */
   183        @DirectCall
   184        create(Int id, FuncPtr tickFxn);
   185
   186        /*!
   187         *  Timer run mode
   188         *
   189         *  Default is {@link #RunMode_CONTINUOUS}.
   190         */
   191        config RunMode runMode = RunMode_CONTINUOUS;
   192
   193        /*!
   194         *  Timer start mode
   195         *
   196         *  Default is {@link #StartMode_AUTO}.
   197         */
   198        config StartMode startMode = StartMode_AUTO;
   199
   200        /*!
   201         *  Argument for tick function
   202         *
   203         *  Default is null.
   204         */
   205        config UArg arg = null;
   206
   207        /*!
   208         *  Period of a tick
   209         *
   210         *  The period can be specified in timer counts or microseconds
   211         *  and its default value is 0.
   212         *
   213         *  The implementation of ITimer will support a period of UInt32
   214         *  timer counts and use pre-scalars if necessary.
   215         */
   216        config UInt32 period = 0;
   217
   218        /*!
   219         *  Period type
   220         *
   221         *  Default is PeriodType_MICROSECS
   222         */
   223        config PeriodType periodType = PeriodType_MICROSECS;
   224
   225        /*!
   226         *  Timer frequency
   227         *
   228         *  This parameter is meaningfull only on platforms where the timer's
   229         *  input clock can be changed. If value is left at zero, then input clock
   230         *  to the timer clock is assumed.
   231         *
   232         *  This value is used to convert timer ticks to real time units; seconds,
   233         *  milliseconds, etc.
   234         */
   235        config xdc.runtime.Types.FreqHz extFreq  = {lo:0, hi:0};
   236
   237        /*!
   238         *  @_nodoc
   239         *  ======== getMaxTicks ========
   240         *  Gets the maximum number of timer ticks that can be skipped (for Clock
   241         *  tick suppression), given the current timer configuration.
   242         *
   243         *  This API is used internally by SYS/BIOS for dynamic Clock tick
   244         *  suppression.  It is not intended to be used for any other purpose.
   245         */
   246        @DirectCall
   247        UInt32 getMaxTicks(UInt32 periodCounts);
   248
   249        /*!
   250         *  @_nodoc
   251         *  ======== setNextTick ========
   252         *  Dynamically reprograms the timer with a new period value,
   253         *  corresponding to the next required tick.  The timer is left running
   254         *  after the call, and it does not need to be stopped and restarted by
   255         *  the caller.
   256         *
   257         *  This API is used internally by SYS/BIOS for dynamic Clock tick
   258         *  suppression.  It is not intended to be used for any other purpose.
   259         *
   260         *  @param(newPeriod)       new timer period, in units of timer counts
   261         *  @param(countsPerTick)   timer counts corresponding to a single tick
   262         */
   263        @DirectCall
   264        Void setNextTick(UInt32 newPeriod, UInt32 countsPerTick);
   265
   266        /*!
   267         *  ======== start ========
   268         *  Reload and start the timer
   269         *
   270         *  Thread safety must be observed when using the {@link #start}
   271         *  and {@link #stop} APIs to avoid possible miss-
   272         *  configuration of the timers and unintended behaviors.
   273         *  To protect against re-entrancy, surround the start/stop invocations
   274         *  with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
   275         *  {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
   276         *
   277         *  @p(code)
   278         *  // disable interrupts if an interrupt could lead to
   279         *  // another call to Timer_start().
   280         *  key = Hwi_disable();
   281         *  Timer_stop();
   282         *  ...
   283         *  Timer_start();
   284         *  Hwi_restore(key);
   285         *  @p
   286         *
   287         *  @a(side effects)
   288         *  Enables the timer's interrupt.
   289         */
   290        @DirectCall
   291        Void start();
   292
   293        /*!
   294         *  ======== stop ========
   295         *  Stop the timer
   296         *
   297         *  Thread safety must be observed when using the {@link #start}
   298         *  and {@link #stop} APIs to avoid possible miss-
   299         *  configuration of the timers and unintended behaviors.
   300         *  To protect against re-entrancy, surround the start/stop invocations
   301         *  with {@link ti.sysbios.hal.Hwi#disable Hwi_disable()} and
   302         *  {@link ti.sysbios.hal.Hwi#restore Hwi_restore()} calls:
   303         *
   304         *  @p(code)
   305         *  // disable interrupts if an interrupt could lead to
   306         *  // another call to Timer_start().
   307         *  key = Hwi_disable();
   308         *  Timer_stop();
   309         *  ...
   310         *  Timer_start();
   311         *  Hwi_restore(key);
   312         *  @p
   313         *
   314         *  @a(side effects)
   315         *  Disables the timer's interrupt.
   316         */
   317        @DirectCall
   318        Void stop();
   319
   320        /*!
   321         *  ======== setPeriod ========
   322         *  Set timer period specified in timer counts
   323         *
   324         *  Timer_setPeriod() invokes Timer_stop() prior to setting the period
   325         *  and leaves the timer in the stopped state.
   326         *
   327         *  To dynamically change the period of a timer you must
   328         *  protect against re-entrancy by disabling interrupts.
   329         *  Use the following call sequence to guarantee proper results:
   330         *
   331         *  @p(code)
   332         *  // disable interrupts if an interrupt could lead to
   333         *  // another call to Timer_start().
   334         *  key = Hwi_disable();
   335         *  Timer_setPeriod(period);
   336         *  Timer_start();
   337         *  Hwi_restore(key);
   338         *  @p
   339         *
   340         *  ITimer implementation must support UInt32 and use pre-scalars whenever
   341         *  necessary
   342         *
   343         *  @a(side effects)
   344         *  Calls Timer_stop(), and disables the timer's interrupt.
   345         *
   346         *  @param(period)          period in timer counts
   347         */
   348        @DirectCall
   349        Void setPeriod(UInt32 period);
   350
   351        /*!
   352         *  ======== setPeriodMicroSecs ========
   353         *  Set timer period specified in microseconds.
   354         *
   355         *  A best-effort method will be used to set the period register.
   356         *  There might be a slight rounding error based on resolution of timer
   357         *  period register. If the timer frequency cannot support the requested
   358         *  period, i.e. the timer period register cannot support the requested
   359         *  period, then this function returns false.
   360         *
   361         *  Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting
   362         *  the period and leaves the timer in the stopped state.
   363         *
   364         *  To dynamically change the period of a timer you must
   365         *  protect against re-entrancy by disabling interrupts.
   366         *  Use the following call sequence to guarantee proper results:
   367         *
   368         *  @p(code)
   369         *  // disable interrupts if an interrupt could lead to
   370         *  // another call to Timer_start().
   371         *  key = Hwi_disable();
   372         *  Timer_setPeriodMicroSecs(period);
   373         *  Timer_start();
   374         *  Hwi_restore(key);
   375         *  @p
   376         *
   377         *  @param(period)          period in microseconds
   378         */
   379        @DirectCall
   380        Bool setPeriodMicroSecs(UInt32 microsecs);
   381
   382        /*!
   383         *  ======== getPeriod ========
   384         *  Get timer period in timer counts
   385         *
   386         *  @b(returns)     period in timer counts
   387         */
   388        @DirectCall
   389        UInt32 getPeriod();
   390
   391        /*!
   392         *  ======== getCount ========
   393         *  Read timer counter register
   394         *
   395         *  @b(returns)     timer counter value
   396         */
   397        @DirectCall
   398        UInt32 getCount();
   399
   400        /*!
   401         *  ======== getFreq ========
   402         *  Return timer frequency in Hz
   403         *
   404         *  This is the effective frequency of the clock incrementing the timer
   405         *  counter register after all scaling factors are taken into account.
   406         *  (including pre-scalars).
   407         *
   408         *  @param(freq)    frequency in Hz
   409         */
   410        @DirectCall
   411        Void getFreq(xdc.runtime.Types.FreqHz *freq);
   412
   413        /*!
   414         *  ======== getFunc ========
   415         *  Get Timer function and arg
   416         *
   417         *  @param(arg)     pointer for returning Timer's function argument
   418         *  @b(returns)     Timer's function
   419         */
   420        @DirectCall
   421        FuncPtr getFunc(UArg *arg);
   422
   423        /*!
   424         *  ======== setFunc ========
   425         *  Overwrite Timer function and arg
   426         *
   427         *  Replaces a Timer object's tickFxn function originally
   428         *  provided in {@link #create}.
   429         *
   430         *  @param(fxn)     pointer to function
   431         *  @param(arg)     argument to function
   432         */
   433        @DirectCall
   434        Void setFunc(FuncPtr fxn, UArg arg);
   435
   436        /*!
   437         *  ======== trigger ========
   438         *  Trigger timer function
   439         *
   440         *  @_nodoc
   441         *  Timer runs for specified number of cycles. The runMode
   442         *  must be Mode_ONESHOT.
   443         *
   444         *  This function should interrupt the cpu after specified number of
   445         *  cpu cycles.
   446         *
   447         *  The last instruction of trigger will start the timer. Depending on how
   448         *  the code is compiled, there may be one or more instructions in between
   449         *  the timer start and client code. The number of instructions specified
   450         *  is counted from when the timer is started.
   451         *
   452         *  @param(instructions)    cpu cycles
   453         */
   454        @DirectCall
   455        Void trigger(UInt32 cycles);
   456
   457        /*!
   458         *  ======== getExpiredCounts ========
   459         *  Get current timer counter
   460         *
   461         *  @_nodoc
   462         *  Reads timer counter and adds period if IFR was set
   463         *  before counter read. Used exclusively by TimestampProvider.
   464         *
   465         *  Must be called with interrupts disabled.
   466         *
   467         *  @b(returns)     expired counts.
   468         */
   469        @DirectCall
   470        UInt32 getExpiredCounts();
   471
   472    }
   473    /*
   474     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   475
   476     */
   477


interface ti.sysbios.interfaces.ITimerSupport

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== ITimerSupport.xdc ========
    34     *
    35     *
    36     */
    37
    38    import xdc.runtime.Error;
    39
    40    /*!
    41     *  ======== ITimerSupport ========
    42     *  Interface for TimerSupport Manager.
    43     */
    44    interface ITimerSupport
    45    {
    46        /*!
    47         *  ======== enable ========
    48         */
    49        @DirectCall
    50        Void enable(UInt timerId, Error.Block *eb);
    51    }
    52    /*
    53     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:00; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    54
    55     */
    56


interface ti.sysbios.interfaces.ITimestamp

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ITimestamp.xdc ========
    15     */
    16    package ti.sysbios.interfaces;
    17
    18    /*!
    19     *  ======== ITimestamp ========
    20     *  Timestamp  Interface
    21     *
    22     *  This interface defines the methods used by client applications to
    23     *  get timestamp values.  It is implemented by the
    24     *  `{@link xdc.runtime.Timestamp Timestamp}` module.
    25     */
    26    interface ITimestamp inherits xdc.runtime.ITimestampProvider
    27    {
    28         /*!
    29         *  ======== get32 ========
    30         *  Return a 32-bit timestamp
    31         *
    32         *  @a(returns)
    33         *  Returns a 32-bit timestamp value.
    34         *  Use `{@link #getFreq}` to convert this value into units of real time.
    35         *
    36         *  @see #get64
    37         */
    38        @DirectCall
    39        override Bits32 get32();
    40
    41        /*!
    42         *  ======== get64 ========
    43         *  Return a 64-bit timestamp
    44         *
    45         *  @param(result)  pointer to 64-bit result
    46         *
    47         *      This parameter is a pointer to a structure representing a 64-bit
    48         *      wide timestamp value where the current timestamp is written.
    49         *
    50         *      If the underlying hardware does not support 64-bit resolution, the
    51         *      `hi` field of `result` is always set to 0; see
    52         *      `{@link xdc.runtime.Types#Timestamp64}`.  So, it is possible for
    53         *      the `lo` field to wrap around without any change to the `hi` field.
    54         *      Use `{@link #getFreq}` to convert this value into units of real
    55         *      time.
    56         *
    57         *  @see #get32
    58         */
    59        @DirectCall
    60        override Void get64(xdc.runtime.Types.Timestamp64 *result);
    61
    62        /*!
    63         *  ======== getFreq ========
    64         *  Get the timestamp timer's frequency (in Hz)
    65         *
    66         *  @param(freq)  pointer to a 64-bit result
    67         *
    68         *      This parameter is a pointer to a structure representing a 64-bit
    69         *      wide frequency value where the timer's frequency (in Hz)
    70         *      is written; see `{@link xdc.runtime.Types#FreqHz}`.
    71         *      This function provides a way of converting timestamp
    72         *      values into units of real time.
    73         *
    74         *  @see #get32
    75         *  @see #get64
    76         */
    77        @DirectCall
    78        override Void getFreq(xdc.runtime.Types.FreqHz *freq);
    79    }
    80    /*
    81     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:01; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    82
    83     */
    84


package ti.sysbios.interfaces

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.interfaces ========
    39     *  Contains all interface specifications.
    40     *
    41     *  For the proxy-delegate mechanism between generic modules and the
    42     *  modules in {@link ti.sysbios.family} to work properly, both the
    43     *  proxy and the delegate modules must be implementations of a common
    44     *  interface specification. The Timer, Hwi, and Cache interface
    45     *  specifications reside in ti.sysbios.interfaces and are
    46     *  {@link ti.sysbios.interfaces.ITimer},
    47     *  {@link ti.sysbios.interfaces.IHwi}, and
    48     *  {@link ti.sysbios.interfaces.ICache} respectively.
    49     *
    50     *  These interface specifications define a minimum set of general APIs
    51     *  that, it is  believed, will satisfy a vast majority of application
    52     *  requirements.
    53     *
    54     *  The I<mod>Support interfaces define "internal" interfaces used by the
    55     *  <mod> modules in their implementation.  These interfaces simplify the
    56     *  process of porting to a new architecture; one only needs to implement
    57     *  the I<mod>Support interface to enable the full functionality of the
    58     *  ti.sysbios.<mod> module.
    59     *
    60     */
    61    package ti.sysbios.interfaces [2,0,0,0] {
    62        interface IHwi;
    63        interface ITaskSupport;
    64        interface ITimer;
    65        interface ITimerSupport;
    66        interface ITimestamp;
    67        interface IIntrinsicsSupport;
    68        interface ICache;
    69        interface ISettings;
    70    }
    71    /*
    72     *  @(#) ti.sysbios.interfaces; 2, 0, 0, 0,495; 6-15-2011 16:26:01; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    73
    74     */
    75


module ti.sysbios.knl.Clock

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Clock.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.knl;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Diags;
    44    import xdc.runtime.Log;
    45
    46    import ti.sysbios.hal.Timer;
    47
    48    /*!
    49     *  ======== Clock ========
    50     *  System Clock Manager
    51     *
    52     *  The System Clock Manager is responsible for all timing services in
    53     *  SYS/BIOS.
    54     *  It generates the periodic system tick. The tick period is configurable.
    55     *  The timeout and period for all Clock Instances and timeout values in
    56     *  other SYS/BIOS modules are specified in terms of Clock ticks.
    57     *
    58     *  The Clock Manager supports two tick "modes": a periodic mode with an
    59     *  interrupt on each tick (TickMode_PERIODIC), and a tick suppression
    60     *  mode (TickMode_DYNAMIC), which reduces the number of timer interrupts to
    61     *  the minimum required to support the scheduled timeouts.  For devices that
    62     *  support it (e.g., MSP430 devices), TickMode_DYNAMIC will be the default
    63     *  mode if one is not specified in the application configuration; otherwise,
    64     *  the default mode will be TickMode_PERIODIC.  The following example shows
    65     *  how the tick mode  can be specified in the application configuration:
    66     *
    67     *  @p(code)
    68     *  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
    69     *
    70     *  // Tell the Clock module to use TickMode_PERIODIC
    71     *  Clock.tickMode = Clock.TickMode_PERIODIC;
    72     *  @p
    73     *
    74     *  Clock Instances are functions that can be scheduled to run after a
    75     *  certain number of Clock ticks.
    76     *  Clock instances are either one-shot or periodic. Instances are started
    77     *  when created or they are started later using the Clock_start()function.
    78     *  Instances can be stopped using the Clock_stop() function. All Clock
    79     *  Instances are executed when they expire in the context of a software
    80     *  interrupt.
    81     *
    82     *  Clock objects are placed in the Clock object service list when
    83     *  created/constructed and remain there until deleted/destructed.
    84     *  To minimize processing overhead, unused or expired Clock objects
    85     *  should be deleted or destructed.
    86     *
    87     *  The getTicks() function returns number of clock ticks since startup.
    88     *
    89     *  By default, the Clock module statically configures a
    90     *  {@link ti.sysbios.hal.Timer}
    91     *  timer instance to provide the periodic 1 ms tick interrupt. If you
    92     *  want to use a custom configured timer for the Clock module's tick source,
    93     *  use the following example configuration as a guide:
    94     *
    95     *  @p(code)
    96     *  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
    97     *
    98     *  // Tell the Clock module that YOU are providing the periodic interrupt
    99     *  Clock.tickSource = Clock.TickSource_USER;
   100     *
   101     *  // this example uses the ti.sysbios.timers.dmtimer.Timer module
   102     *  var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
   103     *
   104     *  // create a dmtimer config parameter object
   105     *  var timerParams = new Timer.Params();
   106     *
   107     *  // make sure you set the period to 1000 us (1ms)
   108     *  timerParams.period = 1000;
   109     *
   110     *  // custom dmtimer config parameters here...
   111     *  timerParams.twer.ovf_wup_ena = 1;
   112     *
   113     *  // Create the timer.
   114     *  // This example uses timer id 3.
   115     *  // The timer interrupt handler must be set to 'Clock.tick'.
   116     *  Timer.create(3, Clock.tick, timerParams);
   117     *  @p
   118     *
   119     *  @p(html)
   120     *  <h3> Calling Context </h3>
   121     *  <table border="1" cellpadding="3">
   122     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   123     *    </colgroup>
   124     *
   125     *    <tr><th> Function                </th><th>  Hwi   </th><th>  Swi   </th>
   126     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   127     *    <!--                                                                -->
   128     *    <tr><td> {@link #construct}      </td><td>   N    </td><td>   N    </td>
   129     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   130     *    <tr><td> {@link #create}         </td><td>   N    </td><td>   N    </td>
   131     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   132     *    <tr><td> {@link #delete}         </td><td>   N    </td><td>   N    </td>
   133     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   134     *    <tr><td> {@link #destruct}       </td><td>   N    </td><td>   N    </td>
   135     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   136     *    <tr><td> {@link #getTicks}       </td><td>   Y    </td><td>   Y    </td>
   137     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   138     *    <tr><td> {@link #getTimeout}     </td><td>   Y    </td><td>   Y    </td>
   139     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   140     *    <tr><td> {@link #getTimerHandle} </td><td>   Y    </td><td>   Y    </td>
   141     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   142     *    <tr><td> {@link #Params_init}    </td><td>   Y    </td><td>   Y    </td>
   143     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   144     *    <tr><td> {@link #setFunc}        </td><td>   Y    </td><td>   Y    </td>
   145     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   146     *    <tr><td> {@link #setPeriod}      </td><td>   Y    </td><td>   Y    </td>
   147     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   148     *    <tr><td> {@link #setTimeout}     </td><td>   Y    </td><td>   Y    </td>
   149     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   150     *    <tr><td> {@link #start}          </td><td>   Y    </td><td>   Y    </td>
   151     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   152     *    <tr><td> {@link #stop}           </td><td>   Y    </td><td>   Y    </td>
   153     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   154     *    <tr><td> {@link #tick}           </td><td>   Y    </td><td>   Y    </td>
   155     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   156     *    <tr><td> {@link #tickReconfig}   </td><td>   Y    </td><td>   Y    </td>
   157     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   158     *    <tr><td> {@link #tickStart}      </td><td>   Y    </td><td>   Y    </td>
   159     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   160     *    <tr><td> {@link #tickStop}       </td><td>   Y    </td><td>   Y    </td>
   161     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   162     *    <tr><td colspan="6"> Definitions: <br />
   163     *       <ul>
   164     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   165     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   166     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   167     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   168     *           <ul>
   169     *             <li> In your module startup after this module is started
   170     *    (e.g. Clock_Module_startupDone() returns TRUE). </li>
   171     *             <li> During
   172     *    {@link xdc.runtime.Startup#lastFxns Startup.lastFxns}. </li>
   173     *             <li> During main().</li>
   174     *             <li> During
   175     *    {@link ti.sysbios.BIOS#startupFxns BIOS.startupFxns}.</li>
   176     *           </ul>
   177     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   178     *           <ul>
   179     *             <li> During
   180     *    {@link xdc.runtime.Startup#firstFxns Startup.firstFxns}.</li>
   181     *             <li> In your module startup before this module is started
   182     *    (e.g. Clock_Module_startupDone() returns FALSE).</li>
   183     *           </ul>
   184     *       </ul>
   185     *    </td></tr>
   186     *
   187     *  </table>
   188     *  @p
   189     */
   190
   191    @ModuleStartup
   192    @InstanceFinalize   /* generate call to Clock_Instance_finalize on delete */
   193    @Template("./Clock.xdt")
   194
   195    module Clock
   196    {
   197        /*!
   198         *  ======== TickSource ========
   199         *  Clock tick source
   200         *
   201         *  @field(TickSource_TIMER) {@link #tick Clock_tick()} is called
   202         *  automatically from within a {@link ti.sysbios.hal.Timer} ISR.  The
   203         *  specific timer and its period can be controlled via {@link #timerId}
   204         *  and {@link tickPeriod}.
   205         *
   206         *  @field(TickSource_USER) {@link #tick Clock_tick()} must be explicitly
   207         *  called by the user's application.
   208         *
   209         *  @field(TickSource_NULL)  {@link #tick Clock_tick()} is never called.
   210         *  In this case, it is an error for the application to ever call
   211         *  Clock_tick().
   212         *
   213         *  @see #tickPeriod
   214         *  @see #timerId
   215         */
   216        enum  TickSource {
   217            TickSource_TIMER,   /*! Use Timer to automatically call Clock_tick() */
   218            TickSource_USER,    /*! Application explicitly calls Clock_tick() */
   219            TickSource_NULL     /*! Clock_tick() is never called */
   220        };
   221
   222        /*!
   223         *  ======== TickMode ========
   224         *  Clock Tick Mode
   225         */
   226        enum  TickMode {
   227            TickMode_PERIODIC,  /*! Timer will interrupt every period */
   228            TickMode_DYNAMIC    /*! Unnecessary timer ticks can be suppressed */
   229        };
   230
   231        /*!
   232         *  ======== BasicView ========
   233         *  @_nodoc
   234         */
   235        metaonly struct BasicView {
   236            String          label;
   237            UInt32          timeout;
   238            UInt            period;
   239            String          fxn[];
   240            UArg            arg;
   241            Bool            started;        /* Instance running? */
   242            String          tRemaining;     /* Remaining timeout */
   243            Bool            periodic;       /* Periodic? (vs. one-shot) */
   244        }
   245
   246        /*!
   247         *  ======== ModuleView ========
   248         *  @_nodoc
   249         */
   250        metaonly struct ModuleView {
   251            String          ticks;
   252            String          tickSource;
   253            String          tickMode;
   254            String          timerHandle;
   255            UInt            timerId;
   256            UInt            swiPriority;
   257            UInt32          tickPeriod;
   258            volatile UInt   nSkip;
   259        }
   260
   261        /*
   262         *  ======== rovViewInfo ========
   263         *  @_nodoc
   264         */
   265        @Facet
   266        metaonly config ViewInfo.Instance rovViewInfo =
   267            ViewInfo.create({
   268                viewMap: [
   269                  ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',  structName: 'BasicView'}],
   270                  ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule', structName: 'ModuleView'}],
   271                ]
   272            });
   273
   274        /*!
   275         *  ======== FuncPtr ========
   276         * Instance function prototype
   277         */
   278        typedef Void (*FuncPtr)(UArg);
   279
   280        /*!
   281         *  ======== LW_delayed ========
   282         *  Logged if Clock Swi delayed by >= 1 tick
   283         */
   284        config Log.Event LW_delayed = {
   285            mask: Diags.USER3,
   286            msg: "LW_delayed: delay: %d"
   287        };
   288
   289        /*!
   290         *  ======== LM_tick ========
   291         *  Logged in every Clock tick interrupt
   292         */
   293        config Log.Event LM_tick = {
   294            mask: Diags.USER1 | Diags.USER2,
   295            msg: "LM_tick: tick: %d"
   296        };
   297
   298        /*!
   299         *  ======== LM_begin ========
   300         *  Logged just prior to calling each Clock function
   301         */
   302        config Log.Event LM_begin = {
   303            mask: Diags.USER1 | Diags.USER2,
   304            msg: "LM_begin: clk: 0x%x, func: 0x%x"
   305        };
   306
   307        /*!
   308         *  ======== A_clockDisabled ========
   309         *  Asserted in Clock_create()
   310         */
   311        config Assert.Id A_clockDisabled = {
   312            msg: "A_clockDisabled: Cannot create a clock instance when BIOS.clockEnabled is false."
   313        };
   314
   315        /*!
   316         *  ======== A_badThreadType ========
   317         *  Asserted in Clock_create and Clock_delete
   318         */
   319        config Assert.Id A_badThreadType = {
   320            msg: "A_badThreadType: Cannot create/delete a Clock from Hwi or Swi thread."
   321        };
   322
   323        /*!
   324         *  ======== tickSource ========
   325         *  Source of clock ticks
   326         *
   327         *  If this parameter is not set to TickSource_TIMER,
   328         *  {@link #tickStart Clock_tickStart()},
   329         *  {@link #tickStop Clock_tickStop()}, and
   330         *  {@link #tickReconfig Clock_tickReconfig()}, have no effect.
   331         *
   332         *  The default is TickSource_TIMER.
   333         */
   334        config TickSource tickSource = TickSource_TIMER;
   335
   336        /*!
   337         *  ======== tickMode ========
   338         *  Timer tick mode
   339         *
   340         *  This parameter specifies the tick mode to be used by the underlying
   341         *  Timer.  With TickMode_PERIODIC the timer will interrupt the CPU at
   342         *  a fixed rate, defined by the tickPeriod.  With TickMode_DYNAMIC the
   343         *  timer can be dynamically reprogrammed by Clock, to interrupt the CPU
   344         *  when the next tick is actually needed for a scheduled timeout.
   345         */
   346        config TickMode tickMode;
   347
   348        /*!
   349         *  ======== timerId ========
   350         *  Timer Id used to create a Timer instance
   351         *
   352         *  If {@link #tickSource Clock.tickSource} is set to TickSource_TIMER,
   353         *  the Clock module automatically  creates a
   354         *  {@link ti.sysbios.hal.Timer#create instance} that automatically calls
   355         *  Clock_doTick() on a periodic basis (as specified by
   356         *  {@link #tickPeriod tickPeriod} and {@link #periodType periodType}.)
   357         *
   358         *  This configuration parameter allows you to control which timer is
   359         *  used to drive the Clock module.
   360         *
   361         *  The default value is {@link ti.sysbios.hal.Timer#ANY Timer.ANY} (~0)
   362         *  and the maximum timerId possible is family and device specific.
   363         *
   364         *  @see ti.sysbios.hal.Timer
   365         */
   366        config UInt timerId = ~0;
   367
   368        /*!
   369         *  ======== swiPriority ========
   370         *  The priority of Swi used by Clock to process its instances
   371         *
   372         *  All Clock instances are executed in the context of a single
   373         *  {@link Swi}.  This parameter allows you to control the priority of
   374         *  that Swi.
   375         *
   376         *  The default value of this parameter is Swi.numPriorities - 1; i.e.,
   377         *  the maximum Swi priority.
   378         *
   379         *  @see ti.sysbios.knl.Swi#numPriorities
   380         */
   381        metaonly config UInt swiPriority;
   382
   383        /*!
   384         *  ======== tickPeriod ========
   385         *  Tick period specified in microseconds
   386         *
   387         *  Default value is family dependent. For example, Linux systems often
   388         *  only support a minimum period of 10000 us and multiples of 10000 us.
   389         *  TI platforms have a default of 1000 us.
   390         */
   391        config UInt32 tickPeriod;
   392
   393        /*!
   394         *  ======== getTicks ========
   395         *  Time in Clock ticks
   396         *
   397         *  The value returned will wrap back to zero after it reaches the max
   398         *  value that can be stored in 32 bits.
   399         *
   400         *  @b(returns)     time in clock ticks
   401         */
   402        @DirectCall
   403        UInt32 getTicks();
   404
   405        /*!
   406         *  ======== getTimerHandle ========
   407         *  Get timer Handle
   408         *
   409         *  Used when is it necessary to change family
   410         *  specific options for the timer and its Hwi Object.
   411         *
   412         *  @b(returns)     Timer Handle
   413         */
   414        @DirectCall
   415        ti.sysbios.hal.Timer.Handle getTimerHandle();
   416
   417        /*!
   418         *  ======== tickStop ========
   419         *  Stop clock for reconfiguration
   420         *
   421         *  This function is used to stop the timer used for generation of
   422         *  clock ticks. It is used along with Clock_tickStart() and
   423         *  Clock_tickReconfig() to allow reconfiguration of timer at runtime.
   424         *
   425         *  @a(constraints)
   426         *  This function is non-reentrant and appropriate locks must be used to
   427         *  protect against  re-entrancy.
   428         */
   429        @DirectCall
   430        Void tickStop();
   431
   432        /*!
   433         *  ======== tickReconfig ========
   434         *  Reconfigure clock for new cpu frequency
   435         *
   436         *  This function uses the new cpu frequency to reconfigure the timer used
   437         *  for generation of clock ticks such that tick period is
   438         *  accurate.  This function is used along with Clock_tickStop() and
   439         *  Clock_tickStart() to allow reconfiguration of timer at runtime.
   440         *
   441         *  When calling Clock_tickReconfig outside of main(), you must also call
   442         *  Clock_tickStop and Clock_tickStart to stop and restart the timer.
   443         *  Use the following call sequence:
   444         *
   445         *  @p(code)
   446         *  // disable interrupts if an interrupt could lead to
   447         *  // another call to Clock_tickReconfig or if interrupt
   448         *  // processing relies on having a running timer
   449         *  Hwi_disable() or Swi_disable();
   450         *  BIOS_setCpuFrequency(Types.FreqHz *freq);
   451         *  Clock_tickStop();
   452         *  Clock_tickReconfig();
   453         *  Clock_tickStart();
   454         *  Hwi_restore() or Swi_enable()
   455         *  @p
   456         *
   457         *  When calling Clock_tickReconfig from main(), the timer has not yet
   458         *  been started because the timer is started as part of BIOS_start().
   459         *  As a result, you can use the following simplified call sequence
   460         *  in main():
   461         *
   462         *  @p(code)
   463         *  BIOS_setCpuFrequency(Types.FreqHz *freq);
   464         *  Clock_tickReconfig(Void);
   465         *  @p
   466         *
   467         *  The return value is false if the timer cannot support the new
   468         *  frequency
   469         *
   470         *  @b(returns)     true if successful
   471         *
   472         *  @a(constraints)
   473         *  This function is non-reentrant and appropriate locks must be used to
   474         *  protect against  re-entrancy.
   475         */
   476        @DirectCall
   477        Bool tickReconfig();
   478
   479        /*!
   480         *  ======== tickStart ========
   481         *  Start clock after reconfiguration
   482         *
   483         *  This function starts the timer used for generation of clock ticks
   484         *  It is used along with Clock_tickStop() and Clock_tickReconfig() to
   485         *  allow reconfiguration of timer at runtime. The new timer configuration
   486         *  reflects changes caused by a call to reconfig().
   487         *
   488         *  @a(constraints)
   489         *  This function is non-reentrant and appropriate locks must be used to
   490         *  protect against  re-entrancy.
   491         */
   492        @DirectCall
   493        Void tickStart();
   494
   495        /*!
   496         *  ======== tick ========
   497         *  Advance Clock time by one tick
   498         *
   499         *  After incrementing a global tick counter, this function posts a Swi
   500         *  that processes the clock instances.
   501         *
   502         *  This function is automatically called by a timer ISR when
   503         *  {@link #tickSource} is set to {@link #TickSource_TIMER}.
   504         *
   505         *  When {@link #tickSource} is set to
   506         *  {@link #TickSource_USER}, Clock_tick() must be called by the
   507         *  application.  Usually, this is done within a user defined {@link Hwi},
   508         *  {@link Swi}, or {@link Task}.
   509         *
   510         *  Note that this function is not re-entrant.  The application is
   511         *  responsible for ensuring that invocations of this function are
   512         *  serialized: either only one thread in the system ever calls this
   513         *  function or all calls are "wrapped" by an appropriate mutex.
   514         *
   515         *  @see #tickSource
   516         */
   517        @DirectCall
   518        Void tick();
   519
   520        /*!
   521         *  @_nodoc
   522         *  ======== workFunc ========
   523         *  Clock Q service routine
   524         *
   525         *  @param(arg0)    Unused. required to match Swi.FuncPtr
   526         *  @param(arg1)    Unused. required to match Swi.FuncPtr
   527         */
   528        @DirectCall
   529        Void workFunc(UArg arg0, UArg arg1);
   530
   531        /*!
   532         *  @_nodoc
   533         *  ======== workFuncDynamic ========
   534         *  Clock Q service routine for TickMode_DYNAMIC
   535         *
   536         *  @param(arg0)    Unused. required to match Swi.FuncPtr
   537         *  @param(arg1)    Unused. required to match Swi.FuncPtr
   538         */
   539        @DirectCall
   540        Void workFuncDynamic(UArg arg0, UArg arg1);
   541
   542        /*!
   543         *  @_nodoc
   544         *  ======= logTick ========
   545         *  Log the LD_tick from within Clock module scope
   546         */
   547        @DirectCall
   548        Void logTick();
   549
   550        /*!
   551         *  @_nodoc
   552         *  ======== getCompletedTicks ========
   553         *  Get the number of Clock ticks that have completed
   554         *
   555         *  Retuns the number of ticks completed, to the point where
   556         *  the underlying Timer interrupt has been serviced.
   557         *
   558         *  @b(returns)     time in clock ticks
   559         */
   560        @DirectCall
   561        UInt32 getCompletedTicks();
   562
   563        /*!
   564         *  @_nodoc
   565         *  ======== getTickPeriod ========
   566         *  Get the Clock tick period
   567         *
   568         *  The period is in units returned by the underlying Timer.
   569         *
   570         *  @b(returns)     period in timer counts
   571         */
   572        @DirectCall
   573        UInt32 getTickPeriod();
   574
   575        /*!
   576         *  @_nodoc
   577         *  ======= setupTimerToSkipTicks ========
   578         *  Reprogram Clock's Timer to suppress unnecessary tick interrupts
   579         */
   580        @DirectCall
   581        Void setupTimerToSkipTicks(UInt skips);
   582
   583    instance:
   584
   585        /*!
   586         *  ======== create ========
   587         *  Creates a Clock Instance
   588         *
   589         *  The first argument is the function that gets called when the timeout
   590         *  expires.
   591         *
   592         *  The 'timeout' argument is used to specify the initial timeout
   593         *  for both one-shot and periodic Clock instances (in Clock ticks).
   594         *
   595         *  The {@link #period} parameter is used to set the subsequent timeout
   596         *  interval (in Clock ticks) for periodic instances.
   597         *
   598         *  For one-shot instances, the period parameter must be set to zero.
   599         *
   600         *  When instances are created they are placed upon a linked list managed
   601         *  by the Clock module.  For this reason, instances cannot be created
   602         *  from either Hwi or Swi context.
   603         *
   604         *  @param(clockFxn)  Function that runs upon timeout
   605         *  @param(timeout)   One-shot timeout or initial start delay (in clock
   606         *                    ticks)
   607         */
   608        @DirectCall
   609        create(FuncPtr clockFxn, UInt timeout);
   610
   611        /*!
   612         *  ======== startFlag ========
   613         *  Start immediately after instance is created
   614         *
   615         *  When this flag is set to false, the user will have to call
   616         *  Clock_start() to start the instance.
   617         *
   618         *  When set to true, both statically created Clock objects and Clock
   619         *  objects created in main() are started at the end of main() when the
   620         *  user calls BIOS_start(). Dynamically created Clock objects created
   621         *  after main() (ie within a task) will be started immediately.
   622         *
   623         *  The default setting for this parameter is false.
   624         *
   625         *  The configured Clock function will be called initially after an
   626         *  interval equal to the 'timeout' argument for both one-shot and
   627         *  periodic Clock objects.
   628         *
   629         *  Periodic Clock objects will subsequently be called at the rate
   630         *  specified by the {@link #period} parameter.
   631         *
   632         */
   633        config Bool startFlag = false;
   634
   635        /*!
   636         *  ======== period ========
   637         *  Period of this instance (in clock ticks)
   638         *
   639         *  The default value of this parameter is 0, which indicates this is
   640         *  a one-shot Clock object.
   641         *
   642         *  A non zero value for this parameter specifies that the Clock
   643         *  object is to be called periodically, and also specifies the
   644         *  rate (in Clock ticks) that the Clock function will be called
   645         *  AFTER the initial 'timeout' argument period.
   646         *
   647         *  For one-shot Clock instances, this parameter must be set to zero.
   648         */
   649        config UInt period = 0;
   650
   651        /*!
   652         *  ======== arg ========
   653         *  Uninterpreted argument passed to instance function
   654         *
   655         *  The default is null.
   656         */
   657        config UArg arg = null;
   658
   659        /*!
   660         *  ======== start ========
   661         *  Start instance
   662         *
   663         *  The {@link #timeout} and {@link #period} values set during create()
   664         *  or by calling Clock_setTimeout() and Clock_setPeriod() are used and
   665         *  the expiry is recomputed.
   666         *  Note that for periodic instances, the first expiry is
   667         *  computed using the timeout specified. All subsequent expiries use the
   668         *  period value.
   669         *
   670         *  @a(constraints)
   671         *  Timeout of instance cannot be zero
   672         */
   673        @DirectCall
   674        Void start();
   675
   676        /*!
   677         *  @_nodoc
   678         *  ======== startI ========
   679         *  Internal start function which assumes Hwis disabled
   680         */
   681        @DirectCall
   682        Void startI();
   683
   684        /*!
   685         *  ======== stop ========
   686         *  Stop instance
   687         */
   688        @DirectCall
   689        Void stop();
   690
   691        /*!
   692         *  ======== setPeriod ========
   693         *  Set periodic interval
   694         *
   695         *  @param(period)          periodic interval in Clock ticks
   696         *
   697         *  @a(constraints)
   698         *  Cannot change period of instance that has been started.
   699         */
   700        @DirectCall
   701        Void setPeriod(UInt period);
   702
   703        /*!
   704         *  ======== setTimeout ========
   705         *  Set the initial timeout
   706         *
   707         *  @param(timeout)         initial timeout in Clock ticks
   708         *
   709         *  @a(constraints)
   710         *  Cannot change the initial timeout of instance that has been started.
   711         */
   712        @DirectCall
   713        Void setTimeout(UInt timeout);
   714
   715        /*!
   716         *  ======== setFunc ========
   717         *  Overwrite Clock function and arg
   718         *
   719         *  Replaces a Clock object's clockFxn function originally
   720         *  provided in {@link #create}.
   721         *
   722         *  @param(clockFxn)        function of type FuncPtr
   723         *  @param(arg)             argument to clockFxn
   724         *
   725         *  @a(constraints)
   726         *  Cannot change function and arg of Clock object that has been started.
   727         */
   728        @DirectCall
   729        Void setFunc(FuncPtr fxn, UArg arg);
   730
   731        /*!
   732         *  ======== getPeriod ========
   733         *  Get period of instance
   734         *
   735         *  Returns the period of an instance.
   736         *
   737         *  @b(returns)             returns periodic interval in Clock ticks
   738         */
   739        @DirectCall
   740        UInt getPeriod();
   741
   742        /*!
   743         *  ======== getTimeout ========
   744         *  Get timeout of instance
   745         *
   746         *  Returns the remaining time if instance has been started.
   747         *
   748         *  @b(returns)             returns timeout in clock ticks
   749         */
   750        @DirectCall
   751        UInt getTimeout();
   752
   753    internal:
   754
   755        /*!
   756         *  ======== doTick ========
   757         *  Function called by the timer interrupt handler
   758         *
   759         *  @param(arg)     Unused. Required to match signature of Hwi.FuncPtr
   760         */
   761        Void doTick(UArg arg);
   762
   763        /*
   764         *  ======== Instance_State ========
   765         */
   766        struct Instance_State {
   767            Queue.Elem      elem;           // required for clock queue
   768            UInt32          timeout;        // in clock ticks
   769            UInt32          currTimeout;    // working timeout
   770            UInt32          period;         // periodic instance if > 0
   771            volatile Bool   active;         // active/idle flag
   772            FuncPtr         fxn;            // instance function
   773            UArg            arg;            // function arg
   774        };
   775
   776        /*
   777         *  ======== Module_State ========
   778         */
   779        struct Module_State {
   780            volatile UInt32 ticks;          // ticks
   781            UInt            swiCount;       // num of Swi posts before Swi runs
   782            Timer.Handle    timer;          // timer used
   783            Void            (*doTickFunc)(UArg);
   784                                            // points to generated Clock_doTick()
   785            Queue.Object    clockQ;         // clock que
   786            Swi.Handle      swi;            // clock swi
   787            UInt32          periodCounts;   // clock tick period in timer counts
   788            volatile UInt   numTickSkip;    // number of ticks being suppressed
   789            UInt            skipsWorkFunc;  // new skips reg'd during workFunc
   790            Bool            inWorkFunc;     // true if in Clock Swi servicing Q
   791        };
   792    }
   793    /*
   794     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:13; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   795
   796     */
   797


module ti.sysbios.knl.Event

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Event.xdc ========
    34     *
    35     *1                     aren't synced to Semaphore state
    36     *! 04-Mar-2008 agd     Stripped down to support binary only and
    37     *!                     single task.
    38     *! 23-Jan-2008 agd     01/22/08 review changes
    39     *! 13-Dec-2007 agd     Added Event_Id_NONE
    40     *! 10-Dec-2007 connell updated call context table
    41     *! 23-May-2007 agd     Addressed SDSCM00017698
    42     *! 11-May-2007 agd     Addressed SDSCM00016595
    43     *! 16-Apr-2007 cmcc    Added calling context table
    44     *! 01-Feb-2007 rt      Added Log.Events
    45     *! 16-Jan-2007 agd     Moved to ipc package
    46     *! 12-Dec-2006 agd     integrate 12/5/06 code review comments
    47     *! 27-Sep-2006 agd     reworked pre-defined event masks
    48     *! 21-Apr-2006 agd     reworked to support counting Events
    49     *! 02-Mar-2006 agd     redefined default event mask constants
    50     *! 14-Feb-2006 agd     reworked to conform to
    51     *!                     current design requirements
    52     *! 31-Jan-2006 nitya/agd created
    53     */
    54
    55    package ti.sysbios.knl;
    56
    57    import xdc.rov.ViewInfo;
    58
    59    import xdc.runtime.Assert;
    60    import xdc.runtime.Diags;
    61    import xdc.runtime.Log;
    62
    63    import ti.sysbios.knl.Queue;
    64    import ti.sysbios.knl.Clock;
    65    import ti.sysbios.knl.Task;
    66
    67    /*!
    68     *  ======== Event ========
    69     *  Event Manager.
    70     *
    71     *  SYS/BIOS events are a means of communication between Tasks and other
    72     *  threads such as Hwis, Swis, and other Tasks, or between Tasks and
    73     *  other SYS/BIOS objects. Other SYS/BIOS objects include semaphores,
    74     *  mailboxes,
    75     *  message queues, etc. Only tasks can wait for events; whereas tasks,
    76     *  Hwis, Swis, or SYS/BIOS objects can post them.
    77     *
    78     *  In order for a task to be notified of an event from a SYS/BIOS object an
    79     *  event object must first be registered with that object. Separate APIs
    80     *  are provided (in their respective modules) for each of the SYS/BIOS object
    81     *  types that support this feature.
    82     *
    83     *  Events are synchronous in nature, meaning that a receiving task will
    84     *  block or pend while waiting for the events to occur. When the desired
    85     *  events are received, the pending task continues its execution, as it
    86     *  would after a call to Semaphore_pend(), for example.
    87     *
    88     *  Tasks can also wait on events that are not linked to other SYS/BIOS objects.
    89     *  These events are explicitly posted from other threads such as tasks,
    90     *  Swis, or Hwis. A task does not register to receive these events; the
    91     *  sending thread simply posts its event(s) to the event object the task
    92     *  is pending on. This scenario is similar to having an ISR post a
    93     *  semaphore.
    94     *
    95     *  A task can wait on events from multiple resources and/or threads; thus,
    96     *  it can be waiting for a semaphore to be posted and for a message to
    97     *  arrive in a message queue or an ISR thread to signal that an event has
    98     *  occurred.
    99     *
   100     *  Events are binary. Events become available (posted) on each Event_post()
   101     *  of the eventId and become non-available (consumed) on each qualifying
   102     *  Event_pend() mask.
   103     *
   104     *  Unlike Semaphores, only a single task can pend on an Event object.
   105     *
   106     *  {@link #pend} is used to wait for events. The andMask & orMask
   107     *  determine which
   108     *  event(s) must occur before returning from {@link #pend}. The timeout
   109     *  parameter
   110     *  allows the task to wait until a timeout, wait indefinitely, or not wait
   111     *  at all. A return value of zero indicates that a timeout has occurred. A
   112     *  non-zero return value is the set of events that were active at the time
   113     *  the task was unblocked.
   114     *
   115     *  The andMask defines a set of events that must ALL occur to allow
   116     *  {@link #pend} to return.
   117     *
   118     *  The orMask defines a set of events that will cause {@link #pend} to
   119     *  return if ANY of them occur.
   120     *
   121     *  All active events present in the orMask are consumed (ie removed from
   122     *  the event object) upon return from {@link #pend}. Only when all events
   123     *  present in the andMask are active are they consumed on return from
   124     *  {@link #pend}.
   125     *
   126     *  {@link #pend} returns immediately if the andMask OR orMask conditions
   127     *  are true upon entry.
   128     *
   129     *  {@link #post} is used to signal events. If a task is waiting for the event
   130     *  and all of the event conditions are met, {@link #post} unblocks the task.
   131     *  If no task is waiting, {@link #post} simply registers the event with the
   132     *  event object and returns.
   133     *
   134     *  The maximum number of eventIds supported is target specific and depends
   135     *  on the number of bits in a UInt data type.
   136     *  For 6x and ARM devices the maximum number of eventIds is therefore 32.
   137     *  For 28x and MSP430 devices, the maximum number of eventIds is 16.
   138     *
   139     *  @p(html)
   140     *  <h3> Calling Context </h3>
   141     *  <table border="1" cellpadding="3">
   142     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   143     *    </colgroup>
   144     *
   145     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   146     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   147     *    <!--                                                                  -->
   148     *    <tr><td> {@link #create}          </td><td>   N    </td><td>   N    </td>
   149     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   150     *    <tr><td> {@link #Params_init}     </td><td>   Y    </td><td>   Y    </td>
   151     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   152     *    <tr><td> {@link #construct}       </td><td>   N    </td><td>   N    </td>
   153     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   154     *    <tr><td> {@link #delete}          </td><td>   N    </td><td>   N    </td>
   155     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   156     *    <tr><td> {@link #destruct}        </td><td>   N    </td><td>   N    </td>
   157     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   158     *    <tr><td> {@link #getPostedEvents} </td><td>   Y    </td><td>   Y    </td>
   159     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   160     *    <tr><td> {@link #pend}            </td><td>   N    </td><td>   N    </td>
   161     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   162     *    <tr><td> {@link #post}            </td><td>   Y    </td><td>   Y    </td>
   163     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   164     *    <tr><td colspan="6"> Definitions: <br />
   165     *       <ul>
   166     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   167     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   168     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   169     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   170     *           <ul>
   171     *             <li> In your module startup after this module is started
   172     *    (e.g. Event_Module_startupDone() returns TRUE). </li>
   173     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   174     *             <li> During main().</li>
   175     *             <li> During BIOS.startupFxns.</li>
   176     *           </ul>
   177     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   178     *           <ul>
   179     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   180     *             <li> In your module startup before this module is started
   181     *    (e.g. Event_Module_startupDone() returns FALSE).</li>
   182     *           </ul>
   183     *       </ul>
   184     *    </td></tr>
   185     *
   186     *  </table>
   187     *  @p
   188     */
   189
   190    /*
   191     *  To remove Event.Ids not defined for targets with 16 bit Ints
   192     */
   193    @CustomHeader
   194
   195    module Event
   196    {
   197        /*!
   198         *  Pre-defined Event Ids
   199         *
   200         *  Event_Ids are provided to simplify the specification of
   201         *  andMasks and orMasks arguments to {@link #pend Event_pend()}.
   202         *
   203         *  Since each Event_Id is a bitmask composed of only a single bit,
   204         *  a group of Event_Ids within an andMask or orMask can be indicated
   205         *  by simply adding them together. For instance, to indicate that a task
   206         *  is to be awakened only when both Event_Id_00 and Event_Id_01 have
   207         *  been posted, the andMask for Event_pend() would be constructed
   208         *  as below:
   209         *
   210         *  @p(code)
   211         *  Event_pend(event, Event_Id_00+EventId_01, Event_Id_NONE,
   212         *             BIOS_WAIT_FOREVER);
   213         *  @p
   214         *
   215         *  As shown above, Event_Id_NONE is to be used as an empty (NULL)
   216         *  andMask or orMask.
   217         *
   218         *  @a(Note)
   219         *  For targets where a UInt is 32 bits in length,
   220         *  Event_Id_00 thru Event_Id_31 can be used.
   221         *
   222         *  For targets where a UInt is 16 bits in length,
   223         *  Event_Id_00 thru Event_Id_15 can be used.
   224         */
   225
   226        const UInt Id_00 = 0x1;
   227        const UInt Id_01 = 0x2;         /*! @see #Id_00 Pre-defined Event IDs. */
   228        const UInt Id_02 = 0x4;         /*! @see #Id_00 Pre-defined Event IDs. */
   229        const UInt Id_03 = 0x8;         /*! @see #Id_00 Pre-defined Event IDs. */
   230        const UInt Id_04 = 0x10;        /*! @see #Id_00 Pre-defined Event IDs. */
   231        const UInt Id_05 = 0x20;        /*! @see #Id_00 Pre-defined Event IDs. */
   232        const UInt Id_06 = 0x40;        /*! @see #Id_00 Pre-defined Event IDs. */
   233        const UInt Id_07 = 0x80;        /*! @see #Id_00 Pre-defined Event IDs. */
   234        const UInt Id_08 = 0x100;       /*! @see #Id_00 Pre-defined Event IDs. */
   235        const UInt Id_09 = 0x200;       /*! @see #Id_00 Pre-defined Event IDs. */
   236        const UInt Id_10 = 0x400;       /*! @see #Id_00 Pre-defined Event IDs. */
   237        const UInt Id_11 = 0x800;       /*! @see #Id_00 Pre-defined Event IDs. */
   238        const UInt Id_12 = 0x1000;      /*! @see #Id_00 Pre-defined Event IDs. */
   239        const UInt Id_13 = 0x2000;      /*! @see #Id_00 Pre-defined Event IDs. */
   240        const UInt Id_14 = 0x4000;      /*! @see #Id_00 Pre-defined Event IDs. */
   241        const UInt Id_15 = 0x8000;      /*! @see #Id_00 Pre-defined Event IDs. */
   242        const UInt Id_16 = 0x10000;     /*! @see #Id_00 Pre-defined Event IDs. */
   243        const UInt Id_17 = 0x20000;     /*! @see #Id_00 Pre-defined Event IDs. */
   244        const UInt Id_18 = 0x40000;     /*! @see #Id_00 Pre-defined Event IDs. */
   245        const UInt Id_19 = 0x80000;     /*! @see #Id_00 Pre-defined Event IDs. */
   246        const UInt Id_20 = 0x100000;    /*! @see #Id_00 Pre-defined Event IDs. */
   247        const UInt Id_21 = 0x200000;    /*! @see #Id_00 Pre-defined Event IDs. */
   248        const UInt Id_22 = 0x400000;    /*! @see #Id_00 Pre-defined Event IDs. */
   249        const UInt Id_23 = 0x800000;    /*! @see #Id_00 Pre-defined Event IDs. */
   250        const UInt Id_24 = 0x1000000;   /*! @see #Id_00 Pre-defined Event IDs. */
   251        const UInt Id_25 = 0x2000000;   /*! @see #Id_00 Pre-defined Event IDs. */
   252        const UInt Id_26 = 0x4000000;   /*! @see #Id_00 Pre-defined Event IDs. */
   253        const UInt Id_27 = 0x8000000;   /*! @see #Id_00 Pre-defined Event IDs. */
   254        const UInt Id_28 = 0x10000000;  /*! @see #Id_00 Pre-defined Event IDs. */
   255        const UInt Id_29 = 0x20000000;  /*! @see #Id_00 Pre-defined Event IDs. */
   256        const UInt Id_30 = 0x40000000;  /*! @see #Id_00 Pre-defined Event IDs. */
   257        const UInt Id_31 = 0x80000000;  /*! @see #Id_00 Pre-defined Event IDs. */
   258
   259        const UInt Id_NONE = 0;         /*! @see #Id_00 Pre-defined Event IDs. */
   260        /*!
   261         *  ======== BasicView ========
   262         *  @_nodoc
   263         */
   264        metaonly struct BasicView {
   265            String          label;
   266            String          postedEvents;
   267            String          pendedTask;
   268            String          andMask;
   269            String          orMask;
   270            String          timeout;
   271        };
   272
   273        /*!
   274         *  ======== rovViewInfo ========
   275         *  @_nodoc
   276         */
   277        @Facet
   278        metaonly config ViewInfo.Instance rovViewInfo =
   279            ViewInfo.create({
   280                viewMap: [
   281                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',
   282                    structName: 'BasicView'}]
   283                ]
   284            });
   285
   286        // -------- Module Parameters --------
   287
   288        // Logs
   289
   290        /*! Logged on calls to Event_post() */
   291        config Log.Event LM_post = {
   292            mask: Diags.USER1 | Diags.USER2,
   293            msg: "LM_post: event: 0x%x, currEvents: 0x%x, eventId: 0x%x"
   294        };
   295
   296        /*! Logged on calls to Event_pend() */
   297        config Log.Event LM_pend = {
   298            mask: Diags.USER1 | Diags.USER2,
   299            msg: "LM_pend: event: 0x%x, currEvents: 0x%x, andMask: 0x%x, orMask: 0x%x, timeout: %d"
   300        };
   301
   302        // Asserts
   303
   304        /*!
   305         *  Asserted when {@link #pend} is called with andMask and orMask == 0
   306         */
   307        config Assert.Id A_nullEventMasks = {
   308            msg: "A_nullEventMasks: orMask and andMask are null."
   309        };
   310
   311        /*!
   312         *  Asserted when {@link #post} is called with eventId == 0
   313         */
   314        config Assert.Id A_nullEventId = {
   315            msg: "A_nullEventId: posted eventId is null."
   316        };
   317
   318        /*!
   319         *  Asserted when {@link #pend} is called by multiple tasks on the same
   320         *  Event object.
   321         */
   322        config Assert.Id A_eventInUse = {
   323            msg: "A_eventInUse: Event object already in use."
   324        };
   325
   326        /*!
   327         *  Asserted when {@link #pend} is called with non-zero timeout from other
   328         *  than a Task context.
   329         */
   330        config Assert.Id A_badContext = {
   331            msg: "A_badContext: bad calling context. Must be called from a Task."
   332        };
   333
   334    instance:
   335
   336        /*!
   337         *  ======== create ========
   338         *  Create an Event object.
   339         *
   340         *  This function creates a new Event object.
   341         */
   342        @DirectCall
   343        create();
   344
   345        /*!
   346         *  ======== pend ========
   347         *  Wait for events defined in 'and' OR 'or' masks.
   348         *
   349         *  pend() is used to wait for events. The andMask and orMask determine
   350         *  which
   351         *  event(s) must occur before returning from pend(). The timeout parameter
   352         *  allows the task to wait until a timeout, wait indefinitely, or not wait
   353         *  at all. A return value of zero indicates that a timeout has occurred. A
   354         *  non-zero return value is the set of events that were active at the time
   355         *  the task was unblocked.
   356         *
   357         *  The andMask defines a set of events that must
   358         *  ALL occur to allow pend() to return.
   359         *
   360         *  The orMask defines a set of events
   361         *  that will cause pend() to return if ANY of them occur.
   362         *
   363         *  All active events
   364         *  present in the orMask are consumed (i.e. removed from the event object)
   365         *  upon return from pend(). Only when all events present in the andMask
   366         *  are active are they consumed on return from pend().
   367         *
   368         *  The pend conditions are satisfied when either ALL of the events
   369         *  in the andMask occur or ANY of the events in the orMask occur.
   370         *
   371         *  A timeout value of
   372         *  {@link ti.sysbios.BIOS#WAIT_FOREVER, BIOS_WAIT_FOREVER} causes
   373         *  the task to wait indefinitely for matching events to be posted.
   374         *
   375         *  A timeout value of {@link ti.sysbios.BIOS#NO_WAIT, BIOS_NO_WAIT}
   376         *  causes Event_pend to return immediately.
   377         *
   378         *  @param(andMask)         return from pend() when ALL of these
   379         *                          events have occurred
   380         *  @param(orMask)          return from pend() when ANY of these
   381         *                          events have occurred
   382         *  @param(timeout)         return from pend() after this many system
   383         *                          time units
   384         *
   385         *  @b(returns)             All consumed events or zero if timeout.
   386         */
   387        @DirectCall
   388        UInt pend(UInt andMask, UInt orMask, UInt timeout);
   389
   390        /*!
   391         *  ======== post ========
   392         *  Post event(s) to an event object.
   393         *
   394         *  Event_post() is used to signal events. If a task is waiting for the
   395         *  event and the event conditions are met, post() unblocks the
   396         *  task. If no tasks are waiting, post() simply registers the event with
   397         *  the event object and returns.
   398         *
   399         *  @param(eventMask)         mask of eventIds to post (must be non-zero)
   400         */
   401        @DirectCall
   402        Void post(UInt eventMask);
   403
   404        /*!
   405         *  ======== getPostedEvents ========
   406         *  Returns the set of events that have not been consumed by a task
   407         *  (ie those events that have not fully satisfied any pend() conditions).
   408         *  No events are consumed!
   409         *
   410         *  @b(returns)             All un-consumed events posted to the event.
   411         */
   412        @DirectCall
   413        UInt getPostedEvents();
   414
   415        /*!
   416         *  @_nodoc
   417         *  ======== sync ========
   418         *  synchronize an eventId to the value given
   419         *  must call with interrupts disabled
   420         *
   421         *  @param(eventId)         eventId to sync
   422         *  @param(count)           count
   423         */
   424        @DirectCall
   425        Void sync(UInt eventId, UInt count);
   426
   427        /*!
   428         *  @_nodoc
   429         *  ======== syncMeta ========
   430         *  synchronize an eventId to the value given (static version)
   431         *
   432         *  @param(eventId)         eventId to sync
   433         *  @param(count)           count
   434         */
   435        metaonly Void syncMeta(UInt eventId, UInt count);
   436
   437    internal:
   438
   439        /*!
   440         *  ======== pendTimeout ========
   441         *  This function is the clock event handler for pend
   442         */
   443        Void pendTimeout(UArg arg);
   444
   445        /* pendQ Element PendStates */
   446        enum PendState {
   447            PendState_TIMEOUT = 0,          /* Clock timeout */
   448            PendState_POSTED = 1,           /* posted by post */
   449            PendState_CLOCK_WAIT = 2,       /* in Clock queue */
   450            PendState_WAIT_FOREVER = 3      /* not in Clock queue */
   451        };
   452
   453        /* Event pendQ Element */
   454        struct PendElem {
   455            Task.PendElem           tpElem;
   456            PendState               pendState;
   457            UInt                    matchingEvents;
   458            UInt                    andMask;
   459            UInt                    orMask;
   460        };
   461
   462        struct Instance_State {
   463            volatile UInt           postedEvents;   /* Current unconsumed events */
   464            Queue.Object            pendQ;          /* queue of PendElems  */
   465                                                    /* for compatibility with */
   466                                                    /* Semaphore */
   467        };
   468    }
   469    /*
   470     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:14; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   471
   472     */
   473


module ti.sysbios.knl.Idle

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Idle.xdc ========
    34     *
    35     */
    36    package ti.sysbios.knl;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    /*!
    41     *  ======== Idle ========
    42     *  Idle Thread Manager.
    43     *
    44     *  The Idle module is used to specify the list of functions to be called
    45     *  when no other tasks are running in the system.
    46     *
    47     *  If tasking is enabled, then the Task module will create an "Idle task"
    48     *  with the lowest possible priority. When no other tasks are running, this
    49     *  idle task runs in an infinite loop, calling the list of functions
    50     *  specified by the Idle module.
    51     *
    52     *  If tasking is disabled, then the idle functions are called in an infinite
    53     *  loop after main and any Module startup functions.
    54     *
    55     *  The list of idle functions is only statically configurable; it cannot be
    56     *  modified at runtime.
    57     */
    58
    59    module Idle
    60    {
    61        /*! Idle function type definition. */
    62        typedef Void (*FuncPtr)();
    63
    64        metaonly struct ModuleView {
    65            UInt    index;
    66            String  fxn;
    67        }
    68
    69        /*! @_nodoc */
    70        @Facet
    71        metaonly config ViewInfo.Instance rovViewInfo =
    72            xdc.rov.ViewInfo.create({
    73                viewMap: [
    74                    ['Idle.funcList',
    75                        {
    76                            type: ViewInfo.MODULE_DATA,
    77                            viewInitFxn: 'viewInitModule',
    78                            structName: 'ModuleView'
    79                        }
    80                    ]
    81                ]
    82            });
    83
    84        /*!
    85         *  ======== funcList ========
    86         *  @_nodoc
    87         *  The array of functions to be called when no other Tasks are running.
    88         */
    89        config FuncPtr funcList[length] = [];
    90
    91        /*!
    92         *  ======== idleFxns ========
    93         *  Functions to be called when no other Tasks are running
    94         *
    95         *  Functions added to this array are added to the list of
    96         *  functions called by the Idle loop which repeatedly calls
    97         *  @{link #run Idle_run}.
    98         *
    99         *  It is also possible to use @{link #addFunc Idle.addFunc()}
   100         *  to add an idle function.  Both the functions added to idleFxns
   101         *  and those added via Idle.addFunc() will be run by the target's
   102         *  Idle loop.
   103         */
   104        metaonly config FuncPtr idleFxns[length] = [
   105            null, null, null, null,  /* slots for GUI */
   106            null, null, null, null
   107        ];
   108
   109        /*!
   110         *  ======== addFunc ========
   111         *  Statically add a function to the Idle function list.
   112         */
   113        metaonly Void addFunc(FuncPtr func);
   114
   115        /*!
   116         *  ======== loop ========
   117         *  @_nodoc
   118         *  Idle loop which calls the idle functions in an infinite loop.
   119         *
   120         *  This function is called internally and is not normally intended
   121         *  to be called by the client.
   122         *
   123         *  When tasking is enabled, the Task module creates an Idle task which
   124         *  simply calls this function. If tasking is disabled, then this function
   125         *  is called after main and any module startup functions.
   126         *
   127         *  The body of this function is an infinite loop that calls the "run"
   128         *  function.
   129         */
   130        @DirectCall
   131        Void loop(UArg arg1, UArg arg2);
   132
   133        /*!
   134         *  ======== run ========
   135         *  Make one pass through idle functions
   136         *
   137         *  This function is called internally by the Idle task when
   138         *  the Idle task has been enabled in the Task module
   139         *  (see {@link Task#enableIdleTask}).
   140         *
   141         *  This function makes one pass through the array of functions defined
   142         *  in the {@link #funcList Idle.funcList}, calling one function after
   143         *  the next. This function returns after all functions have been
   144         *  executed one time.
   145         *
   146         *  @see Task#enableIdleTask
   147         *  @see Task#allBlockedFunc
   148         */
   149        @DirectCall
   150        Void run();
   151
   152    }
   153    /*
   154     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:15; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   155
   156     */
   157


module ti.sysbios.knl.Mailbox

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Mailbox.xdc ========
    34     *
    35     */
    36    package ti.sysbios.knl;
    37
    38    import xdc.rov.ViewInfo;
    39
    40    import xdc.runtime.IHeap;
    41
    42    /*!
    43     *  ======== Mailbox ========
    44     *  Mailbox Manager
    45     *
    46     *  The Mailbox module makes available a set of functions that manipulate
    47     *  mailbox objects accessed through handles of type Mailbox_Handle.
    48     *
    49     *  {@link #pend()} is used to wait for a message from a mailbox.
    50     *  The timeout parameter to Mailbox_pend allows the task to wait until a
    51     *  timeout specified in terms of system clock ticks.
    52     *  A timeout value of {@link ti.sysbios.BIOS#WAIT_FOREVER BIOS_WAIT_FOREVER}
    53     *  causes the task to wait indefinitely  for a message.
    54     *  A timeout value of {@link ti.sysbios.BIOS#NO_WAIT BIOS_NO_WAIT}
    55     *  causes Mailbox_pend to return immediately.
    56     *  Mailbox_pend's return value indicates whether the mailbox was signaled
    57     *  successfully.
    58     *
    59     *  When a Mailbox has been configured with a {@link #readerEvent} Event
    60     *  object and a task has returned from {@link Event#pend()} with the
    61     *  corresponding {@link #readerEventId}, then BIOS_NO_WAIT
    62     *  should be passed to Mailbox_pend() to retrieve the message.
    63     *
    64     *  NOTE: Since only a single reader can pend on a {@link #readerEvent}
    65     *  Event object,
    66     *  a Mailbox configured with a {@link #readerEvent} Event object does not
    67     *  support multiple readers.
    68     *
    69     *  {@link #post()} is used to send a message to a mailbox.
    70     *  The timeout parameter to Mailbox_post specifies the amount of time the
    71     *  calling task waits if the mailbox is full.
    72     *
    73     *  When a Mailbox has been configured with a {@link #writerEvent} Event
    74     *  object and a task has returned from {@link Event#pend()} with the
    75     *  corresponding {@link #writerEventId}, then BIOS_NO_WAIT
    76     *  should be passed to Mailbox_post() knowing that the message
    77     *  will be successfully posted.
    78     *
    79     *  NOTE: Since only a single writer can pend on a {@link #writerEvent}
    80     *  Event object,
    81     *  a Mailbox configured with a {@link #writerEvent} Event object does not
    82     *  support multiple writers.
    83     *
    84     *  @p(html)
    85     *  <h3> Calling Context </h3>
    86     *  <table border="1" cellpadding="3">
    87     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    88     *    </colgroup>
    89     *
    90     *    <tr><th> Function        </th><th>  Hwi   </th><th>  Swi   </th>
    91     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    92     *    <!--                                                        -->
    93     *    <tr><td> {@link #Params_init}       </td><td>   Y    </td><td>   Y   </td>
    94     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td> {@link #construct}         </td><td>   N    </td><td>   N   </td>
    96     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> {@link #create}            </td><td>   N    </td><td>   N   </td>
    98     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    99     *    <tr><td> {@link #delete}            </td><td>   N    </td><td>   N   </td>
   100     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   101     *    <tr><td> {@link #destruct}          </td><td>   N    </td><td>   N   </td>
   102     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   103     *    <tr><td> {@link #getNumFreeMsgs}    </td><td>   Y    </td><td>   Y   </td>
   104     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   105     *    <tr><td> {@link #getNumPendingMsgs} </td><td>   Y    </td><td>   Y   </td>
   106     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   107     *    <tr><td> {@link #pend}              </td><td>   Y*   </td><td>   Y*  </td>
   108     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   109     *    <tr><td> {@link #post}              </td><td>   Y    </td><td>   Y   </td>
   110     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   111     *    <tr><td colspan="6"> Definitions: <br />
   112     *       <ul>
   113     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   114     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   115     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   116     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   117     *           <ul>
   118     *             <li> In your module startup after this module is started
   119     *    (e.g. Mailbox_Module_startupDone() returns TRUE). </li>
   120     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   121     *             <li> During main().</li>
   122     *             <li> During BIOS.startupFxns.</li>
   123     *           </ul>
   124     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   125     *           <ul>
   126     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   127     *             <li> In your module startup before this module is started
   128     *    (e.g. Mailbox_Module_startupDone() returns FALSE).</li>
   129     *           </ul>
   130     *       <li> <b>*</b>: Yes but only for a timeout value of zero. </li>
   131     *       </ul>
   132     *    </td></tr>
   133     *
   134     *  </table>
   135     *  @p
   136     */
   137
   138    @ModuleStartup     /* Instances require more initialization at startup */
   139    @InstanceFinalize
   140    @InstanceInitError
   141
   142    module Mailbox
   143    {
   144        /*!
   145         *  ======== BasicView ========
   146         *  @_nodoc
   147         */
   148        metaonly struct BasicView {
   149            String label;
   150            SizeT  msgSize;
   151            UInt   numMsgs;
   152        }
   153
   154        /*!
   155         *  ======== DetailedView ========
   156         *  @_nodoc
   157         */
   158        metaonly struct DetailedView {
   159            String label;
   160            SizeT  msgSize;
   161            UInt   numMsgs;
   162            UInt   curNumMsgs;
   163            UInt   freeSlots;
   164            String pendQueue[];
   165            String postQueue[];
   166        }
   167
   168        /*!
   169         *  ======== rovViewInfo ========
   170         *  @_nodoc
   171         */
   172        @Facet
   173        metaonly config ViewInfo.Instance rovViewInfo =
   174            ViewInfo.create({
   175                viewMap: [
   176                [
   177                    'Basic',
   178                    {
   179                        type: ViewInfo.INSTANCE,
   180                        viewInitFxn: 'viewInitBasic',
   181                        structName: 'BasicView'
   182                    }
   183                ],
   184                [
   185                    'Detailed',
   186                    {
   187                        type: ViewInfo.INSTANCE,
   188                        viewInitFxn: 'viewInitDetailed',
   189                        structName: 'DetailedView'
   190                    }
   191                ]
   192                ]
   193            });
   194
   195        /*!
   196         *  ======== MbxElem ========
   197         *  The header used to save each Mailbox message
   198         *
   199         *  Mailbox messages are stored in a queue that requires a header in
   200         *  front of each message.  This structure defines that header and its
   201         *  size must be factored into the total data size requirements for a
   202         *  mailbox instance.
   203         */
   204        struct MbxElem {
   205            Queue.Elem elem;
   206        };
   207
   208        /*!
   209         *  ======== A_invalidBufSize ========
   210         *  Assert raised when the bufSize parameter is too small
   211         *
   212         *  This assert is raised when bufSize is too small to handle
   213         *  (size of messages + sizeof(MbxElem)) * number of messages.
   214         *  See {@link ti.sysbios.knl.MailBox#buf} for more information on the buf
   215         *  parameter.
   216         */
   217        config xdc.runtime.Assert.Id A_invalidBufSize =
   218            {msg: "Mailbox_create's bufSize parameter is invalid (too small)"};
   219
   220    instance:
   221
   222        /*!
   223         *  ======== create ========
   224         *  Create a mailbox
   225         *
   226         *  Mailbox_create creates a mailbox object which is initialized to contain
   227         *  numMsgs messages of size msgSize.
   228         *
   229         *  @param(msgSize)         size of message
   230         *  @param(numMsgs)         length of mailbox
   231         */
   232        @DirectCall
   233        create(SizeT msgSize, UInt numMsgs);
   234
   235        /*!
   236         *  ======== heap ========
   237         *  The IHeap instance used for dynamic creates
   238         *
   239         *  This heap is used only for dynamic instances is ignored  for static
   240         *  instances.
   241         */
   242        config xdc.runtime.IHeap.Handle heap = null;
   243
   244        /*!
   245         *  ======== sectionName ========
   246         *  Section name for the buffer managed by the instance
   247         *
   248         *  The default section is the 'dataSection' in the platform.
   249         */
   250        metaonly config String sectionName = null;
   251
   252        /*!
   253         *  ======== readerEvent ========
   254         *  Mailbox not empty event if using Events. Default is null
   255         *
   256         *  Posted whenever a mailbox is written to.
   257         *  Reader task pends on this event.
   258         *  Note that {@link ti.sysbios.knl.Semaphore#supportsEvents
   259         *  Semaphore.supportsEvents} has to be
   260         *  set to true for Mailbox to support Events.
   261         */
   262        config Event.Handle readerEvent = null;
   263
   264        /*!
   265         *  ======== readerEventId ========
   266         *  Mailbox not empty event Id if using Events. Default is 1
   267         *
   268         *  Posted whenever a mailbox is written to.
   269         *  Reader task pends on this eventId.
   270         *  Note that {@link ti.sysbios.knl.Semaphore#supportsEvents
   271         *  Semaphore.supportsEvents} has to be
   272         *  set to true for Mailbox to support Events.
   273         */
   274        config UInt readerEventId = 1;
   275
   276        /*!
   277         *  ======== writerEvent ========
   278         *  Mailbox not full event if using Events. Default is null
   279         *
   280         *  Posted whenever a mailbox is read from.
   281         *  Writer task pends on this event.
   282         *  Note that {@link ti.sysbios.knl.Semaphore#supportsEvents
   283         *  Semaphore.supportsEvents} has to be
   284         *  set to true for Mailbox to support Events.
   285         */
   286        config Event.Handle writerEvent = null;
   287
   288        /*!
   289         *  ======== writerEventId ========
   290         *  Mailbox not full event Id if using Events
   291         *
   292         *  Posted whenever a mailbox is read from.
   293         *  Writer task pends on this eventId.
   294         *  Note that {@link ti.sysbios.knl.Semaphore#supportsEvents
   295         *  Semaphore.supportsEvents} has to be
   296         *  set to true for Mailbox to support Events.
   297         */
   298        config UInt writerEventId = 1;
   299
   300        /*!
   301         *  ======== buf ========
   302         *  The address of the buffer used for creating messages
   303         *
   304         *  This property is only used for dynamically created Mailboxes.
   305         *  If set to 'null', the messages will be allocated from the heap
   306         *  during runtime, otherwise the user may set this to a buffer of their
   307         *  creation to be used for allocating the messages.
   308         *
   309         *  The module will split the buf into
   310         *  {@link ti.sysbios.knl.Mailbox#numMsgs} number of blocks (one block per
   311         *  Mailbox message).
   312         *
   313         *  Please note that if the buffer is user supplied, then it is the user's
   314         *  responsibility to ensure that it is aligned properly and is also large
   315         *  enough to contain {@link ti.sysbios.knl.Mailbox#numMsgs} number of
   316         *  blocks.  The size of each block is defined as follows:
   317         *  @p(code)
   318         *      sizeof(Mailbox_MbxElem) + msgSize
   319         *  @p
   320         *
   321         *  Since the buffer must be a aligned properly, it may be necessary to
   322         *  'round up' the total size of the buffer to the next multiple of the
   323         *  alignment for odd sized messages.
   324         *
   325         *  @see #MbxElem
   326         */
   327        config Ptr buf = null;
   328
   329        /*!
   330         *  ======== bufSize ========
   331         *  The size of the buffer that 'buf' references
   332         *
   333         *  This property is only used for dynamically created Mailboxes.
   334         */
   335        config UInt bufSize = 0;
   336
   337        /*!
   338         *  ======== getNumFreeMsgs ========
   339         *  Get the number messages available for use
   340         */
   341        @DirectCall
   342        Int getNumFreeMsgs();
   343
   344        /*!
   345         *  ======== getNumPendingMsgs ========
   346         *  Get the number of messages that are ready to be read
   347         */
   348        @DirectCall
   349        Int getNumPendingMsgs();
   350
   351        /*!
   352         *  ======== pend ========
   353         *  Wait for a message from mailbox
   354         *
   355         *  If the mailbox is not empty, Mailbox_pend copies the first message into
   356         *  msg and returns TRUE. Otherwise, Mailbox_pend suspends the execution of
   357         *  the current task until Mailbox_post is called or the timeout expires.
   358         *
   359         *  A timeout value of
   360         *  {@link ti.sysbios.BIOS#WAIT_FOREVER, BIOS_WAIT_FOREVER} causes
   361         *  the task to wait indefinitely  for a message.
   362         *
   363         *  A timeout value of {@link ti.sysbios.BIOS#NO_WAIT, BIOS_NO_WAIT}
   364         *  causes Mailbox_pend to return immediately.
   365         *
   366         *  The timeout value of {@link ti.sysbios.BIOS#NO_WAIT, BIOS_NO_WAIT}
   367         *  should be passed to Mailbox_pend() to retrieve a message after
   368         *  Event_pend() is called outside of Mailbox_pend to wait on an incoming
   369         *  message.
   370         *
   371         *  Mailbox_pend's return value indicates whether the mailbox was signaled
   372         *  successfully.
   373         *
   374         *  @param(msg)     message pointer
   375         *  @param(timeout) maximum duration in system clock ticks
   376         *  @b(returns)     TRUE if successful, FALSE if timeout
   377         */
   378        @DirectCall
   379        Bool pend(Ptr msg, UInt timeout);
   380
   381        /*!
   382         *  ======== post ========
   383         *  Post a message to mailbox
   384         *
   385         *  Mailbox_post checks to see if there are any free message slots before
   386         *  copying msg into the mailbox. Mailbox_post readies the first task
   387         *  (if any) waiting on the mailbox. If the mailbox is full and a timeout
   388         *  is specified  the task remains suspended until Mailbox_pend is called
   389         *  or the timeout expires.
   390         *
   391         *  A timeout value of
   392         *  {@link ti.sysbios.BIOS#WAIT_FOREVER, BIOS_WAIT_FOREVER} causes
   393         *  the task to wait indefinitely for a free slot.
   394         *
   395         *  A timeout value of {@link ti.sysbios.BIOS#NO_WAIT, BIOS_NO_WAIT}
   396         *  causes  Mailbox_post to return immediately.
   397         *
   398         *  The timeout value of {@link ti.sysbios.BIOS#NO_WAIT, BIOS_NO_WAIT}
   399         *  should be passed to Mailbox_post() to post a message after
   400         *  Event_pend() is called outside of Mailbox_post to wait on an
   401         *  available message buffer.
   402         *
   403         *  Mailbox_post's return value indicates whether the msg was
   404         *  copied or not.
   405         *
   406         *  @param(msg)     message pointer
   407         *  @param(timeout) maximum duration in system clock ticks
   408         *  @b(returns)     TRUE if successful, FALSE if timeout
   409         */
   410        @DirectCall
   411        Bool post(Ptr msg, UInt timeout);
   412
   413    internal:
   414
   415        Void cleanQue(Queue.Handle obj);
   416
   417        /*
   418         *  ======== postInit ========
   419         *  finish initializing static and dynamic instances
   420         */
   421        Int postInit(Object *obj, SizeT blockSize);
   422
   423        /* -------- Internal Structures -------- */
   424        struct Instance_State {
   425            xdc.runtime.IHeap.Handle    heap;
   426            SizeT                       msgSize;
   427            UInt                        numMsgs;
   428            Ptr                         buf;
   429            Queue.Object                dataQue;
   430            Queue.Object                freeQue;
   431            Semaphore.Object            dataSem;
   432            Semaphore.Object            freeSem;
   433            UInt                        numFreeMsgs;
   434            Char                        allocBuf[];
   435        };
   436    }
   437    /*
   438     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:15; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   439
   440     */
   441


package ti.sysbios.knl

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38    requires ti.sysbios.family;
    39
    40    /*!
    41     *  ======== ti.sysbios.knl ========
    42     *  Contains core threading modules for the SYS/BIOS kernel.
    43     *
    44     *  Many real-time applications must perform a number of functions at the
    45     *  same time, often in response to external events such as the availability of
    46     *  data or the presence of a control signal. Both the functions and `when`
    47     *  they are performed are important.
    48     *
    49     *  Such functions are called "threads". Within SYS/BIOS, the term is defined
    50     *  broadly to include any independent stream of instructions executed by the
    51     *  processor. A thread is a single point of control that can activate a
    52     *  function call or an interrupt service routine (ISR).
    53     *
    54     *  SYS/BIOS enables your applications to be structured as a collection of
    55     *  threads. Multithreaded programs allow higher-priority threads to preempt
    56     *  lower-priority threads and allow various types of interaction between
    57     *  threads, including blocking, communication, and synchronization.
    58     *
    59     *  SYS/BIOS provides support for several types of threads with different
    60     *  priorities. Each thread type has different execution and preemption
    61     *  characteristics. The thread types (from highest to lowest priority) are:
    62     *
    63     *  @p(blist)
    64     *  - Hardware interrupts ({@link ti.sysbios.hal.Hwi}), which includes
    65     *    {@link ti.sysbios.hal.Timer} functions
    66     *  - Software interrupts ({@link ti.sysbios.knl.Swi}), which includes
    67     *    {@link ti.sysbios.knl.Clock} functions
    68     *  - Tasks ({@link ti.sysbios.knl.Task})
    69     *  - Background thread ({@link ti.sysbios.knl.Idle})
    70     *  @p
    71     *
    72     *  The ti.sysbios.knl package also provides several modules for
    73     *  synchronizing threads.
    74     *
    75     *  @p(blist)
    76     *  - Semaphores ({@link ti.sysbios.knl.Semaphore}) are often used to
    77     *    coordinate access to a shared resource
    78     *    among a set of competing tasks. Semaphores can be used for task
    79     *    synchronization and mutual exclusion. Semaphore objects can be declared
    80     *    as either counting or binary semaphores. The same APIs are used for
    81     *    both counting and binary semaphores.
    82     *  - Events ({@link ti.sysbios.knl.Event}) provide a means for
    83     *    communicating between and synchronizing
    84     *    threads. They are similar to Semaphores, except that they allow you
    85     *    to specify multiple conditions ("events") that must occur before the
    86     *    waiting thread returns.
    87     *  - Mailboxes ({@link ti.sysbios.knl.Mailbox}) can be used to pass buffers
    88     *    from one thread to another.
    89     *    A Mailbox instance can be used by multiple readers and writers.
    90     *  @p
    91     *
    92     *  In addition to Semaphores, Events, and Mailboxes, you can use
    93     *  Gates to prevent concurrent accesses to critical regions of code.
    94     *  The {@link xdc.runtime.Gate} module is provided by XDCtools, but
    95     *  SYS/BIOS
    96     *  provides some additional implementations in {@link ti.sysbios.gates}.
    97     */
    98    package ti.sysbios.knl [2,0,0,0] {
    99        module Clock;
   100        module Idle;
   101        module Intrinsics;
   102        module Event;     // Must be before Semaphore!!!
   103        module Mailbox;
   104        module Queue;
   105        module Semaphore;
   106        module Swi;
   107        module Task;
   108    }
   109    /*
   110     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:17; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   111
   112     */
   113


module ti.sysbios.knl.Semaphore

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Semaphore.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.knl;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43    import xdc.runtime.Assert;
    44
    45    import ti.sysbios.knl.Queue;
    46    import ti.sysbios.knl.Task;
    47    import ti.sysbios.knl.Clock;
    48
    49    /*!
    50     *  ======== Semaphore ========
    51     *  Semaphore Manager
    52     *
    53     *  The Semaphore manager makes available a set of functions that manipulate
    54     *  semaphore objects. Semaphores can be used for task synchronization and
    55     *  mutual exclusion.
    56     *
    57     *  Semaphores can be counting semaphores or binary semaphores. Counting
    58     *  semaphores keep track of the number of times the semaphore has been posted
    59     *  with post(). This is useful, for example, if you have a group of resources
    60     *  that are shared between tasks. Such tasks might call pend() to see if a
    61     *  resource is available before using one.
    62     *
    63     *  Binary semaphores can have only two states: available (count = 1) and
    64     *  unavailable (count = 0). They can be used to share a single resource
    65     *  between
    66     *  tasks. They can also be used for a basic signaling mechanism, where the
    67     *  semaphore can be posted multiple times. Binary semaphores do not keep track
    68     *  of the count; they simply track whether the semaphore has been posted
    69     *  or not.
    70     *
    71     *  The Mailbox module uses a counting semaphore internally to manage the
    72     *  count of free (or full) mailbox elements. Another example of a counting
    73     *  semaphore is an ISR that might fill multiple buffers of data for
    74     *  consumption by a task. After filling each buffer, the ISR puts the buffer on
    75     *  a queue and calls post(). The task waiting for the data calls pend(), which
    76     *  simply decrements the semaphore count and returns or blocks if the count is
    77     *  0. The semaphore count thus tracks the number of full buffers available for
    78     *  the task.
    79     *
    80     *  pend() is used to wait for a semaphore. The timeout parameter allows the
    81     *  task to wait until a timeout, wait indefinitely, or not wait at all. The
    82     *  return value is used to indicate if the semaphore was signaled successfully.
    83     *
    84     *  post() is used to signal a semaphore. If a task is waiting for the
    85     *  semaphore, post() removes the task from the semaphore queue and puts it on
    86     *  the ready queue. If no tasks are waiting, post() simply increments the
    87     *  semaphore count and returns.  For a binary semaphore the count is always
    88     *  set to one.
    89     *
    90     *  @p(html)
    91     *  <h3> Calling Context </h3>
    92     *  <table border="1" cellpadding="3">
    93     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    94     *    </colgroup>
    95     *
    96     *    <tr><th> Function               </th><th>  Hwi   </th><th>  Swi   </th>
    97     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    98     *    <!--                                                                  -->
    99     *    <tr><td> {@link #Params_init}   </td><td>   Y    </td><td>   Y    </td>
   100     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   101     *    <tr><td> {@link #construct}     </td><td>   N    </td><td>   N    </td>
   102     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   103     *    <tr><td> {@link #create}        </td><td>   N    </td><td>   N    </td>
   104     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   105     *    <tr><td> {@link #delete}        </td><td>   N    </td><td>   N    </td>
   106     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   107     *    <tr><td> {@link #destruct}      </td><td>   N    </td><td>   N    </td>
   108     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   109     *    <tr><td> {@link #getCount}      </td><td>   Y    </td><td>   Y    </td>
   110     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   111     *    <tr><td> {@link #pend}          </td><td>   N    </td><td>   N    </td>
   112     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   113     *    <tr><td> {@link #post}          </td><td>   Y    </td><td>   Y    </td>
   114     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   115     *    <tr><td> {@link #registerEvent} </td><td>   N    </td><td>   N    </td>
   116     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   117     *    <tr><td> {@link #reset}         </td><td>   N    </td><td>   N    </td>
   118     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   119     *    <tr><td colspan="6"> Definitions: <br />
   120     *       <ul>
   121     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   122     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   123     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   124     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   125     *           <ul>
   126     *             <li> In your module startup after this module is started
   127     *    (e.g. Semaphore_Module_startupDone() returns TRUE). </li>
   128     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   129     *             <li> During main().</li>
   130     *             <li> During BIOS.startupFxns.</li>
   131     *           </ul>
   132     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   133     *           <ul>
   134     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   135     *             <li> In your module startup before this module is started
   136     *    (e.g. Semaphore_Module_startupDone() returns FALSE).</li>
   137     *           </ul>
   138     *       </ul>
   139     *    </td></tr>
   140     *
   141     *  </table>
   142     *  @p
   143     */
   144
   145    @InstanceFinalize       /* to destruct queue */
   146
   147    module Semaphore
   148    {
   149        /*! Types of semaphores. */
   150        enum Mode {
   151            Mode_COUNTING,  /*! Counting semaphore. */
   152            Mode_BINARY     /*! Binary Semaphore. */
   153        };
   154
   155        /*!
   156         *  ======== BasicView ========
   157         *  @_nodoc
   158         */
   159        metaonly struct BasicView {
   160            String          label;
   161            String          event;
   162            String          eventId;
   163            String          mode;
   164            Int             count;
   165            String          pendedTasks[];
   166        };
   167
   168        /*!
   169         *  ======== rovViewInfo ========
   170         *  @_nodoc
   171         */
   172        @Facet
   173        metaonly config ViewInfo.Instance rovViewInfo =
   174            ViewInfo.create({
   175                viewMap: [
   176                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}]
   177                ]
   178            });
   179
   180        // -------- Module Parameters --------
   181
   182        /*!
   183         *  ======== LM_post ========
   184         *  Logged on calls to Semaphore_post()
   185         */
   186        config Log.Event LM_post = {
   187            mask: Diags.USER1 | Diags.USER2,
   188            msg: "LM_post: sem: 0x%x, count: %d"
   189        };
   190
   191        /*!
   192         *  ======== LM_pend ========
   193         *  Logged on calls to Semaphore_pend()
   194         */
   195        config Log.Event LM_pend = {
   196            mask: Diags.USER1 | Diags.USER2,
   197            msg: "LM_pend: sem: 0x%x, count: %d, timeout: %d"
   198        };
   199
   200        /*!
   201         *  ======== A_noEvents ========
   202         *  Assert raised if application uses Event but it's not supported
   203         *
   204         *  This assertion is triggered by {@link #create} if
   205         *  {@link #supportsEvents} is false and an {@link ti.sysbios.knl.Event}
   206         *  object is passed to {@link #create}.
   207         */
   208        config Assert.Id A_noEvents = {
   209            msg: "A_noEvents: The Event.supportsEvents flag is disabled."
   210        };
   211
   212        /*!
   213         *  ======== A_invTimeout ========
   214         *  @_nodoc
   215         *  This assertion is no longer used
   216         */
   217        config Assert.Id A_invTimeout = {
   218            msg: "A_invTimeout: Can't use BIOS_EVENT_ACQUIRED with this Semaphore."
   219        };
   220
   221        /*!
   222         *  ======== A_badContext ========
   223         *  Assert raised if an operation is invalid in the current calling context
   224         *
   225         *  Asserted when {@link #pend} is called with non-zero timeout from
   226         *  other than a Task context.
   227         */
   228        config Assert.Id A_badContext = {
   229            msg: "A_badContext: bad calling context. Must be called from a Task."
   230        };
   231
   232        /*!
   233         *  ======== supportsEvents ========
   234         *  Support Semaphores with Events?
   235         *
   236         *  The default for this parameter is false.
   237         */
   238        config Bool supportsEvents = false;
   239
   240    instance:
   241
   242        /*!
   243         *  ======== create ========
   244         *  Create a Semaphore object
   245         *
   246         *  This function creates a new Semaphore object which is initialized to
   247         *  count.
   248         *
   249         *  @param(count)   initial semaphore count
   250         */
   251        @DirectCall
   252        create(Int count);
   253
   254        /*!
   255         *  ======== event ========
   256         *  Event instance to use if non-NULL
   257         *
   258         *  The default value of this parameter is null.  If event is non-null:
   259         *  @p(blist)
   260         *      - Event_post(sem->event, sem->eventId) will be invoked when
   261         *        Semaphore_post() is called.
   262         *
   263         *      - Event_pend(sem->event, 0, sem->eventId, timeout) will be
   264         *        invoked when Semaphore_pend() is called.
   265         *  @p
   266         */
   267        config Event.Handle event = null;
   268
   269        /*!
   270         *  ======== eventId ========
   271         *  eventId if using Events
   272         *
   273         *  The default for this parameters is 1.
   274         */
   275        config UInt eventId = 1;
   276
   277        /*!
   278         *  ======== mode ========
   279         *  Semaphore mode
   280         *
   281         *  When mode is BINARY, the semaphore has only two states, available
   282         *  and unavailable. When mode is COUNTING, the semaphore keeps track of
   283         *  number of times a semaphore is posted.
   284         *
   285         *  The default for this parameter is COUNTING.
   286         */
   287        config Mode mode = Mode_COUNTING;
   288
   289        /*!
   290         *  ======== getCount ========
   291         *  Get current semaphore count
   292         *
   293         *  This function returns the current value of the semaphore specified by
   294         *  the handle.
   295         *
   296         *  @b(returns)             current semaphore count
   297         */
   298        @DirectCall
   299        Int getCount();
   300
   301        /*!
   302         *  ======== pend ========
   303         *  Wait for a semaphore
   304         *
   305         *  If the semaphore count is greater than zero (available), this function
   306         *  decrements the count and returns TRUE. If the semaphore count is zero
   307         *  (unavailable), this function suspends execution of the current task
   308         *  until post() is called or the timeout expires.
   309         *
   310         *  A timeout value of
   311         *  {@link ti.sysbios.BIOS#WAIT_FOREVER BIOS_WAIT_FOREVER} causes
   312         *  the task to wait indefinitely for its semaphore to be posted.
   313         *
   314         *  A timeout value of {@link ti.sysbios.BIOS#NO_WAIT BIOS_NO_WAIT}
   315         *  causes Semaphore_pend to return immediately.
   316         *
   317         *  @param(timeout)     return after this many system time units
   318         *
   319         *  @b(returns)         TRUE if successful, FALSE if timeout
   320         */
   321        @DirectCall
   322        Bool pend(UInt timeout);
   323
   324        /*!
   325         *  ======== post ========
   326         *  Signal a semaphore.
   327         *
   328         *  Readies the first task waiting for the semaphore. If no task is
   329         *  waiting, this function simply increments the semaphore count and
   330         *  returns.  In the case of a binary semaphore, the count has a
   331         *  maximum value of one.
   332         */
   333        @DirectCall
   334        Void post();
   335
   336        /*!
   337         *  ======== registerEvent ========
   338         *  Register an Event Object with a semaphore
   339         *
   340         *  Ordinarily, an Event object and eventId are configured at
   341         *  Semaphore create time.
   342         *
   343         *  This API is provided so that Semaphore-using middleware
   344         *  can support implicit Event posting without having to be
   345         *  retrofitted.
   346         *
   347         *  After the Event object and eventId are registered with the
   348         *  Semaphore:
   349
   350         *  Event_post(event, eventId) will be invoked when
   351         *  Semaphore_post(sem) is called.
   352         *
   353         *  Event_pend(event, eventId, 0, timeout) will be invoked when
   354         *  Semaphore_pend(sem, timeout) is called.
   355         *
   356         *  @param(event)                     Ptr to Event Object
   357         *  @param(eventId)                   Event ID
   358         *
   359         */
   360        @DirectCall
   361        Void registerEvent(Event.Handle event, UInt eventId);
   362
   363        /*!
   364         *  ======== reset ========
   365         *  Reset semaphore count
   366         *
   367         *  Resets the semaphore count to count.
   368         *  No task switch occurs when calling SEM_reset.
   369         *
   370         *  @a(constraints)
   371         *  count must be greater than or equal to 0.
   372         *
   373         *  No tasks should be waiting on the semaphore when
   374         *  Semaphore_reset is called.
   375         *
   376         *  Semaphore_reset cannot be called by a Hwi or a Swi.
   377         *
   378         *  @param(count)                   semaphore count
   379         *
   380         */
   381        @DirectCall
   382        Void reset(Int count);
   383
   384    internal:
   385
   386        /*
   387         * Event module function pointers. Used to decouple
   388         * Semaphore from Event when supportsEvents is false
   389         */
   390        config Void (*eventPost)(Event.Handle, UInt);
   391
   392        config Void (*eventSync)(Event.Handle, UInt, UInt);
   393
   394        /*!
   395         *  ======== pendTimeout ========
   396         *  This function is the clock event handler for pend
   397         */
   398        Void pendTimeout(UArg arg);
   399
   400        /* pendQ Element PendStates */
   401        enum PendState {
   402            PendState_TIMEOUT = 0,          /* Clock timeout */
   403            PendState_POSTED = 1,           /* posted by post */
   404            PendState_CLOCK_WAIT = 2,       /* in Clock queue */
   405            PendState_WAIT_FOREVER = 3      /* not in Clock queue */
   406        };
   407
   408        /* Semaphore pendQ Element */
   409        struct PendElem {
   410            Task.PendElem           tpElem;
   411            PendState               pendState;
   412        };
   413
   414        struct Instance_State {
   415            Event.Handle            event;
   416            UInt                    eventId;
   417            Mode                    mode;   /* binary or counting */
   418            volatile UInt16         count;  /* curr semaphore count */
   419            Queue.Object            pendQ;  /* queue of PendElems */
   420        };
   421    }
   422    /*
   423     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:15; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   424
   425     */
   426


module ti.sysbios.knl.Swi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Swi.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.knl;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Error;
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Diags;
    44    import xdc.runtime.Log;
    45
    46    import ti.sysbios.knl.Queue;
    47
    48    /*!
    49     *  ======== Swi ========
    50     *  Software Interrupt Manager
    51     *
    52     *  The Swi module manages software interrupt service routines, which are
    53     *  patterned after hardware interrupt service routines.
    54
    55     *  SYS/BIOS manages four distinct levels of execution threads: hardware
    56     *  interrupt service routines, software interrupt routines, tasks, and
    57     *  background idle functions. A software interrupt is an object that
    58     *  encapsulates a function to be executed and a priority.
    59     *  Software interrupts are prioritized, preempt tasks, and are preempted
    60     *  by hardware interrupt service routines.
    61     *
    62     *  Each software interrupt has a priority level. A software interrupt
    63     *  preempts any lower-priority software interrupt currently executing.
    64     *
    65     *  A target program uses an API call to post a Swi object. This causes the
    66     *  Swi module to schedule execution of the software interrupt's function.
    67     *  When a Swi is posted by an API call, the Swi object's function is not
    68     *  executed immediately. Instead, the function is scheduled for execution.
    69     *  SYS/BIOS uses the Swi's priority to determine whether to preempt the
    70     *  thread currently running. Note that if a Swi is posted several times
    71     *  before it begins running, (because Hwis and higher priority interrupts
    72     *  are running,) when the Swi does eventually run, it will run only one time.
    73     *
    74     *  Software interrupts can be posted for execution with a call to
    75     *  {@link #post} or a number of other Swi functions. Each Swi object has a
    76     *  "trigger" which is used either to determine whether to post the Swi or as
    77     *  a value that can be evaluated within the Swi's function. {@link #andn} and
    78     *  {@link #dec} post the Swi if the trigger value transitions to 0.
    79     *  {@link #or} and {@link #inc} also modify the trigger value. ({@link #or}
    80     *  sets bits, and {@link #andn} clears bits.)
    81     *
    82     *  The {@link #disable} and {@link #restore} operations allow you to
    83     *  post several
    84     *  Swis and enable them all for execution at the same time. The Swi
    85     *  priorities then determine which Swi runs first.
    86     *
    87     *  All Swis run to completion; you cannot suspend a Swi while it waits for
    88     *  something (for example, a device) to be ready. So, you can use the
    89     *  trigger to tell the Swi when all the devices and other conditions it
    90     *  relies on are ready. Within a Swi processing function, a call to
    91     *  Swi_getTrigger returns the value of the trigger when the Swi started
    92     *  running.
    93     *  Note that the trigger is automatically reset to its original value
    94     *  when a Swi runs; however, {@link #getTrigger} will return the saved
    95     *  trigger
    96     *  value from when the Swi started execution.
    97     *
    98     *  All Swis run with interrupts globally enabled (ie GIE = 1).
    99     *  Therefore, any Swi module API that results in a
   100     *  Swi being made ready to run (ie {@link #post}, {@link #inc},
   101     *  {@link #andn}, {@link #or}, {@link #restore}, or {@link #enable})
   102     *  will subsequently also cause interrupts to be enabled while the
   103     *  Swi function executes. Upon return from the Swi function,
   104     *  global interrupts are restored to their previous enabled/disabled
   105     *  state.
   106     *
   107     *  A Swi preempts any currently running Swi with a lower priority.
   108     *  When multiple Swis of the same priority level have been posted,
   109     *  their respective Swi functions are executed in the order the Swis
   110     *  were posted.
   111     *  Hwis in turn preempt any currently running Swi,
   112     *  allowing the target to respond quickly to hardware peripherals.
   113     *
   114     *  Swi threads are executed using the ISR (or "Hwi") stack. Thus
   115     *  they share the ISR stack with Hwi threads.
   116     *
   117     *  {@link #disable} also disables the Task scheduler.
   118     *  Therefore, Task pre-emption and blocking is disabled while
   119     *  the Swi scheduler is disabled.
   120     *  {@link #restore} will re-enable and invoke the Task
   121     *  scheduler if the Task scheduler was not disabled prior
   122     *  to invoking {@link #disable}.
   123     *  The currently ready highest priority task will be immediately
   124     *  switched to or continue to run when the lowest order {@link #restore}
   125     *  invocation re-enables the Swi scheduler.
   126     *
   127     *  In the following example, the newly created task is not switched to
   128     *  until after the Swi_restore() call since Task scheduling is disabled
   129     *  while Swi scheduling is disabled:
   130     *
   131     *  @p(code)
   132     *  key = Swi_disable();
   133     *  // create a task of higher priority than the current task thread
   134     *  myTaskParams.priority = Task_getPri(Task_self()) + 1;
   135     *  myTask = Task_create(myTaskFunc, &myTaskParams, NULL);
   136     *  Swi_restore(key);
   137     *  @p
   138     *
   139     *  @p(html)
   140     *  <a name="hookfunc"></a>
   141     *  @p
   142     *
   143     *  @a(Hook Functions)
   144     *
   145     *  Sets of hook functions can be specified for the Swi module.  Each set
   146     *  contains these hook functions:
   147     *  @p(blist)
   148     *  -Register:  A function called before all statically-created Swis
   149     *      are initialized at runtime.
   150     *  -Create:    A function that is called when a Swi is created.
   151     *      This includes Swis that are created statically and those
   152     *      created dynamically using {@link #create}.
   153     *  -Ready:     A function that is called when any Swi becomes ready
   154     *      to run.
   155     *  -Begin:     A function that is called just prior to running a Swi.
   156     *  -End:       A function that is called just after a Swi finishes.
   157     *  -Delete:    A function that is called when a Swi is deleted at
   158     *      run-time with {@link #delete}.
   159     *  @p
   160     *  Hook functions can only be configured statically.
   161     *
   162     *  If you define more than one set of hook functions, all the functions
   163     *  of a particular type will be run when a Swi triggers that type of
   164     *  hook.
   165     *
   166     *  @p(html)
   167     *  <B>Register Function</B>
   168     *  @p
   169     *
   170     *  The Register function is provided to allow a hook set to store its
   171     *  hookset ID.  This id can be passed to {@link #setHookContext} and
   172     *  {@link #getHookContext} to set or get hookset-specific context.  The
   173     *  Register function must be specified if the hook implementation
   174     *  needs to use {@link #setHookContext} or {@link #getHookContext}.
   175     *  The registerFxn hook function is called during system initialization
   176     *  before interrupts have been enabled.
   177     *
   178     *  @p(code)
   179     *  Void myRegisterFxn(Int id);
   180     *  @p
   181     *
   182     *  @p(html)
   183     *  <B>Create and Delete Functions</B>
   184     *  @p
   185     *
   186     *  The create and delete functions are called whenever a Swi is created
   187     *  or deleted.  They are called with interrupts enabled (unless called
   188     *  at boot time or from main()).
   189     *
   190     *  @p(code)
   191     *  Void myCreateFxn(Swi_Handle swi, Error_Block *eb);
   192     *  @p
   193     *
   194     *  @p(code)
   195     *  Void myDeleteFxn(Swi_Handle swi);
   196     *  @p
   197     *
   198     *  @p(html)
   199     *  <B>Ready, Begin, and End Functions</B>
   200     *  @p
   201     *
   202     *  The ready, begin and end functions are all called with interrupts
   203     *  enabled.  The ready function is called when a Swi is posted and made
   204     *  ready to run.  The begin function is called right before the function
   205     *  associated with the given Swi is run.  The end function is called
   206     *  right after this function returns.
   207     *
   208     *  @p(code)
   209     *  Void myReady(Swi_Handle swi);
   210     *  @p
   211     *
   212     *  @p(code)
   213     *  Void myBegin(Swi_Handle swi);
   214     *  @p
   215     *
   216     *  @p(code)
   217     *  Void myEnd(Swi_Handle swi);
   218     *  @p
   219     *
   220     *  @p(html)
   221     *  <h3> Calling Context </h3>
   222     *  <table border="1" cellpadding="3">
   223     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   224     *  </colgroup>
   225     *
   226     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   227     *  <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   228     *    <!--                                             -->
   229     *    <tr><td> {@link #create}          </td><td>   N    </td><td>   N    </td>
   230     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   231     *    <tr><td> {@link #disable}         </td><td>   Y    </td><td>   Y    </td>
   232     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   233     *    <tr><td> {@link #getTrigger}      </td><td>   Y    </td><td>   Y    </td>
   234     *  <td>   N    </td><td>   N    </td><td>   N    </td></tr>
   235     *    <tr><td> {@link #Params_init}     </td><td>   Y    </td><td>   Y    </td>
   236     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   237     *    <tr><td> {@link #restore}         </td><td>   Y    </td><td>   Y    </td>
   238     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   239     *    <tr><td> {@link #self}            </td><td>   Y    </td><td>   Y    </td>
   240     *  <td>   N    </td><td>   N    </td><td>   N    </td></tr>
   241     *
   242     *    <tr><td> {@link #andn}            </td><td>   Y    </td><td>   Y    </td>
   243     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   244     *    <tr><td> {@link #construct}       </td><td>   N    </td><td>   N    </td>
   245     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   246     *    <tr><td> {@link #dec}             </td><td>   Y    </td><td>   Y    </td>
   247     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   248     *    <tr><td> {@link #delete}          </td><td>   N    </td><td>   N    </td>
   249     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   250     *    <tr><td> {@link #destruct}        </td><td>   N    </td><td>   N    </td>
   251     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   252     *    <tr><td> {@link #getHookContext}  </td><td>   Y    </td><td>   Y    </td>
   253     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   254     *    <tr><td> {@link #getPri}          </td><td>   Y    </td><td>   Y    </td>
   255     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   256     *    <tr><td> {@link #getFunc}         </td><td>   Y    </td><td>   Y    </td>
   257     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   258     *    <tr><td> {@link #inc}             </td><td>   Y    </td><td>   Y    </td>
   259     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   260     *    <tr><td> {@link #or}              </td><td>   Y    </td><td>   Y    </td>
   261     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   262     *    <tr><td> {@link #post}            </td><td>   Y    </td><td>   Y    </td>
   263     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   264     *    <tr><td> {@link #setHookContext}  </td><td>   Y    </td><td>   Y    </td>
   265     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   266     *    <tr><td colspan="6"> Definitions: <br />
   267     *       <ul>
   268     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   269     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   270     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   271     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   272     *           <ul>
   273     *             <li> In your module startup after this module is started
   274     *  (e.g. Swi_Module_startupDone() returns TRUE). </li>
   275     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   276     *             <li> During main().</li>
   277     *             <li> During BIOS.startupFxns.</li>
   278     *           </ul>
   279     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   280     *           <ul>
   281     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   282     *             <li> In your module startup before this module is started
   283     *  (e.g. Swi_Module_startupDone() returns FALSE).</li>
   284     *           </ul>
   285     *       </ul>
   286     *    </td></tr>
   287     *
   288     *  </table>
   289     *  @p
   290     */
   291
   292    @ModuleStartup      /* generate a call to Swi_Module_startup */
   293                        /* to initialize hooks in instances */
   294    @InstanceFinalize   /* generate call to Swi_Instance_finalize on delete */
   295
   296    @InstanceInitError  /* instance init can fail, call finalize if so */
   297
   298    module Swi
   299    {
   300        // -------- Module Constants --------
   301
   302        // -------- Module Types --------
   303
   304        /*!
   305         *  ======== FuncPtr ========
   306         *  Swi function type definition
   307         *
   308         *  All Swi functions are passed two uninterpreted arguments of type
   309         *  UArg and have no return value.
   310         */
   311        typedef Void (*FuncPtr)(UArg, UArg);
   312
   313        /*!
   314         *  ======== HookSet ========
   315         *  Swi hook set type definition
   316         *
   317         *  This structure defines the set of hook functions that can be
   318         *  specified for the Swi module.
   319         *
   320         *  See {@link #hookfunc Hook Functions} for details.
   321         */
   322        struct HookSet {
   323            Void (*registerFxn)(Int);
   324            Void (*createFxn)(Handle, Error.Block *);
   325            Void (*readyFxn)(Handle);
   326            Void (*beginFxn)(Handle);
   327            Void (*endFxn)(Handle);
   328            Void (*deleteFxn)(Handle);
   329        };
   330
   331        /*!
   332         *  ======== BasicView ========
   333         *  @_nodoc
   334         */
   335        metaonly struct BasicView {
   336            String  label;
   337            String  state;
   338            UInt    priority;
   339            String  fxn[];
   340            UArg    arg0;
   341            UArg    arg1;
   342            UInt    initTrigger;
   343            UInt    curTrigger;
   344            //Ptr   hookEnv[];
   345        };
   346
   347        /*!
   348         *  ======== ModuleView ========
   349         *  @_nodoc
   350         */
   351        metaonly struct ModuleView {
   352            String  schedulerState;
   353            String  readyQMask;
   354            Ptr     currentSwi;
   355            String  currentFxn[];
   356        };
   357
   358        /*!
   359         *  ======== rovViewInfo ========
   360         *  @_nodoc
   361         */
   362        @Facet
   363        metaonly config ViewInfo.Instance rovViewInfo =
   364            xdc.rov.ViewInfo.create({
   365                viewMap: [
   366                    ['Basic',  {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',  structName: 'BasicView'}],
   367                    ['Module', {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
   368                ]
   369             });
   370
   371        // -------- Module Proxies --------
   372
   373        // -------- Module Parameters --------
   374
   375        /*!
   376         *  ======== LM_begin ========
   377         *  The event logged just prior to invoking a Swi's function
   378         */
   379        config Log.Event LM_begin = {
   380            mask: Diags.USER1 | Diags.USER2,
   381            msg: "LM_begin: swi: 0x%x, func: 0x%x, preThread: %d"
   382        };
   383
   384        /*!
   385         *  ======== LD_end ========
   386         *  The event logged just after returning from a Swi's function
   387         */
   388        config Log.Event LD_end = {
   389            mask: Diags.USER2,
   390            msg: "LD_end: swi: 0x%x"
   391        };
   392
   393        /*!
   394         *  ======== LM_post ========
   395         *  The event logged when Swi_post() is called
   396         */
   397        config Log.Event LM_post = {
   398            mask: Diags.USER1 | Diags.USER2,
   399            msg: "LM_post: swi: 0x%x, func: 0x%x, pri: %d"
   400        };
   401
   402        /*!
   403         *  ======== A_swiDisabled ========
   404         *  Assertion raised if Swi_create is called and runtime Swi creation is
   405         *  disabled
   406         *
   407         *  @see {@link ti.sysbios.BIOS#swiEnabled}
   408         */
   409        config Assert.Id A_swiDisabled = {
   410            msg: "A_swiDisabled: Cannot create a Swi when Swi is disabled."
   411        };
   412
   413        /*!
   414         *  ======== A_badPriority ========
   415         *  Assertion raised if a Swi's priority is out of range
   416         *
   417         *  Swi priorities must be in the range of 0 and numPriorities-1.
   418         */
   419        config Assert.Id A_badPriority = {
   420            msg: "A_badPriority: An invalid Swi priority was used."
   421        };
   422
   423        /*!
   424         *  ======== numPriorities ========
   425         *  Number of Swi priorities supported
   426         *
   427         *  The maximum number of priorities supported is
   428         *  target-specific and depends on the number of
   429         *  bits in a UInt data type. For 6x and ARM devices
   430         *  the maximum number of priorities is therefore 32.
   431         *  For 28x, 55x, and MSP430 devices, the maximum number of
   432         *  priorities is 16.
   433         */
   434        config UInt numPriorities = 16;
   435
   436        /*!
   437         *  ======== hooks ========
   438         *  const array to hold all HookSet objects
   439         *  @_nodoc
   440         */
   441        config HookSet hooks[length] = [];
   442
   443
   444        // -------- Module Functions --------
   445
   446        /*!
   447         *  ======== addHookSet ========
   448         *  Add hook functions to be called by the Swi scheduler
   449         *
   450         *  This function is used in a config file to add a set of functions
   451         *  that are called before or after significant points within the Swi
   452         *  scheduler.
   453         *
   454         *  Configures a set of hook functions for the
   455         *  Swi module. Each set contains these hook functions:
   456         *
   457         *  @p(blist)
   458         *  -Register:  A function called before all statically-created Swis
   459         *      are initialized at runtime.
   460         *  -Create:    A function that is called when a Swi is created.
   461         *      This includes Swis that are created statically and those
   462         *      created dynamically using {@link #create}.
   463         *  -Ready:     A function that is called when any Swi becomes ready
   464         *      to run.
   465         *  -Begin:     A function that is called just prior to running a Swi.
   466         *  -End:       A function that is called just after a Swi finishes.
   467         *  -Delete:    A function that is called when a Swi is deleted at
   468         *  run-time with {@link #delete}.
   469         *  @p
   470         *
   471         *  See {@link #hookfunc Hook Functions} for more details.
   472         *
   473         *  HookSet structure elements may be omitted, in which case those
   474         *  elements will not exist.
   475         *
   476         *  For example, the following configuration code defines a
   477         *  HookSet:
   478         *
   479         *  @p(code)
   480         *  // Hook Set 1
   481         *  Swi.addHookSet({
   482         *     registerFxn: '&myRegister1',
   483         *     createFxn:   '&myCreate1',
   484         *     readyFxn:    '&myReady1',
   485         *     beginFxn:    '&myBegin1',
   486         *     endFxn:      '&myEnd1',
   487         *     deleteFxn:   '&myDelete1'
   488         *  });
   489         *  @p
   490         *
   491         *  @param(hookSet)         structure of type HookSet
   492         */
   493        metaonly Void addHookSet(HookSet hookSet);
   494
   495        /*!
   496         *  ======== Swi_startup ========
   497         *  Start the Swi scheduler
   498         *
   499         *  @_nodoc
   500         *  This function is called in BIOS_start() after Hwi_enable().
   501         */
   502        @DirectCall
   503        Void startup();
   504
   505        /*!
   506         *  ======== Swi_enabled ========
   507         *  Returns TRUE if the Swi scheduler is enabled
   508         *
   509         *  @_nodoc
   510         */
   511        @DirectCall
   512        Bool enabled();
   513
   514        /*!
   515         *  ======== disable ========
   516         *  Disable Swi Scheduling
   517         *
   518         *  {@link #disable} and {@link #restore} control Swi scheduling.
   519         *  {@link #disable} disables all other Swi functions from running until
   520         *  {@link #restore} is called. Hardware interrupts can still run.
   521         *
   522         *  {@link #disable} and {@link #restore} allow you to ensure that
   523         *  statements that must be performed together during critical
   524         *  processing are not preempted by other Swis or Tasks.
   525         *
   526         *  The value of the key returned is opaque to applications and is meant
   527         *  to be passed to Swi_restore().
   528         *
   529         *  In the following example, the critical section cannot be preempted
   530         *  by any Swis.
   531         *
   532         *  @p(code)
   533         *  key = Swi_disable();
   534         *      `critical section`
   535         *  Swi_restore(key);
   536         *  @p
   537         *
   538         *  @a(constraints)
   539         *  Swi_disable also disables the Task scheduler.
   540         *  Swi_restore will re-enable and invoke the Task
   541         *  scheduler if the Task scheduler was not disabled prior
   542         *  to invoking Swi_disable().
   543         *
   544         *  @b(returns)     opaque key for use with Swi_restore()
   545         */
   546        @DirectCall
   547        UInt disable();
   548
   549        /*!
   550         *  ======== enable ========
   551         *  Enable Swi Scheduling
   552         *
   553         *  @_nodoc
   554         *  Swi_enable unconditionally enables Swis and invokes the Swi scheduler
   555         *  if any Swis are pending.
   556         *
   557         *  @a(constraints)
   558         *  Swi_enable will also invoke the Task scheduler if the
   559         *  Task scheduler is not currently disabled.
   560         *
   561         *  The {@link #post} discussion regarding global interrupts also applies
   562         *  to this API.
   563         *
   564         */
   565        @DirectCall
   566        Void enable();
   567
   568        /*!
   569         *  ======== restore ========
   570         *  Restore Swi Scheduling state
   571         *
   572         *  Swi_restore restores the Swi scheduler to the locked/unlocked state
   573         *  it was in when Swi_disable was called. If the scheduler becomes
   574         *  unlocked and Swis of sufficient priority have been made ready to
   575         *  run by any of the posting APIs, then they are run at this time.
   576         *
   577         *  Swi_disable and Swi_restore control software interrupt processing.
   578         *  Swi_disable disables all other Swi functions from running until
   579         *  Swi_restore is called. Hardware interrupts can still run.
   580         *
   581         *  Swi_disable and Swi_restore allow you to ensure that statements that
   582         *  must be performed together during critical processing are not
   583         *  pre-empted by other Swis.
   584         *
   585         *  In the following example, the critical section cannot be preempted
   586         *  by any Swis:
   587         *
   588         *  @p(code)
   589         *  key = Swi_disable();
   590         *      `critical section`
   591         *  Swi_restore(key);
   592         *  @p
   593         *
   594         *  @a(constraints)
   595         *  Swi_restore will also re-enable and invoke the Task
   596         *  scheduler if the Task scheduler was not disabled prior to
   597         *  invoking Swi_disable().
   598         *
   599         *  The {@link #post} discussion regarding global interrupts applies
   600         *  to this API.
   601         *
   602         *  @param(key)     key to restore previous Swi scheduler state
   603         */
   604        @DirectCall
   605        Void restore(UInt key);
   606
   607        /*!
   608         *  ======== restoreHwi ========
   609         *  Restore Swi Scheduling state
   610         *
   611         *  @_nodoc
   612         *  Optimized version used by Hwi dispatcher.
   613         */
   614        @DirectCall
   615        Void restoreHwi(UInt key);
   616
   617        /*!
   618         *  ======== self ========
   619         *  Return address of currently executing Swi object
   620         *
   621         *  Swi_self returns the handle of the currently executing Swi.
   622         *
   623         *  For example, you can call Swi_self as follows if you want
   624         *  a Swi to repost itself:
   625         *
   626         *  @p(code)
   627         *  Swi_post( Swi_self() );
   628         *  @p
   629         *
   630         *  @b(returns)     handle of currently running Swi
   631         */
   632        @DirectCall
   633        Handle self();
   634
   635        /*!
   636         *  ======== getTrigger ========
   637         *  Return the trigger value of the currently executing Swi
   638         *
   639         *  Swi_getTrigger returns the value that Swi's trigger had when the Swi
   640         *  started running. SYS/BIOS saves the trigger value internally, so that
   641         *  Swi_getTrigger can access it at any point within a Swi object's
   642         *  function, and then automatically resets the trigger to its initial
   643         *  value.
   644         *
   645         *  Swi_getTrigger should only be called within a function run by a Swi
   646         *  object.
   647         *
   648         *  When called from within the context of a Swi, the value returned by
   649         *  Swi_getTrigger is zero if the Swi was posted by a call to Swi_andn,
   650         *  or Swi_dec. Therefore, Swi_getTrigger provides relevant information
   651         *  only if the Swi was posted by a call to Swi_inc, Swi_or, Swi_orHook,
   652         *  or Swi_post.
   653         *
   654         *  This API is called within a Swi object's function to use the trigger
   655         *  value that caused the function to run. For example, if you use
   656         *  Swi_or or Swi_inc to post a Swi, different trigger values can require
   657         *  different processing.
   658         *
   659         *  @p(code)
   660         *  swicount = Swi_getTrigger();
   661         *  @p
   662         *
   663         *  @b(returns)         trigger value
   664         */
   665        @DirectCall
   666        UInt getTrigger();
   667
   668        /*!
   669         *  ======== raisePri ========
   670         *  Raise a Swi's priority
   671         *
   672         *  @_nodoc
   673         *  This function is provided for legacy compatibility.
   674         *
   675         *  Swi_raisePri is used to raise the priority of the currently running
   676         *  Swi to the priority passed in as the argument. Swi_raisePri can be
   677         *  used in conjunction with Swi_restorePri to provide a mutual exclusion
   678         *  mechanism without disabling Swis.
   679         *
   680         *  Swi_raisePri should be called before a shared resource is accessed,
   681         *  and Swi_restorePri should be called after the access to the shared
   682         *  resource.
   683         *
   684         *  A call to Swi_raisePri not followed by a Swi_restorePri keeps the
   685         *  Swi's priority for the rest of the processing at the raised level. A
   686         *  Swi_post of the Swi posts the Swi at its original priority level.
   687         *
   688         *  A Swi object's execution priority must range from 0 to
   689         *  Swi_numPriorities - 1
   690         *
   691         *  Swi_raisePri never lowers the current Swi priority.
   692         *
   693         *  Constraints and Calling Context
   694         *  @p(blist)
   695         *  - Swi_raisePri must only be called from a Swi context.
   696         *  @p
   697         *
   698         *  @b(returns)         key for use with restorePri()
   699         */
   700        @DirectCall
   701        UInt raisePri(UInt priority);
   702
   703        /*!
   704         *  ======== restorePri ========
   705         *  Restore a Swi's priority
   706         *
   707         *  @_nodoc
   708         *  This function is provided for legacy compatibility.
   709         *
   710         *  Swi_restorePri restores the priority to the Swi's priority prior to the
   711         *  Swi_raisePri call. Swi_restorePri can be used in
   712         *  conjunction with Swi_raisePri to provide a mutual exclusion mechanism
   713         *  without disabling all Swis.
   714         *
   715         *  Swi_raisePri should be called right before the shared resource is
   716         *  referenced, and Swi_restorePri should be called after the reference to
   717         *  the shared resource.
   718         *
   719         *  Constraints and Calling Context
   720         *
   721         *  @p(blist)
   722         *  - Swi_restorePri must only be called from a Swi context.
   723         *  @p
   724         *
   725         *  @param(key)     key returned from Swi_raisePri
   726         */
   727        @DirectCall
   728        Void restorePri(UInt key);
   729
   730    instance:
   731
   732        /*!
   733         *  ======== create ========
   734         *  Create a software interrupt
   735         *
   736         *  Swi_create creates a new Swi object.
   737         *
   738         *  The following C code sets Swi parameters and
   739         *  creates two Swi objects:
   740         *
   741         *  @p(code)
   742         *  Void main()
   743         *  {
   744         *      Swi_Params swiParams;
   745         *
   746         *      Swi_Params_init(&swiParams);
   747         *      swiParams.arg0 = 1;
   748         *      swiParams.arg1 = 0;
   749         *      swiParams.priority = 2;
   750         *      swiParams.trigger = 0;
   751         *
   752         *      swi0 = Swi_create(swi0Fxn, &swiParams, NULL);
   753         *
   754         *      swiParams.arg0 = 2;
   755         *      swiParams.arg1 = 0;
   756         *      swiParams.priority = 1;
   757         *      swiParams.trigger = 3;
   758         *
   759         *      swi1 = Swi_create(swi1Fxn, &swiParams, NULL);
   760         *
   761         *      BIOS_start();
   762         *  }
   763         *  @p
   764         *
   765         *  The following XDCscript statements set Swi parameters and
   766         *  create two Swi objects:
   767         *
   768         *  @p(code)
   769         *  var Swi = xdc.useModule('ti.sysbios.knl.Swi');
   770         *
   771         *  var swiParams = new Swi.Params();
   772         *  swiParams.arg0 = 1;
   773         *  swiParams.arg1 = 0;
   774         *  swiParams.priority = 2;
   775         *  swiParams.trigger = 0;
   776         *  Program.global.swi0 = Swi.create('&swi0Fxn', swiParams);
   777         *
   778         *  swiParams.arg0 = 2;
   779         *  swiParams.priority = 1;
   780         *  swiParams.trigger = 3;
   781         *  Program.global.swi1 = Swi.create('&swi1Fxn', swiParams);
   782         *  @p
   783         *
   784         *  @param(fxn)     Swi Function
   785         */
   786        @DirectCall
   787        create(FuncPtr fxn);
   788
   789        // -------- Handle Parameters --------
   790
   791        /*!
   792         *  ======== arg0 ========
   793         *  Swi function argument 0
   794         *
   795         *  The default value of this optional parameter is 0.
   796         *
   797         *  @see #FuncPtr
   798         */
   799        config UArg arg0 = 0;
   800
   801        /*!
   802         *  ======== arg1 ========
   803         *  Swi function argument 1
   804         *
   805         *  The default value of this optional parameter is 0.
   806         *
   807         *  @see #FuncPtr
   808         */
   809        config UArg arg1 = 0;
   810
   811        /*!
   812         *  ======== priority ========
   813         *  Swi priority
   814         *
   815         *  Each software interrupt has a priority level, 0 to
   816         *  ({@link #numPriorities} - 1). A software interrupt
   817         *  preempts any lower-priority software interrupt currently executing.
   818         *  When multiple Swis of the same priority level have been posted,
   819         *  their respective Swi functions are executed in the order the Swis
   820         *  were posted.
   821         *
   822         *  The default value of this optional parameter is ~0, which yields a
   823         *  Swi with the highest priority: ({@link #numPriorities} - 1).
   824         */
   825        config UInt priority = ~0;
   826
   827        /*!
   828         *  ======== trigger ========
   829         *  Initial Swi trigger value
   830         *
   831         *  The default value of this optional parameter is 0.
   832         *
   833         *  Each Swi object has a "trigger" used either to determine whether to
   834         *  post the Swi or as a value that can be evaluated within the Swi's
   835         *  function.
   836         *
   837         *  The {@link #andn} and {@link #dec} functions post the Swi
   838         *  if the trigger value transitions to 0. The {@link #or} and
   839         *  {@link #inc} functions also modify the trigger value. ({@link #or}
   840         *  sets bits, and {@link #andn} clears bits.)
   841         */
   842        config UInt trigger = 0;
   843
   844        // -------- Handle Functions --------
   845
   846        /*!
   847         *  ======== andn ========
   848         *  Clear bits in Swi's trigger; post if trigger becomes 0
   849         *
   850         *  Swi_andn is used to conditionally post a software interrupt.
   851         *  Swi_andn clears the bits specified by a mask from Swi's internal
   852         *  trigger. If the Swi's trigger becomes 0, Swi_andn posts the Swi.
   853         *  The bitwise logical operation performed is:
   854         *
   855         *  @p(code)
   856         *  trigger = trigger AND (NOT MASK)
   857         *  @p
   858         *
   859         *  If multiple conditions that all be met before a
   860         *  Swi can run, you should use a different bit in the trigger for
   861         *  each condition. When a condition is met, clear the bit for that
   862         *  condition.
   863         *
   864         *  For example, if two events must happen before a Swi is to be
   865         *  triggered, the initial trigger value of the Swi can be 3 (binary 0011).
   866         *  One call to Swi_andn can have a mask value of 2 (binary 0010), and
   867         *  another call to Swi_andn can have a mask value of 1 (binary 0001).
   868         *  After both calls have been made, the trigger value will be 0.
   869         *
   870         *  @p(code)
   871         *  Swi_andn(swi0, 2);  // clear bit 1
   872         *  Swi_andn(swi0, 1);  // clear bit 0
   873         *  @p
   874         *
   875         *  Swi_andn results in a context switch if the Swi's trigger becomes
   876         *  zero and the Swi has higher priority than the currently executing
   877         *  thread.
   878         *
   879         *  You specify a Swi's initial trigger value at Swi creation time.
   880         *  The trigger value is automatically reset when the Swi executes.
   881         *
   882         *  @a(constraints)
   883         *  The {@link #post} discussion regarding global interrupts applies
   884         *  to this API.
   885         *
   886         *  @param(mask)    inverse value to be ANDed
   887         */
   888        @DirectCall
   889        Void andn(UInt mask);
   890
   891        /*!
   892         *  ======== dec ========
   893         *  Decrement Swi's trigger value; post if trigger becomes 0
   894         *
   895         *  Swi_dec is used to conditionally post a software interrupt. Swi_dec
   896         *  decrements the value in Swi's trigger by 1. If Swi's trigger value
   897         *  becomes 0, Swi_dec posts the Swi. You can increment a trigger value
   898         *  by using Swi_inc, which always posts the Swi.
   899         *
   900         *  For example, you would use Swi_dec if you wanted to post a Swi after
   901         *  a number of occurrences of an event.
   902         *
   903         *  @p(code)
   904         *  // swi0's trigger is configured to start at 3
   905         *  Swi_dec(swi0);      // trigger = 2
   906         *  Swi_dec(swi0);      // trigger = 1
   907         *  Swi_dec(swi0);      // trigger = 0
   908         *  @p
   909         *
   910         *  You specify a Swi's initial trigger value at Swi creation time. The
   911         *  trigger value is automatically reset when the Swi executes.
   912         *
   913         *  Swi_dec results in a context switch if the Swi's trigger becomes
   914         *  zero and the Swi has higher priority than the currently executing
   915         *  thread.
   916         *
   917         *  @a(constraints)
   918         *  The {@link #post} discussion regarding global interrupts applies
   919         *  to this API.
   920         */
   921        @DirectCall
   922        Void dec();
   923
   924        /*!
   925         *  ======== getHookContext ========
   926         *  Get hook instance's context pointer for a Swi
   927         *
   928         *  For example, this C code gets the HookContext, prints it,
   929         *  and sets a new value for the HookContext.
   930         *
   931         *  @p(code)
   932         *  Ptr pEnv;
   933         *  Swi_Handle mySwi;
   934         *  Int myHookSetId1;
   935         *
   936         *  pEnv = Swi_getHookContext(swi, myHookSetId1);
   937         *
   938         *  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
   939         *                (ULong)pEnv, (ULong)Timestamp_get32());
   940         *
   941         *  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
   942         *  @p
   943         *
   944         *  See {@link #hookfunc Hook Functions} for more details.
   945         *
   946         *  @b(returns)     hook instance's context pointer for Swi
   947         */
   948        @DirectCall
   949        Ptr getHookContext(Int id);
   950
   951        /*!
   952         *  ======== setHookContext ========
   953         *  Set hook instance's context for a swi
   954         *
   955         *  For example, this C code gets the HookContext, prints it,
   956         *  and sets a new value for the HookContext.
   957         *
   958         *  @p(code)
   959         *  Ptr pEnv;
   960         *  Swi_Handle mySwi;
   961         *  Int myHookSetId1;
   962         *
   963         *  pEnv = Swi_getHookContext(swi, myHookSetId1);
   964         *
   965         *  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
   966         *                (ULong)pEnv, (ULong)Timestamp_get32());
   967         *
   968         *  Swi_setHookContext(swi, myHookSetId1, (Ptr)0xc0de1);
   969         *  @p
   970         *
   971         *  See {@link #hookfunc Hook Functions} for more details.
   972         *
   973         *  @param(id)              hook instance's ID
   974         *  @param(hookContext)     value to write to context
   975         */
   976        @DirectCall
   977        Void setHookContext(Int id, Ptr hookContext);
   978
   979        /*!
   980         *  ======== getPri ========
   981         *  Return a Swi's priority
   982         *
   983         *  Swi_getPri returns the priority of the Swi passed in as the
   984         *  argument.
   985         *
   986         *  @b(returns)     Priority of Swi
   987         */
   988        @DirectCall
   989        UInt getPri();
   990
   991        /*!
   992         *  ======== getFunc ========
   993         *  Get Swi function and arguments
   994         *
   995         *  If either arg0 or arg1 is NULL, then the corresponding argument is not
   996         *  returned.
   997         *
   998         *  @param(arg0)     pointer for returning Swi's first function argument
   999         *  @param(arg1)     pointer for returning Swi's second function argument
  1000         *
  1001         *  @b(returns)     Swi function
  1002         */
  1003        @DirectCall
  1004        FuncPtr getFunc(UArg *arg0, UArg *arg1);
  1005
  1006        /*!
  1007         *  ======== inc ========
  1008         *  Increment Swi's trigger value and post the Swi
  1009         *
  1010         *  Swi_inc increments the value in Swi's trigger by 1 and posts the Swi
  1011         *  regardless of the resulting trigger value. You can decrement a
  1012         *  trigger value using Swi_dec, which only posts the Swi if the
  1013         *  trigger value is 0.
  1014         *
  1015         *  If a Swi is posted several times before it has a chance to begin
  1016         *  executing (i.e. when Hwis or higher priority Swis are running) the Swi
  1017         *  only runs one time. If this situation occurs, you can use Swi_inc to
  1018         *  post the Swi. Within the Swi's function, you could then use
  1019         *  Swi_getTrigger to find out how many times this Swi has been posted
  1020         *  since the last time it was executed.
  1021         *
  1022         *  You specify a Swi's initial trigger value at Swi creation time.
  1023         *  The trigger value is automatically reset when the Swi executes.
  1024         *  To get the trigger value, use Swi_getTrigger.
  1025         *
  1026         *  Swi_inc results in a context switch if the Swi is higher priority
  1027         *  than the currently executing thread.
  1028         *
  1029         *  @a(constraints)
  1030         *  The {@link #post} discussion regarding global interrupts applies
  1031         *  to this API.
  1032         */
  1033        @DirectCall
  1034        Void inc();
  1035
  1036        /*!
  1037         *  ======== or ========
  1038         *  Or mask with value contained in Swi's trigger and post the
  1039         *  Swi.
  1040         *
  1041         *  Swi_or is used to post a software interrupt. Swi_or sets the bits
  1042         *  specified by a mask in Swi's trigger. Swi_or posts the Swi
  1043         *  regardless of the resulting trigger value. The bitwise logical
  1044         *  operation performed on the trigger value is:
  1045         *
  1046         *  @p(code)
  1047         *  trigger = trigger OR mask
  1048         *  @p
  1049         *
  1050         *  You specify a Swi's initial trigger value at Swi creation time.
  1051         *  The trigger value is automatically reset when the Swi executes.
  1052         *  To get the trigger value, use Swi_getTrigger.
  1053         *
  1054         *  For example, you might use Swi_or to post a Swi if any of three
  1055         *  events should cause a Swi to be executed, but you want the Swi's
  1056         *  function to be able to tell which event occurred. Each event
  1057         *  would correspond to a different bit in the trigger.
  1058         *
  1059         *  Swi_or results in a context switch if the Swi is higher priority
  1060         *  than the currently executing thread.
  1061         *
  1062         *  @a(constraints)
  1063         *  The {@link #post} discussion regarding global interrupts applies
  1064         *  to this API.
  1065         *
  1066         *  @param(mask)    value to be ORed
  1067         */
  1068        @DirectCall
  1069        Void or(UInt mask);
  1070
  1071        /*!
  1072         *  ======== post ========
  1073         *  Unconditionally post a software interrupt
  1074         *
  1075         *  Swi_post is used to post a software interrupt regardless of the
  1076         *  trigger value. No change is made to the Swi object's trigger value.
  1077         *
  1078         *  Swi_post results in a context switch if the Swi is higher priority
  1079         *  than the currently executing thread.
  1080         *
  1081         *  @a(constraints)
  1082         *  Swis are ALWAYS run with interrupts enabled.
  1083         *  If a Swi is made ready to run as a consequence of this
  1084         *  API, interrupts will be globally enabled while the Swi function
  1085         *  executes, regardless of the prior globally enabled/disabled
  1086         *  state of interrupts.
  1087         *  Upon return from this API, the global interrupt enabled/disabled state
  1088         *  is restored to its previous value.
  1089         */
  1090        @DirectCall
  1091        Void post();
  1092
  1093    internal:   /* not for client use */
  1094
  1095        /*
  1096         *  ======== taskDisable ========
  1097         *  Swi and Task module function pointers
  1098         *
  1099         *  Used to decouple Hwi from Swi and Task when
  1100         *  dispatcherSwiSupport or dispatcherTaskSupport is false.
  1101         */
  1102        config UInt (*taskDisable)();
  1103        config Void (*taskRestore)(UInt);
  1104
  1105        /*
  1106         *  ======== schedule ========
  1107         *  Run the highest priority Swi
  1108         *
  1109         *  Called by Swi_restore() which is used
  1110         *  in a task context.
  1111         *
  1112         *  Must be called with interrupts disabled.
  1113         */
  1114        Void schedule();
  1115
  1116        /*
  1117         *  ======== run ========
  1118         *  Set up and run Swi
  1119         *
  1120         *  Enter with Hwi's disabled.
  1121         *  Exits with Hwi's enabled
  1122         */
  1123        Void run(Object *swi);
  1124
  1125        /*
  1126         *  ======== postInit ========
  1127         *  Finish initializing static and dynamic Swis
  1128         */
  1129        Int postInit(Object *swi, Error.Block *eb);
  1130
  1131        /*!
  1132         *  ======== numConstructedSwis ========
  1133         *  Number of statically constructed Swi objects
  1134         *
  1135         *  @_nodoc
  1136         *  Shouldn't be set directly by the user's
  1137         *  config (it gets set by instance$static$init).
  1138         */
  1139        config UInt numConstructedSwis = 0;
  1140
  1141        /*!
  1142         *  ======== Instance_State ========
  1143         *  @_nodoc
  1144         */
  1145        struct Instance_State {
  1146            Queue.Elem      qElem;      // Link within readyQ
  1147            FuncPtr         fxn;        // Swi function
  1148            UArg            arg0;       // Swi function 1st arg
  1149            UArg            arg1;       // Swi function 2nd arg
  1150            UInt            priority;   // Swi priority
  1151            UInt            mask;       // handy curSet orMask (= 1 << priority)
  1152            Bool            posted;     // TRUE = Swi already posted.
  1153            UInt            initTrigger;// Initial Trigger value
  1154            UInt            trigger;    // Swi Trigger
  1155            Queue.Handle    readyQ;     // This Swi's readyQ
  1156            Ptr             hookEnv[];
  1157        };
  1158
  1159        /*!
  1160         *  ======== Module_State ========
  1161         *  @_nodoc
  1162         */
  1163        struct Module_State {
  1164            Bool            locked;     // TRUE = Swi scheduler locked
  1165            UInt            curSet;     // Bitmask reflects readyQ states
  1166            UInt            curTrigger; // current Swi's on-entry trigger
  1167            Handle          curSwi;     // current Swi instance
  1168            Queue.Handle    curQ;       // current Swi's readyQ,
  1169                                        // when all posted Swis have run
  1170            Queue.Object    readyQ[];   // Swi ready queues
  1171            Handle          constructedSwis[]; // array of statically
  1172                                        // constructed Swis
  1173        };
  1174    }
  1175    /*
  1176     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:16; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
  1177
  1178     */
  1179


module ti.sysbios.knl.Task

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Task.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.knl;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import xdc.runtime.Error;
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Diags;
    44    import xdc.runtime.Log;
    45    import xdc.runtime.IHeap;
    46
    47    import ti.sysbios.knl.Queue;
    48
    49    /*!
    50     *  ======== Task ========
    51     *  Task Manager.
    52     *
    53     *  The Task module makes available a set of functions that manipulate task
    54     *  objects accessed through pointers of type {@link #Handle}. Tasks represent
    55     *  independent threads of control that conceptually execute functions in
    56     *  parallel within a single C program; in reality, concurrency is achieved
    57     *  by switching the processor from one task to another.
    58     *
    59     *  When you create a task, it is provided with its own run-time stack,
    60     *  used for storing local variables as well as for further nesting of
    61     *  function calls. Each stack must be large enough to handle normal
    62     *  subroutine calls and one task preemption context.
    63     *  A task preemption context is the context that gets saved when one task
    64     *  preempts another as a result of an interrupt thread readying
    65     *  a higher-priority task.
    66     *
    67     *  All tasks executing within a single program share a common set of
    68     *  global variables, accessed according to the standard rules of scope
    69     *  defined for C functions.
    70     *
    71     *  Each task is in one of five modes of execution at any point in time:
    72     *  running, ready, blocked, terminated, or inactive. By design, there is
    73     *  always one
    74     *  (and only one) task currently running, even if it is only the idle task
    75     *  managed internally by Task. The current task can be suspended from
    76     *  execution by calling certain Task functions, as well as functions
    77     *  provided by other modules like the Semaphore or Event Modules.
    78     *  The current task
    79     *  can also terminate its own execution. In either case, the processor
    80     *  is switched to the highest priority task that is ready to run.
    81     *
    82     *  You can assign numeric priorities to tasks. Tasks are
    83     *  readied for execution in strict priority order; tasks of the same
    84     *  priority are scheduled on a first-come, first-served basis.
    85     *  The priority of the currently running task is never lower
    86     *  than the priority of any ready task. Conversely, the running task
    87     *  is preempted and re-scheduled for execution whenever there exists
    88     *  some ready task of higher priority.
    89     *
    90     *  @a(Task Deletion)
    91     *
    92     *  Any dynamically created task that is not in the Task_Mode_RUNNING
    93     *  state (ie not the currently running task) can be deleted using the
    94     *  {@link #delete} API.
    95     *
    96     *  Task_delete() removes the task from all internal queues and calls
    97     *  Memory_free() to free the task object and stack.
    98     *  Memory_free() must acquire a lock to the memory before proceeding.
    99     *  If another task already holds a lock to the memory, then there is
   100     *  a context switch.
   101     *
   102     *  You can specify application-wide Delete hook functions that
   103     *  run whenever a task is deleted. See the discussion of Hook Functions
   104     *  below for details.
   105     *
   106     *  Note: Unless the mode of the deleted task is Task_Mode_TERMINATED,
   107     *  Task_delete should be called with care. For example, if the task has
   108     *  obtained exclusive access to a resource, deleting the task makes the
   109     *  resource unavailable.
   110     *
   111     *  Task_delete() constraints:
   112
   113     *  @p(blist)
   114     *  -The task cannot be the currently executing task (Task_self()).
   115     *  -Task_delete cannot be called from a Swi or Hwi.
   116     *  -No check is performed to prevent Task_delete from being used on a
   117     *  statically-created object. If a program attempts to delete a task object
   118     *  that was created statically, the Memory_free() call will result in an
   119     *  assertion failure in its corresponding Heap manager, causing the
   120     *  application to exit.
   121     *  @p
   122     *
   123     *  @a(Stack Alignment)
   124     *
   125     *  Stack size parameters for both static and dynamic tasks are rounded
   126     *  up to the nearest integer multiple of a target-specific alignment
   127     *  requirement.
   128     *
   129     *  In the case of Task's which are created with a user-provided stack,
   130     *  both the base address and the stackSize are aligned. The base address
   131     *  is increased to the nearest aligned address. The stack size is decreased
   132     *  accordingly and then rounded down to the nearest integer multiple of the
   133     *  target-specific required alignment.
   134     *
   135     *  @p(html)
   136     *  <a name="hookfunc"></a>
   137     *  @p
   138     *
   139     *  @a(Hook Functions)
   140     *
   141     *  Sets of hook functions can be specified for the Task module.  Each
   142     *  set can contains these hook functions:
   143     *  @p(blist)
   144     *  -Register: A function called before any statically created tasks
   145     *      are initialized at runtime.  The register hook is called at boot time
   146     *      before main() and before interrupts are enabled.
   147     *  -Create: A function that is called when a task is created.
   148     *      This includes tasks that are created statically and those
   149     *      created dynamically using {@link #create} or {@link #construct}.
   150     *      The create hook is called outside of a Task_disable/enable block and
   151     *   before the task has been added to the ready list.
   152     *  -Ready: A function that is called when a task becomes ready to run.
   153     *   The ready hook is called from within a Task_disable/enable block with
   154     *   interrupts enabled.
   155     *  -Switch: A function that is called just before a task switch
   156     *      occurs. The 'prev' and 'next' task handles are passed to the Switch
   157     *      hook. 'prev' is set to NULL for the initial task switch that occurs
   158     *      during SYS/BIOS startup.  The Switch hook is called from within a
   159     *      Task_disable/enable block with interrupts enabled.
   160     *  -Exit:      A function that is called when a task exits using
   161     *      {@link #exit}.  The exit hook is passed the handle of the exiting
   162     *      task.  The exit hook is called outside of a Task_disable/enable block
   163     *      and before the task has been removed from the kernel lists.
   164     *  -Delete: A function that is called when any task is deleted at
   165     *      run-time with {@link #delete}.  The delete hook is called outside
   166     *      of a Task_disable/enable block.
   167     *  @p
   168     *  Hook functions can only be configured statically.
   169     *
   170     *  If you define more than one set of hook functions, all the functions
   171     *  of a particular type will be run when a Swi triggers that type of
   172     *  hook.
   173     *
   174     *  @p(html)
   175     *  <B>Register Function</B>
   176     *  @p
   177     *
   178     *  The Register function is provided to allow a hook set to store its
   179     *  hookset ID.  This id can be passed to {@link #setHookContext} and
   180     *  {@link #getHookContext} to set or get hookset-specific context.  The
   181     *  Register function must be specified if the hook implementation
   182     *  needs to use {@link #setHookContext} or {@link #getHookContext}.
   183     *  The registerFxn hook function is called during system initialization
   184     *  before interrupts have been enabled.
   185     *
   186     *  @p(code)
   187     *  Void myRegisterFxn(Int id);
   188     *  @p
   189     *
   190     *  @p(html)
   191     *  <B>Create and Delete Functions</B>
   192     *  @p
   193     *
   194     *  The create and delete functions are called whenever a Task is created
   195     *  or deleted.  They are called with interrupts enabled (unless called
   196     *  at boot time or from main()).
   197     *
   198     *  @p(code)
   199     *  Void myCreateFxn(Task_Handle task, Error_Block *eb);
   200     *  @p
   201     *
   202     *  @p(code)
   203     *  Void myDeleteFxn(Task_Handle task);
   204     *  @p
   205     *
   206     *  @p(html)
   207     *  <B>Switch Function</B>
   208     *  @p
   209     *
   210     *  If a switch function is specified, it is invoked just before the new task
   211     *  is switched to.  The switch function is called with interrupts enabled.
   212     *
   213     *  This function can be used to save/restore additional task context (for
   214     *  example, external hardware registers), to check for task stack overflow,
   215     *  to monitor the time used by each task, etc.
   216     *
   217     *  @p(code)
   218     *  Void mySwitchFxn(Task_Handle prev, Task_Handle next);
   219     *  @p
   220     *
   221     *  To properly handle the switch to the first task your switchFxn should
   222     *  check for "prev == NULL" before using prev:
   223     *
   224     *  @p(code)
   225     *  Void mySwitchFxn(Task_Handle prev, Task_Handle next)
   226     *  {
   227     *      if (prev != NULL) {
   228     *          ...
   229     *      }
   230     *      ...
   231     *  }
   232     *  @p
   233     *
   234     *  @p(html)
   235     *  <B>Ready Function</B>
   236     *  @p
   237     *
   238     *  If a ready function is specified, it is invoked whenever a task is made
   239     *  ready to run.   The ready function is called  with interrupts enabled
   240     *  (unless called at boot time or from main()).
   241     *
   242     *  @p(code)
   243     *  Void myReadyFxn(Task_Handle task);
   244     *  @p
   245     *
   246     *  @p(html)
   247     *  <B>Exit Function</B>
   248     *  @p
   249     *
   250     *  If an exit function is specified, it is invoked when a task exits (via
   251     *  call to Task_exit() or when a task returns from its' main function).
   252     *  The Exit Function is called with interrupts enabled.
   253     *
   254     *  @p(code)
   255     *  Void myExitFxn(Task_Handle task);
   256     *  @p
   257     *
   258     *  @p(html)
   259     *  <h3> Calling Context </h3>
   260     *  <table border="1" cellpadding="3">
   261     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   262     *  </colgroup>
   263     *
   264     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   265     *  <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   266     *    <!--                                                       -->
   267     *    <tr><td> {@link #create}          </td><td>   N    </td><td>   N    </td>
   268     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   269     *    <tr><td> {@link #disable}         </td><td>   Y    </td><td>   Y    </td>
   270     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   271     *    <tr><td> {@link #exit}            </td><td>   N    </td><td>   N    </td>
   272     *  <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   273     *    <tr><td> {@link #getIdleTask}     </td><td>   Y    </td><td>   Y    </td>
   274     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   275     *    <tr><td> {@link #Params_init}     </td><td>   Y    </td><td>   Y    </td>
   276     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
   277     *    <tr><td> {@link #restore}         </td><td>   Y    </td><td>   Y    </td>
   278     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   279     *    <tr><td> {@link #self}            </td><td>   Y    </td><td>   Y    </td>
   280     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   281     *    <tr><td> {@link #sleep}           </td><td>   N    </td><td>   N    </td>
   282     *  <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   283     *    <tr><td> {@link #yield}           </td><td>   Y    </td><td>   Y    </td>
   284     *  <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   285     *    <tr><td> {@link #construct}       </td><td>   N    </td><td>   N    </td>
   286     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   287     *    <tr><td> {@link #delete}          </td><td>   N    </td><td>   N    </td>
   288     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   289     *    <tr><td> {@link #destruct}        </td><td>   N    </td><td>   N    </td>
   290     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   291     *    <tr><td> {@link #getEnv}          </td><td>   Y    </td><td>   Y    </td>
   292     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   293     *    <tr><td> {@link #getHookContext}  </td><td>   Y    </td><td>   Y    </td>
   294     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   295     *    <tr><td> {@link #getMode}         </td><td>   Y    </td><td>   Y    </td>
   296     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   297     *    <tr><td> {@link #getPri}          </td><td>   Y    </td><td>   Y    </td>
   298     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   299     *    <tr><td> {@link #setEnv}          </td><td>   Y    </td><td>   Y    </td>
   300     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   301     *    <tr><td> {@link #setHookContext}  </td><td>   Y    </td><td>   Y    </td>
   302     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   303     *    <tr><td> {@link #setPri}          </td><td>   Y    </td><td>   Y    </td>
   304     *  <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   305     *    <tr><td> {@link #stat}            </td><td>   Y    </td><td>   Y    </td>
   306     *  <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   307     *    <tr><td colspan="6"> Definitions: <br />
   308     *       <ul>
   309     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   310     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   311     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   312     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   313     *           <ul>
   314     *             <li> In your module startup after this module is started
   315     *  (e.g. Task_Module_startupDone() returns TRUE). </li>
   316     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   317     *             <li> During main().</li>
   318     *             <li> During BIOS.startupFxns.</li>
   319     *           </ul>
   320     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   321     *           <ul>
   322     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   323     *             <li> In your module startup before this module is started
   324     *  (e.g. Task_Module_startupDone() returns FALSE).</li>
   325     *           </ul>
   326     *       </ul>
   327     *    </td></tr>
   328     *
   329     *  </table>
   330     *  @p
   331     */
   332
   333    @ModuleStartup      /* generate a call to Task_Module_startup at startup */
   334    @InstanceFinalize   /* generate call to Task_Instance_finalize on delete */
   335    @InstanceInitError  /* instance init can fail */
   336
   337    module Task
   338    {
   339
   340        // -------- Module Constants --------
   341
   342        // -------- Module Types --------
   343
   344        /*! Task function type definition. */
   345        typedef Void (*FuncPtr)(UArg, UArg);
   346
   347        /*! "All Task Blocked" function type definition. */
   348        typedef Void (*AllBlockedFuncPtr)(Void);
   349
   350        /*!
   351         *  Task execution modes.
   352         *
   353         *  These enumerations are the range of modes or states that
   354         *  a task can be in. A task's current mode can be gotten using
   355         *  {@link #stat}.
   356         */
   357        enum Mode {
   358            Mode_RUNNING,           /*! Task is currently executing. */
   359            Mode_READY,             /*! Task is scheduled for execution. */
   360            Mode_BLOCKED,           /*! Task is suspended from execution. */
   361            Mode_TERMINATED,        /*! Task is terminated from execution. */
   362            Mode_INACTIVE           /*! Task is on inactive task list */
   363        };
   364
   365        /*!
   366         *  Task Status Buffer.
   367         *
   368         *  Passed to and filled in by {@link #stat};
   369         */
   370        struct Stat {
   371            Int     priority;       /*! Task priority. */
   372            Ptr     stack;          /*! Task stack. */
   373            SizeT   stackSize;      /*! Task stack size. */
   374            IHeap.Handle stackHeap; /*! Heap used to alloc stack. */
   375            Ptr     env;            /*! Global environment struct. */
   376            Mode    mode;           /*! Task's current mode. */
   377            Ptr     sp;             /*! Task's current stack pointer. */
   378            SizeT   used;           /*! max # of words used on stack. */
   379        };
   380
   381        /*!
   382         *  Task hook set type definition.
   383         *
   384         *  Sets of hook functions can be specified for the Task module.
   385         *  See {@link #hookfunc Hook Functions} for details.
   386         */
   387        struct HookSet {
   388            Void (*registerFxn)(Int);
   389            Void (*createFxn)(Handle, Error.Block *);
   390            Void (*readyFxn)(Handle);
   391            Void (*switchFxn)(Handle, Handle);
   392            Void (*exitFxn)(Handle);
   393            Void (*deleteFxn)(Handle);
   394        };
   395
   396        /*!  @_nodoc */
   397        metaonly struct BasicView {
   398            String      label;
   399            Int         priority;
   400            String      mode;
   401            String      fxn[];
   402            UArg        arg0;
   403            UArg        arg1;
   404            SizeT       stackSize;
   405            Ptr         stackBase;
   406        }
   407
   408        /*!  @_nodoc */
   409        metaonly struct DetailedView {
   410            String      label;
   411            Int         priority;
   412            String      mode;
   413            String      fxn[];
   414            UArg        arg0;
   415            UArg        arg1;
   416            SizeT       stackPeak;
   417            SizeT       stackSize;
   418            Ptr         stackBase;
   419            String      blockedOn;
   420        }
   421
   422        /*!  @_nodoc */
   423        metaonly struct ModuleView {
   424            String      schedulerState;
   425            String      readyQMask;
   426            Bool        workPending;
   427            UInt        numVitalTasks;
   428            Ptr         currentTask;
   429            SizeT       hwiStackPeak;
   430            SizeT       hwiStackSize;
   431            Ptr         hwiStackBase;
   432        }
   433
   434        /*! @_nodoc */
   435        @Facet
   436        metaonly config ViewInfo.Instance rovViewInfo =
   437            ViewInfo.create({
   438                viewMap: [
   439                    ['Basic',    {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic',    structName: 'BasicView'}],
   440                    ['Detailed', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitDetailed', structName: 'DetailedView'}],
   441                    ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule',   structName: 'ModuleView'}],
   442                ]
   443            });
   444
   445        // -------- Module Parameters --------
   446
   447        // Logs
   448
   449        /*! Logged on every task switch */
   450        config Log.Event LM_switch = {
   451            mask: Diags.USER1 | Diags.USER2,
   452            msg: "LM_switch: oldtsk: 0x%x, oldfunc: 0x%x, newtsk: 0x%x, newfunc: 0x%x"
   453        };
   454
   455        /*! Logged on calls to Task_sleep */
   456        config Log.Event LM_sleep = {
   457            mask: Diags.USER1 | Diags.USER2,
   458            msg: "LM_sleep: tsk: 0x%x, func: 0x%x, timeout: %d"
   459        };
   460
   461        /*! Logged when a task is made ready to run (ie Semaphore_post()) */
   462        config Log.Event LD_ready = {
   463            mask: Diags.USER2,
   464            msg: "LD_ready: tsk: 0x%x, func: 0x%x, pri: %d"
   465        };
   466
   467        /*! Logged when a task is blocked (ie Semaphore_pend()) */
   468        config Log.Event LD_block = {
   469            mask: Diags.USER2,
   470            msg: "LD_block: tsk: 0x%x, func: 0x%x"
   471        };
   472
   473        /*! Logged on calls to Task_yield */
   474        config Log.Event LM_yield = {
   475            mask: Diags.USER1 | Diags.USER2,
   476            msg: "LM_yield: tsk: 0x%x, func: 0x%x, currThread: %d"
   477        };
   478
   479        /*! Logged on calls to Task_setPri */
   480        config Log.Event LM_setPri = {
   481            mask: Diags.USER1 | Diags.USER2,
   482            msg: "LM_setPri: tsk: 0x%x, func: 0x%x, oldPri: %d, newPri %d"
   483        };
   484
   485        /*!
   486         *  Logged when Task functions fall thru the bottom
   487         *  or when Task_exit() is explicitly called.
   488         */
   489        config Log.Event LD_exit = {
   490            mask: Diags.USER2,
   491            msg: "LD_exit: tsk: 0x%x, func: 0x%x"
   492        };
   493
   494        // Errors
   495
   496        /*!
   497         *  Error raised when a stack overflow (or corruption) is detected.
   498         *
   499         *  This error is raised by kernel's stack checking function.  This
   500         *  function checks the stacks before every task switch to make sure
   501         *  that reserved word at top of stack has not been modified.
   502         *
   503         *  The stack checking logic is enabled by the {@link #initStackFlag} and
   504         *  {@link #checkStackFlag} configuration parameters.  If both of these
   505         *  flags are set to true, the kernel will validate the stacks.
   506         */
   507        config Error.Id E_stackOverflow  = {
   508            msg: "E_stackOverflow: Task 0x%x stack overflow."
   509        };
   510
   511        /*!
   512         *  Error raised when a task's stack pointer (SP) does not point
   513         *  somewhere within the task's stack.
   514         *
   515         *  This error is raised by kernel's stack checking function.  This
   516         *  function checks the SPs before every task switch to make sure
   517         *  they point within the task's stack.
   518         *
   519         *  The stack checking logic is enabled by the {@link #initStackFlag} and
   520         *  {@link #checkStackFlag} configuration parameters.  If both of these
   521         *  flags are set to true, the kernel will validate the stack pointers.
   522         */
   523        config Error.Id E_spOutOfBounds  = {
   524            msg: "E_spOutOfBounds: Task 0x%x stack error, SP = 0x%x."
   525        };
   526
   527        // Asserts
   528
   529        /*! Asserted in Task_create and Task_delete */
   530        config Assert.Id A_badThreadType = {
   531            msg: "A_badThreadType: Cannot create/delete a task from Hwi or Swi thread."
   532        };
   533
   534        /*! Asserted in Task_delete */
   535        config Assert.Id A_badTaskState = {
   536            msg: "A_badTaskState: Can't delete a task in RUNNING state."
   537        };
   538
   539        /*! Asserted in Task_delete */
   540        config Assert.Id A_noPendElem = {
   541            msg: "A_noPendElem: Not enough info to delete BLOCKED task."
   542        };
   543
   544        /*! Asserted in Task_create */
   545        config Assert.Id A_taskDisabled = {
   546            msg: "A_taskDisabled: Cannot create a task when tasking is disabled."
   547        };
   548
   549        /*! Asserted in Task_create */
   550        config Assert.Id A_badPriority = {
   551            msg: "A_badPriority: An invalid task priority was used."
   552        };
   553
   554        /*! Asserted in Task_sleep */
   555        config Assert.Id A_badTimeout = {
   556            msg: "A_badTimeout: Can't sleep FOREVER."
   557        };
   558
   559        /*!
   560         *  Number of Task priorities supported. Default is 16.
   561         *
   562         *  The maximum number of priorities supported is
   563         *  target specific and depends on the number of
   564         *  bits in a UInt data type. For 6x and ARM devices
   565         *  the maximum number of priorities is therefore 32.
   566         *  For 28x, 55x, and MSP430 devices, the maximum number of
   567         *  priorities is 16.
   568         */
   569        config UInt numPriorities = 16;
   570
   571        /*!
   572         *  Default stack size (in MAUs) used for all tasks.
   573         *
   574         *  Default is obtained from the family-specific TaskSupport module
   575          *  (e.g. {@link ti.sysbios.family.arm.m3.TaskSupport},
   576          *  {@link ti.sysbios.family.c62.TaskSupport}).
   577         */
   578        config SizeT defaultStackSize;
   579
   580        /*!
   581         *  Default memory section used for all statically created task stacks.
   582         *
   583         *  The default stack section name is target/device specific.
   584         *  For C6x targets it is ".far:taskStackSection".
   585         *  For C28x targets it is ".taskStackSection".
   586         *  For all other targets it is ".bss:taskStackSection".
   587         *
   588         *  By default, all statically created task stacks are grouped together
   589         *  into the defaultStackSection and placed where ever
   590         *  the target specific defaultStackSection base section name
   591         *  (ie .bss, .far, .ebss) is placed.
   592         *
   593         *  To place all task stacks into a different memory segment,
   594         *  add the following to your config script:
   595         *
   596         *  @p(code)
   597         *  Program.sectMap[Task.defaultStackSection] = new Program.SectionSpec();
   598         *  Program.sectMap[Task.defaultStackSection].loadSegment =
   599         *                   "yourMemorySegment";
   600         *  @p
   601         *
   602         *  To group all task stacks into a different section AND place that
   603         *  section into a specific memory segment, add the following to your
   604         *  config script:
   605         *
   606         *  @p(code)
   607         *  Task.defaultStackSection = ".yourSectionName";
   608         *  Program.sectMap[Task.defaultStackSection] = new Program.SectionSpec();
   609         *  Program.sectMap[Task.defaultStackSection].loadSegment =
   610         *                   "yourMemorySegment";
   611         *  @p
   612         *
   613         *  Where "yourSectionName" can be just about anything, and
   614         *                   "yourMemorySegment"
   615         *  must be a memory segment defined for your board.
   616         */
   617        metaonly config String defaultStackSection;
   618
   619        /*!
   620         *  Default Mem heap used for all dynamically created task stacks.
   621         *
   622         *  Default is null.
   623         */
   624        config IHeap.Handle defaultStackHeap;
   625
   626        /*!
   627         *  Create a task (of priority 0) to run the Idle functions in.
   628         *
   629         *  When set to true, a task is created that continuously calls the
   630         *  {@link Idle#run Idle_run()} function, which, in turn calls each of
   631         *  the configured Idle functions.
   632         *
   633         *  When set to false, no Idle Task is created and it is up to the
   634         *  user to call the Idle_run() function if the configured Idle
   635         *  functions need to be run. Or, by adding the following lines to
   636         *  the config script, the Idle functions will run whenever all
   637         *  tasks are blocked ({@link #allBlockedFunc Task.allBlockedFunc}):
   638         *
   639         *  @p(code)
   640         *  Task.enableIdleTask = false;
   641         *  Task.allBlockedFunc = Idle.run;
   642         *  @p
   643         *
   644         *  Default is true.
   645         *
   646         *  @see #idleTaskStackSize
   647         *  @see #idleTaskStackSection
   648         *  @see #idleTaskVitalTaskFlag
   649         *  @see #allBlockedFunc
   650         */
   651        metaonly config Bool enableIdleTask = true;
   652
   653        /*!
   654         *  Idle task stack size in MAUs.
   655         *
   656         *  Default is inherited from module config defaultStackSize.
   657         */
   658        metaonly config SizeT idleTaskStackSize;
   659
   660        /*!
   661         *  Idle task stack section
   662         *
   663         *  Default is inherited from module config defaultStackSection;
   664         */
   665        metaonly config String idleTaskStackSection;
   666
   667        /*!
   668         *  Idle task's vitalTaskFlag.
   669         *  (see {@link #vitalTaskFlag}).
   670         *
   671         *  Default is true.
   672         */
   673        metaonly config Bool idleTaskVitalTaskFlag = true;
   674
   675        /*!
   676         *  Function to call while all tasks are blocked.
   677         *
   678         *  This function will be called repeatedly while no tasks are
   679         *  ready to run.
   680         *
   681         *  Ordinarily (in applications that have tasks ready to run at startup),
   682         *  the function will run in the context of the last task to block.
   683         *
   684         *  In an application where there are no tasks ready to run
   685         *  when BIOS_start() is called, the allBlockedFunc function is
   686         *  called within the BIOS_start() thread which runs on the system/ISR
   687         *  stack.
   688         *
   689         *  By default, allBlockedFunc is initialized to point to an internal
   690         *  function that simply returns.
   691         *
   692         *  By adding the following lines to the config script, the Idle
   693         *  functions will run whenever all tasks are blocked:
   694         *
   695         *  @p(code)
   696         *  Task.enableIdleTask = false;
   697         *  Task.allBlockedFunc = Idle.run;
   698         *  @p
   699         *
   700         *  @see #enableIdleTask
   701         *
   702         *  @a(constraints)
   703         *  The configured allBlockedFunc is designed to be called repeatedly.
   704         *  It must return in order for the task scheduler to check if all
   705         *  tasks are STILL blocked and if not, run the highest priority task
   706         *  currently ready to run.
   707         *
   708         *  The configured allBlockedFunc function is called with interrupts
   709         *  disabled. If your function must run with interrupts enabled,
   710         *  surround the body of your code with  Hwi_enable()/Hwi_restore()
   711         *  function calls per the following example:
   712         *
   713         *  @p(code)
   714         *  Void yourFunc() {
   715         *      UInt hwiKey;
   716         *
   717         *      hwiKey = Hwi_enable();
   718         *
   719         *      ...         // your code here
   720         *
   721         *      Hwi_restore(hwiKey);
   722         *  }
   723         *  @p
   724         */
   725        config AllBlockedFuncPtr allBlockedFunc;
   726
   727        /*!
   728         *  Initialize stack with known value for stack checking at runtime
   729         *  (see {@link #checkStackFlag}).
   730         *
   731         *  This is also useful for inspection of stack in debugger or core
   732         *  dump utilities.
   733         *  Default is true.
   734         */
   735        config Bool initStackFlag = true;
   736
   737        /*!
   738         *  Check 'from' and 'to' task stacks before task context switch.
   739         *
   740         *  The check consists of testing the top of stack value against
   741         *  its initial value (see {@link #initStackFlag}). If it is no
   742         *  longer at this value, the assumption is that the task has
   743         *  overrun its stack. If the test fails, then the
   744         *  {@link #E_stackOverflow} error is raised.
   745         *
   746         *  Runtime stack checking is only performed if {@link #initStackFlag} is
   747         *  also true.
   748         *
   749         *  Default is true.
   750         *
   751         *  To enable or disable full stack checking, you should set both this
   752         *  flag and the {@link ti.sysbios.hal.Hwi#checkStackFlag}.
   753         */
   754        metaonly config Bool checkStackFlag = true;
   755
   756        /*!
   757         *  Automatically delete terminated tasks.
   758         *
   759         *  If this feature is enabled, an Idle function is installed that
   760         *  deletes dynamically created Tasks that have terminated either
   761         *  by falling through their task function or by explicitly calling
   762         *  Task_exit().
   763         *
   764         *  A list of terminated Tasks that were created dynmically is
   765         *  maintained internally. Each invocation of the installed Idle function
   766         *  deletes the first Task on this list. This one-at-a-time process
   767         *  continues until the list is empty.
   768         *
   769         *  @a(Note)
   770         *  This feature is disabled by default.
   771         *
   772         *  If this feature is enable, the user's application must not
   773         *  also delete terminated tasks or undefined and/or potentially
   774         *  catastrophic behavior will result.
   775         */
   776        config Bool deleteTerminatedTasks = false;
   777
   778        /*!
   779         *  Const array that holds the HookSet objects.
   780         *
   781         *  See {@link #hookfunc Hook Functions} for details about HookSets.
   782         */
   783        config HookSet hooks[length] = [];
   784
   785        // -------- Module Functions --------
   786
   787        /*!
   788         *  ======== addHookSet ========
   789         *  addHookSet is used in a config file to add a hook set.
   790         *
   791         *  Configures a set of hook functions for the
   792         *  Task module. Each set contains these hook functions:
   793         *
   794         *  @p(blist)
   795         *  -Register: A function called before any statically created tasks
   796         *  are initialized at runtime.  The register hook is called at boot time
   797         *  before main() and before interrupts are enabled.
   798         *  -Create: A function that is called when a task is created.
   799         *  This includes tasks that are created statically and those
   800         *  created dynamically using {@link #create} or {@link #construct}.
   801         *  The create hook is called outside of a Task_disable/enable block and
   802         *   before the task has been added to the ready list.
   803         *  -Ready: A function that is called when a task becomes ready to run.
   804         *   The ready hook is called from within a Task_disable/enable block with
   805         *   interrupts enabled.
   806         *  -Switch: A function that is called just before a task switch
   807         *  occurs. The 'prev' and 'next' task handles are passed to the Switch
   808         *  hook. 'prev' is set to NULL for the initial task switch that occurs
   809         *  during SYS/BIOS startup.  The Switch hook is called from within a
   810         *  Task_disable/enable block with interrupts enabled.
   811         *  -Exit:  A function that is called when a task exits using
   812         *  {@link #exit}.  The exit hook is passed the handle of the exiting
   813         *  task.  The exit hook is called outside of a Task_disable/enable block
   814         *  and before the task has been removed from the kernel lists.
   815         *  -Delete: A function that is called when any task is deleted at
   816         *  run-time with {@link #delete}.  The delete hook is called outside
   817         *  of a Task_disable/enable block.
   818         *  @p
   819         *  Hook functions can only be configured statically.
   820         *
   821         *  See {@link #hookfunc Hook Functions} for more details.
   822         *
   823         *  HookSet structure elements may be omitted, in which case those
   824         *  elements will not exist.
   825         *
   826         *  For example, the following configuration code defines a HookSet:
   827         *
   828         *  @p(code)
   829         *  // Hook Set 1
   830         *  Task.addHookSet({
   831         *     registerFxn: '&myRegister1',
   832         *     createFxn:   '&myCreate1',
   833         *     readyFxn:    '&myReady1',
   834         *     switchFxn:   '&mySwitch1',
   835         *     exitFxn:     '&myExit1',
   836         *     deleteFxn:   '&myDelete1'
   837         *  });
   838         *  @p
   839         *
   840         *  @param(hook)    structure of type HookSet
   841         */
   842        metaonly Void addHookSet(HookSet hook);
   843
   844        /*!
   845         *  @_nodoc
   846         *  ======== Task_startup ========
   847         *  Start the task scheduler.
   848         *
   849         *  Task_startup signals the end of boot operations, enables
   850         *  the Task scheduler and schedules the highest priority ready
   851         *  task for execution.
   852         *
   853         *  Task_startup is called by BIOS_start() after Hwi_enable()
   854         *  and Swi_enable(). There is no return from this function as the
   855         *  execution thread is handed to the highest priority ready task.
   856         */
   857        @DirectCall
   858        Void startup();
   859
   860        /*!
   861         *  ======== Task_disable ========
   862         *  Disable the task scheduler.
   863         *
   864         *  {@link #disable} and {@link #restore} control Task scheduling.
   865         *  {@link #disable} disables all other Tasks from running until
   866         *  {@link #restore} is called. Hardware and Software interrupts
   867         *  can still run.
   868         *
   869         *  {@link #disable} and {@link #restore} allow you to ensure that
   870         *  statements
   871         *  that must be performed together during critical processing are not
   872         *  preempted by other Tasks.
   873         *
   874         *  The value of the key returned is opaque to applications and is meant
   875         *  to be passed to Task_restore().
   876         *
   877         *  In the following example, the critical section is
   878         *  not preempted by any Tasks.
   879         *
   880         *  @p(code)
   881         *  key = Task_disable();
   882         *      `critical section`
   883         *  Task_restore(key);
   884         *  @p
   885         *
   886         *  You can also use {@link #disable} and {@link #restore} to
   887         *  create several Tasks and allow them to be invoked in
   888         *  priority order.
   889         *
   890         *  {@link #disable} calls can be nested.
   891         *
   892         *  @b(returns)     key for use with {@link #restore}
   893         *
   894         *  @a(constraints)
   895         *  Do not call any function that can cause the current task to block
   896         *  within a {@link #disable}/{@link #restore} block. For example,
   897         *  {@link ti.sysbios.knl.Semaphore#pend Semaphore_pend}
   898         *  (if timeout is non-zero),
   899         *  {@link #sleep}, {@link #yield}, and Memory_alloc can all
   900         *  cause blocking.
   901         */
   902        @DirectCall
   903        UInt disable();
   904
   905        /*!
   906         *  @_nodoc
   907         *  ======== enable ========
   908         *  Enable the task scheduler.
   909         *
   910         *  {@link #enable} unconditionally enables the Task scheduler and
   911         *  schedules the highest priority ready task for execution.
   912         *
   913         *  This function is called by {@link #startup} (which is called by
   914         *  {@link ti.sysbios.BIOS#start BIOS_start}) to begin multi-tasking
   915         *  operations.
   916         */
   917        @DirectCall
   918        Void enable();
   919
   920        /*!
   921         *  ======== restore ========
   922         *  Restore Task scheduling state.
   923         *
   924         *  {@link #disable} and {@link #restore} control Task scheduling
   925         *  {@link #disable} disables all other Tasks from running until
   926         *  {@link #restore} is called. Hardware and Software interrupts
   927         *  can still run.
   928         *
   929         *  {@link #disable} and {@link #restore} allow you to ensure that
   930         *  statements
   931         *  that must be performed together during critical processing are not
   932         *  preempted.
   933
   934         *  In the following example, the critical section is not preempted
   935         *  by any Tasks.
   936         *
   937         *  @p(code)
   938         *  key = Task_disable();
   939         *      `critical section`
   940         *  Task_restore(key);
   941         *  @p
   942         *
   943         *  You can also use {@link #disable} and {@link #restore} to create
   944         *  several Tasks and allow them to be performed in priority order.
   945         *
   946         *  {@link #disable} calls can be nested.
   947         *
   948         *  {@link #restore} returns with interrupts enabled if the key unlocks
   949         *  the scheduler
   950         *
   951         *  @param(key)     key to restore previous Task scheduler state
   952         *
   953         *  @a(constraints)
   954         *  Do not call any function that can cause the current task to block
   955         *  within a {@link #disable}/{@link #restore} block. For example,
   956         *  {@link ti.sysbios.knl.Semaphore#pend Semaphore_pend()}
   957         *  (if timeout is non-zero),
   958         *  {@link #sleep}, {@link #yield}, and Memory_alloc can all
   959         *  cause blocking.
   960         *
   961         *  {@link #restore} internally calls Hwi_enable() if the key passed
   962         *  to it results in the unlocking of the Task scheduler (ie if this
   963         *  is root Task_disable/Task_restore pair).
   964         */
   965        @DirectCall
   966        Void restore(UInt key);
   967
   968        /*!
   969         *  @_nodoc
   970         *  ======== restoreHwi ========
   971         *  Restore Task scheduling state.
   972         *  Used by dispatcher. Does not re-enable Ints.
   973         */
   974        @DirectCall
   975        Void restoreHwi(UInt key);
   976
   977        /*!
   978         *  ======== self ========
   979         *  Returns a handle to the currently executing Task object.
   980         *
   981         *  Task_self returns the object handle for the currently executing task.
   982         *  This function is useful when inspecting the object or when the current
   983         *  task changes its own priority through {@link #setPri}.
   984         *
   985         *  No task switch occurs when calling Task_self.
   986         *
   987         *  Task_self will return NULL until Tasking is initiated at the end of
   988         *  BIOS_start().
   989         *
   990         *  @b(returns)     address of currently executing task object
   991         */
   992        @DirectCall
   993        Handle self();
   994
   995        /*!
   996         *  ======== selfMacro ========
   997         *  Returns a handle to the currently executing Task object.
   998         *
   999         *  Task_selfMacro is identical to {@link #self} but is implemented as
  1000         *  and inline macro.
  1001         *
  1002         *  @b(returns)     address of currently executing task object
  1003         */
  1004        @Macro
  1005        Handle selfMacro();
  1006
  1007        /*!
  1008         *  @_nodoc
  1009         *  ======== checkStacks ========
  1010         *  Check for stack overflow.
  1011         *
  1012         *  This function is usually called by the {@link #HookSet} switchFxn to
  1013         *  make sure task stacks are valid before performing the context
  1014         *  switch.
  1015         *
  1016         *  If a stack overflow is detected on either the oldTask or the
  1017         *  newTask, a {@link #E_stackOverflow} Error is raised and the system
  1018         *  exited.
  1019         *
  1020         *  In order to work properly, {@link #checkStacks} requires that the
  1021         *  {@link #initStackFlag} set to true, which it is by default.
  1022         *
  1023         *  You can call {@link #checkStacks} directly from your application.
  1024         *  For example, you can check the current task's stack integrity
  1025         *  at any time with a call like the following:
  1026         *
  1027         *  @p(code)
  1028         *  Task_checkStacks(Task_self(), Task_self());
  1029         *  @p
  1030         *
  1031         *  @param(oldTask)  leaving Task Object Ptr
  1032         *  @param(newTask)  entering Task Object Ptr
  1033         */
  1034        @DirectCall
  1035        Void checkStacks(Handle oldTask, Handle newTask);
  1036
  1037        /*!
  1038         *  ======== exit ========
  1039         *  Terminate execution of the current task.
  1040         *
  1041         *  Task_exit terminates execution of the current task, changing its mode
  1042         *  from {@link #Mode_RUNNING} to {@link #Mode_TERMINATED}. If all tasks
  1043         *  have been terminated, or if all remaining tasks have their
  1044         *  vitalTaskFlag attribute set to FALSE, then SYS/BIOS terminates the
  1045         *  program as a whole by calling the function System_exit with a status
  1046         *  code of 0.
  1047         *
  1048         *  Task_exit is automatically called whenever a task returns from its
  1049         *  top-level function.
  1050         *
  1051         *  Exit Hooks (see exitFxn in {@link #HookSet}) can be used to provide
  1052         *  functions that run whenever a task is terminated. The exitFxn Hooks
  1053         *  are called before the task has been blocked and marked
  1054         *  {@link #Mode_TERMINATED}.
  1055         *  See {@link #hookfunc Hook Functions} for more information.
  1056         *
  1057         *  Any SYS/BIOS function can be called from an Exit Hook function.
  1058         *
  1059         *  Calling {@link #self} within an Exit function returns the task
  1060         *  being exited. Your Exit function declaration should be similar to
  1061         *  the following:
  1062         *  @p(code)
  1063         *  Void myExitFxn(Void);
  1064         *  @p
  1065         *
  1066         *  A task switch occurs when calling Task_exit unless the program as a
  1067         *  whole is terminated
  1068         *
  1069         *  @a(constraints)
  1070         *  Task_exit cannot be called from a Swi or Hwi.
  1071         *
  1072         *  Task_exit cannot be called from the program's main() function.
  1073         */
  1074        @DirectCall
  1075        Void exit();
  1076
  1077        /*!
  1078         *  ======== sleep ========
  1079         *  Delay execution of the current task.
  1080         *
  1081         *  Task_sleep changes the current task's mode from {@link #Mode_RUNNING}
  1082         *  to {@link #Mode_BLOCKED}, and delays its execution for nticks
  1083         *  increments of the {@link Clock system clock}. The actual time
  1084         *  delayed can be up to 1 system clock tick less than nticks due to
  1085         *  granularity in system timekeeping and the time elapsed per
  1086         *  tick is determined by {@link Clock#tickPeriod Clock_tickPeriod}.
  1087         *
  1088         *  After the specified period of time has elapsed, the task reverts to
  1089         *  the {@link #Mode_READY} mode and is scheduled for execution.
  1090         *
  1091         *  A task switch always occurs when calling Task_sleep if nticks > 0.
  1092         *
  1093         *  @param(nticks)  number of system clock ticks to sleep
  1094         *
  1095         *  @a(constraints)
  1096         *  Task_sleep cannot be called from a Swi or Hwi, or within a
  1097         *  {@link #disable} / {@link #restore} block.
  1098         *
  1099         *  Task_sleep cannot be called from the program's main() function.
  1100         *
  1101         *  Task_sleep should not be called from within an Idle function. Doing
  1102         *  so prevents analysis tools from gathering run-time information.
  1103         *
  1104         *  nticks cannot be {@link ti.sysbios.BIOS#WAIT_FOREVER BIOS_WAIT_FOREVER}.
  1105         */
  1106        @DirectCall
  1107        Void sleep(UInt nticks);
  1108
  1109        /*!
  1110         *  ======== yield ========
  1111         *  Yield processor to equal priority task.
  1112         *
  1113         *  Task_yield yields the processor to another task of equal priority.
  1114         *
  1115         *  A task switch occurs when you call Task_yield if there is an equal
  1116         *  priority task ready to run.
  1117         *
  1118         *  Tasks of higher priority preempt the currently running task without
  1119         *  the need for a call to Task_yield. If only lower-priority tasks are
  1120         *  ready to run when you call Task_yield, the current task continues to
  1121         *  run. Control does not pass to a lower-priority task.
  1122         *
  1123         *  @a(constraints)
  1124         *  When called within an Hwi, the code sequence calling Task_yield
  1125         *  must be invoked by the Hwi dispatcher.
  1126         *
  1127         *  Task_yield cannot be called from the program's main() function.
  1128         */
  1129        @DirectCall
  1130        Void yield();
  1131
  1132        /*!
  1133         *  ======== getIdleTask ========
  1134         *  returns a handle to idle task object
  1135         */
  1136        @DirectCall
  1137        Handle getIdleTask();
  1138
  1139        /*!
  1140         *  ======== getNickName ========
  1141         *
  1142         */
  1143        metaonly String getNickName(Any tskView);
  1144
  1145    instance:
  1146
  1147        /*!
  1148         *  ======== create ========
  1149         *  Create a Task.
  1150         *
  1151         *  Task_create creates a new task object. If successful, Task_create
  1152         *  returns the handle of the new task object. If unsuccessful,
  1153         *  Task_create returns NULL unless it aborts.
  1154         *
  1155         *  The fxn parameter uses the {@link #FuncPtr} type to pass a pointer to
  1156         *  the function the Task object should run. For example, if myFxn is a
  1157         *  function in your program, your C code can create a Task object
  1158         *  to call that
  1159         *  function as follows:
  1160         *
  1161         *  @p(code)
  1162         *  Task_Params taskParams;
  1163         *
  1164         *  // Create task with priority 15
  1165         *  Task_Params_init(&taskParams);
  1166         *  taskParams.stackSize = 512;
  1167         *  taskParams.priority = 15;
  1168         *  Task_create((Task_FuncPtr)myFxn, &taskParams, &eb);
  1169         *  @p
  1170         *
  1171         *  The following statements statically create a task in the
  1172         *  configuration file:
  1173         *
  1174         *  @p(code)
  1175         *  var params = new Task.Params;
  1176         *  params.instance.name = "tsk0";
  1177         *  params.arg0 = 1;
  1178         *  params.arg1 = 2;
  1179         *  params.priority = 1;
  1180         *  Task.create('&tsk0_func', params);
  1181         *  @p
  1182         *
  1183         *  If NULL is passed instead of a pointer to an actual Task_Params
  1184         *  struct, a
  1185         *  default set of parameters is used. The "eb" is an error block that
  1186         *  you can use
  1187         *  to handle errors that may occur during Task object creation.
  1188         *
  1189         *  The newly created task is placed in {@link #Mode_READY} mode, and is
  1190         *  scheduled to begin concurrent execution of the following function
  1191         *  call:
  1192         *
  1193         *  @p(code)
  1194         *  (*fxn)(arg1, arg2);
  1195         *  @p
  1196         *
  1197         *  As a result of being made ready to run, the task runs any
  1198         *  application-wide Ready functions that have been specified.
  1199         *
  1200         *  Task_exit is automatically called if and when the task returns
  1201         *  from fxn.
  1202         *
  1203         *  @p(html)
  1204         *  <B>Create Hook Functions</B>
  1205         *  @p
  1206         *
  1207         *  You can specify application-wide Create hook functions in your config
  1208         *  file that run whenever a task is created. This includes tasks that
  1209         *  are created statically and those created dynamically using
  1210         *  Task_create.
  1211         *
  1212         *  For Task objects created statically, Create functions are called
  1213         *  during the Task module initialization phase of the program startup
  1214         *  process prior to main().
  1215         *
  1216         *  For Task objects created dynamically, Create functions
  1217         *  are called after the task handle has been initialized but before the
  1218         *  task has been placed on its ready queue.
  1219         *
  1220         *  Any SYS/BIOS function can be called from Create functions.
  1221         *  SYS/BIOS passes the task handle of the task being created to each of
  1222         *  the Create functions.
  1223         *
  1224         *  All Create function declarations should be similar to this:
  1225         *  @p(code)
  1226         *  Void myCreateFxn(Task_Handle task);
  1227         *  @p
  1228         *
  1229         *  @param(fxn)     Task Function
  1230         *
  1231         *  @a(constraints)
  1232         *  @p(blist)
  1233         *  - The fxn parameter and the name attribute cannot be NULL.
  1234         *  - The priority attribute must be less than or equal to
  1235         *  ({@link #numPriorities} - 1) and greater than or equal to one (1)
  1236         *  (priority 0 is owned by the Idle task).
  1237         *  - The priority can be less than zero (0) for tasks that should not
  1238         *  execute.
  1239         *  - The stackHeap attribute must identify a valid memory Heap.
  1240         *  @p
  1241         */
  1242        @DirectCall
  1243        create(FuncPtr fxn);
  1244
  1245        // -------- Handle Parameters --------
  1246
  1247        /*! Task function argument. Default is 0 */
  1248        config UArg arg0 = 0;
  1249
  1250        /*! Task function argument. Default is 0 */
  1251        config UArg arg1 = 0;
  1252
  1253        /*!
  1254         *  Task priority (0 to numPriorities-1 or -1).
  1255         *  Default is 1.
  1256         */
  1257        config Int priority = 1;
  1258
  1259        /*!
  1260         *  Task stack pointer. Default = null.
  1261         *
  1262         *  Null indicates that the stack is to be allocated by create().
  1263         *
  1264         *  Example: To statically initialize "tsk0"'s stack to a literal
  1265         *  address, use the following syntax:
  1266         *
  1267         *  @p(code)
  1268         *      Program.global.tsk0.stack = $addr(literal);
  1269         *  @p
  1270         *
  1271         */
  1272        config Ptr stack = null;
  1273
  1274        /*!
  1275         *  Task stack size in MAUs.
  1276         *
  1277         *  The default value of 0 means that the module config
  1278         *  {@link #defaultStackSize} is used.
  1279         */
  1280        config SizeT stackSize = 0;
  1281
  1282        /*!
  1283         *  Mem section used for statically created task stacks.
  1284         *
  1285         *  Default is inherited from module config defaultStackSection.
  1286         */
  1287        metaonly config String stackSection;
  1288
  1289        /*!
  1290         *  Mem heap used for dynamically created task stack.
  1291         *
  1292         *  The default value of NULL means that the module config
  1293         *  {@link #defaultStackHeap} is used.
  1294         */
  1295        config IHeap.Handle stackHeap = null;
  1296
  1297        /*! Environment data struct. */
  1298        config Ptr env = null;
  1299
  1300        /*!
  1301         *  Exit system immediately when the last task with this
  1302         *  flag set to TRUE has terminated.
  1303         *
  1304         *  Default is true.
  1305         */
  1306        config Bool vitalTaskFlag = true;
  1307
  1308        // -------- Handle Functions --------
  1309
  1310        /*!
  1311         *  @_nodoc
  1312         *  ======== getArg0 ========
  1313         *  Returns arg0 passed via params to create.
  1314         *
  1315         *  @b(returns)     task's arg0
  1316         */
  1317        @DirectCall
  1318        UArg getArg0();
  1319
  1320        /*!
  1321         *  @_nodoc
  1322         *  ======== getArg1 ========
  1323         *  Returns arg1 passed via params to create.
  1324         *
  1325         *  @b(returns)     task's arg1
  1326         */
  1327        @DirectCall
  1328        UArg getArg1();
  1329
  1330        /*!
  1331         *  ======== getEnv ========
  1332         *  Get task environment pointer.
  1333         *
  1334         *  Task_getEnv returns the environment pointer of the specified task. The
  1335         *  environment pointer references an arbitrary application-defined data
  1336         *  structure.
  1337         *
  1338         *  If your program uses multiple hook sets, {@link #getHookContext}
  1339         *  allows you to get environment pointers you have set for a particular
  1340         *  hook set and Task object combination.
  1341         *
  1342         *  @b(returns)     task environment pointer
  1343         */
  1344        @DirectCall
  1345        Ptr getEnv();
  1346
  1347        /*!
  1348         *  ======== getHookContext ========
  1349         *  Get hook set's context for a task.
  1350         *
  1351         *  For example, this C code gets the HookContext, prints it,
  1352         *  and sets a new value for the HookContext.
  1353         *
  1354         *  @p(code)
  1355         *  Ptr pEnv;
  1356         *  Task_Handle myTask;
  1357         *  Int myHookSetId1;
  1358         *
  1359         *  pEnv = Task_getHookContext(task, myHookSetId1);
  1360         *
  1361         *  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
  1362         *                (ULong)pEnv, (ULong)Timestamp_get32());
  1363         *
  1364         *  Task_setHookContext(task, myHookSetId1, (Ptr)0xc0de1);
  1365         *  @p
  1366         *
  1367         *  See {@link #hookfunc Hook Functions} for more details.
  1368         *
  1369         *  @param(id)      hook set ID
  1370         *  @b(returns)     hook set context for task
  1371         */
  1372        @DirectCall
  1373        Ptr getHookContext(Int id);
  1374
  1375        /*!
  1376         *  ======== getPri ========
  1377         *  Get task priority.
  1378         *
  1379         *  Task_getPri returns the priority of the referenced task.
  1380         *
  1381         *  @b(returns)     task priority
  1382         */
  1383        @DirectCall
  1384        Int getPri();
  1385
  1386        /*!
  1387         *  @_nodoc
  1388         *  ======== setArg0 ========
  1389         *  Set arg0 (used primarily for legacy support)
  1390         */
  1391        @DirectCall
  1392        Void setArg0(UArg arg);
  1393
  1394        /*!
  1395         *  @_nodoc
  1396         *  ======== setArg1 ========
  1397         *  Set arg1 (used primarily for legacy support)
  1398         */
  1399        @DirectCall
  1400        Void setArg1(UArg arg);
  1401
  1402        /*!
  1403         *  ======== setEnv ========
  1404         *  Set task environment.
  1405         *
  1406         *  Task_setEnv sets the task environment pointer to env. The
  1407         *  environment pointer references an arbitrary application-defined
  1408         *  data structure.
  1409         *
  1410         *  If your program uses multiple hook sets, {@link #setHookContext}
  1411         *  allows you to set environment pointers for any
  1412         *  hook set and Task object combination.
  1413         *
  1414         *  @param(env)     task environment pointer
  1415         */
  1416        @DirectCall
  1417        Void setEnv(Ptr env);
  1418
  1419        /*!
  1420         *  ======== setHookContext ========
  1421         *  Set hook instance's context for a task.
  1422         *
  1423         *  For example, this C code gets the HookContext, prints it,
  1424         *  and sets a new value for the HookContext.
  1425         *
  1426         *  @p(code)
  1427         *  Ptr pEnv;
  1428         *  Task_Handle myTask;
  1429         *  Int myHookSetId1;
  1430         *
  1431         *  pEnv = Task_getHookContext(task, myHookSetId1);
  1432         *
  1433         *  System_printf("myEnd1: pEnv = 0x%lx, time = %ld\n",
  1434         *                (ULong)pEnv, (ULong)Timestamp_get32());
  1435         *
  1436         *  Task_setHookContext(task, myHookSetId1, (Ptr)0xc0de1);
  1437         *  @p
  1438         *
  1439         *  See {@link #hookfunc Hook Functions} for more details.
  1440         *
  1441         *  @param(id)              hook set ID
  1442         *  @param(hookContext)     value to write to context
  1443         */
  1444        @DirectCall
  1445        Void setHookContext(Int id, Ptr hookContext);
  1446
  1447        /*!
  1448         *  ======== setPri ========
  1449         *  Set a task's priority
  1450         *
  1451         *  Task_setpri sets the execution priority of task to newpri, and returns
  1452         *  that task's old priority value. Raising or lowering a task's priority
  1453         *  does not necessarily force preemption and re-scheduling of the caller:
  1454         *  tasks in the {@link #Mode_BLOCKED} mode remain suspended despite a
  1455         *  change in priority; and tasks in the {@link #Mode_READY} mode gain
  1456         *  control only if their new priority is greater than that of the
  1457         *  currently executing task.
  1458         *
  1459         *  The maximum value of newpri is ({@link #numPriorities} - 1).
  1460         *  The minimum value of newpri is one (1) (The Idle task owns priority 0).
  1461         *  If newpri is less than 0, the task is barred from further execution
  1462         *  until its priority is raised at a later time by another task; if newpri
  1463         *  equals ({@link #numPriorities} - 1), execution of the task effectively
  1464         *  locks out all other program activity, except for the handling of
  1465         *  interrupts.
  1466         *
  1467         *  The current task can change its own priority (and possibly preempt its
  1468         *  execution) by passing the output of {@link #self} as the value of the
  1469         *  task parameter.
  1470         *
  1471         *  A context switch occurs when calling Task_setpri if a currently
  1472         *  running task priority is set lower than the priority of another
  1473         *  currently ready task, or if another ready task is made to have a
  1474         *  higher priority than the currently running task.
  1475         *
  1476         *  Task_setpri can be used for mutual exclusion.
  1477         *
  1478         *  If a task's new priority is different than its previous priority,
  1479         *  then its relative placement in its new ready task priority
  1480         *  queue can be different than the one it was removed from. This can
  1481         *  effect the relative order in which it becomes the running task.
  1482         *
  1483         *  The effected task is placed at the head of its new priority queue
  1484         *  if it is the currently running task. Otherwise it is placed at
  1485         *  at the end of its new task priority queue.
  1486         *
  1487         *  @param(newpri) task's new priority
  1488         *  @b(returns)     task's old priority
  1489         *
  1490         *  @a(constraints)
  1491         *  newpri must be less than or equal to ({@link #numPriorities} - 1).
  1492         *
  1493         *  The task cannot be in the {@link #Mode_TERMINATED} mode.
  1494         *
  1495         *  The new priority should not be zero (0). This priority level is
  1496         *  reserved for the Idle task.
  1497         */
  1498        @DirectCall
  1499        UInt setPri(Int newpri);
  1500
  1501        /*!
  1502         *  ======== stat ========
  1503         *  Retrieve the status of a task.
  1504         *
  1505         *  Task_stat retrieves attribute values and status information about a
  1506         *  task.
  1507         *
  1508         *  Status information is returned through statbuf, which references a
  1509         *  structure of type {@link #Stat}.
  1510         *
  1511         *  When a task is preempted by a software or hardware interrupt, the task
  1512         *  execution mode returned for that task by Task_stat is still
  1513         *  {@link #Mode_RUNNING}  because the task runs when the preemption ends.
  1514         *
  1515         *  The current task can inquire about itself by passing the output of
  1516         *  {@link #self} as the first argument to Task_stat. However, the task
  1517         *  stack pointer (sp) in the {@link #Stat} structure is the value from
  1518         *  the previous context switch.
  1519         *
  1520         *  Task_stat has a non-deterministic execution time. As such, it is not
  1521         *  recommended to call this API from Swis or Hwis.
  1522         *
  1523         *  @param(statbuf) pointer to task status structure
  1524         *
  1525         *  @a(constraints)
  1526         *  statbuf cannot be NULL;
  1527         */
  1528        @DirectCall
  1529        Void stat(Stat *statbuf);
  1530
  1531        /*!
  1532         *  ======== getMode ========
  1533         *  Retrieve the {@link #Mode} of a task.
  1534         */
  1535        @DirectCall
  1536        Mode getMode();
  1537
  1538        /*!
  1539         *  @_nodoc
  1540         *  ======== block ========
  1541         *  Block a task.
  1542         *
  1543         *  Remove a task from its ready list.
  1544         *  The effect of this API is manifest the next time the internal
  1545         *  Task scheduler is invoked.
  1546         *  This can be done directly by embedding the call within a
  1547         *  {@link #disable}/{@link #restore} block.
  1548         *  Otherwise, the effect will be manifest as a result of processing
  1549         *  the next dispatched interrupt, or by posting a Swi, or by falling
  1550         *  through the task function.
  1551         *
  1552         *  @a(constraints)
  1553         *  If called from within a Hwi or a Swi, or main(), there is no need
  1554         *  to embed the call within a {@link #disable}/{@link #restore} block.
  1555         */
  1556        @DirectCall
  1557        Void block();
  1558
  1559        /*!
  1560         *  @_nodoc
  1561         *  ======== unblock ========
  1562         *  Unblock a task.
  1563         *
  1564         *  Place task in its ready list.
  1565         *  The effect of this API is manifest the next time the internal
  1566         *  Task scheduler is invoked.
  1567         *  This can be done directly by embedding the call within a
  1568         *  {@link #disable}/{@link #restore} block.
  1569         *  Otherwise, the effect will be manifest as a result of processing
  1570         *  the next dispatched interrupt, or by posting a Swi, or by falling
  1571         *  through the task function.
  1572         *
  1573         *  @a(constraints)
  1574         *  If called from within a Hwi or a Swi, or main(), there is no need
  1575         *  to embed the call within a {@link #disable}/{@link #restore} block.
  1576         */
  1577        @DirectCall
  1578        Void unblock();
  1579
  1580        /*!
  1581         *  @_nodoc
  1582         *  ======== blockI ========
  1583         *  Block a task.
  1584         *
  1585         *  Remove a task from its ready list.
  1586         *  Must be called within Task_disable/Task_restore block
  1587         *  with interrupts disabled.
  1588         *  This API is meant to be used internally.
  1589         */
  1590        @DirectCall
  1591        Void blockI();
  1592
  1593        /*!
  1594         *  @_nodoc
  1595         *  ======== unblockI ========
  1596         *  Unblock a task.
  1597         *
  1598         *  Place task in its ready list.
  1599         *  Must be called within Task_disable/Task_restore block
  1600         *  with interrupts disabled.
  1601         *  This API is meant to be used internally.
  1602         *
  1603         *  @param(hwiKey) key returned from Hwi_disable()
  1604         */
  1605        @DirectCall
  1606        Void unblockI(UInt hwiKey);
  1607
  1608
  1609    internal:   /* not for client use */
  1610
  1611        /*! Target-specific support functions. */
  1612        proxy SupportProxy inherits ti.sysbios.interfaces.ITaskSupport;
  1613
  1614        /*
  1615         *  ======== schedule ========
  1616         *  Find highest priority ready task and invoke it.
  1617         *
  1618         *  Must be called with interrupts disabled.
  1619         */
  1620        Void schedule();
  1621
  1622        /*
  1623         *  ======== enter ========
  1624         *  Task's initial entry point before entering task function.
  1625         */
  1626        Void enter();
  1627
  1628        /*
  1629         *  ======== sleepTimeout ========
  1630         *  This function is the clock event handler for sleep.
  1631         */
  1632        Void sleepTimeout(UArg arg);
  1633
  1634        /*
  1635         *  ======== postInit ========
  1636         *  finish initializing static and dynamic Tasks
  1637         */
  1638        Int postInit(Object *swi, Error.Block *eb);
  1639
  1640        /*
  1641         *  Number of statically constructed Task objects.
  1642         *  Shouldn't be set directly by the user's
  1643         *  config (it gets set by instance$static$init).
  1644         */
  1645        config UInt numConstructedTasks = 0;
  1646
  1647        /*
  1648         *  ======== allBlockedFunction ========
  1649         *  default function to be called
  1650         */
  1651        Void allBlockedFunction();
  1652
  1653        /*
  1654         *  ======== deleteTerminatedTasksFunc ========
  1655         *  Idle func that deletes the first terminated task it finds
  1656         *  in the queue of dynamically created tasks
  1657         */
  1658        Void deleteTerminatedTasksFunc();
  1659
  1660        /*
  1661         *  Common object used by all blocked tasks to enable Task_delete()
  1662         *  to remove a task from any pend Q it is placed on while blocked.
  1663         */
  1664        struct PendElem {
  1665            Queue.Elem              qElem;
  1666            Task.Handle             task;
  1667            Clock.Handle            clock;
  1668        };
  1669
  1670        struct Instance_State {
  1671            Queue.Elem      qElem;      // Task's readyQ element
  1672            volatile Int    priority;   // Task priority
  1673            UInt            mask;       // curSet mask = 1 << priority
  1674            Ptr             context;    // ptr to Task's saved context
  1675                                        // while not in RUNNING mode.
  1676            Mode            mode;       // READY, BLOCKED, RUNNING, etc
  1677            PendElem        *pendElem;  // ptr to Task, Semaphore, Event,
  1678                                        // or GateMutexPri PendElem
  1679            SizeT           stackSize;  // Task's stack buffer size
  1680            Char            stack[];    // buffer used for Task's stack
  1681            IHeap.Handle    stackHeap;  // Heap to allocate stack from
  1682            FuncPtr         fxn;        // Task function
  1683            UArg            arg0;       // Task function 1st arg
  1684            UArg            arg1;       // Task function 2nd arg
  1685            Ptr             env;        // Task environment pointer
  1686            Ptr             hookEnv[];  // ptr to Task's hook env array
  1687            Bool            vitalTaskFlag; // TRUE = shutdown system if
  1688                                        // last task like this exits
  1689            Queue.Handle    readyQ;     // This Task's readyQ
  1690        };
  1691
  1692        struct Module_State {
  1693            Bool            locked;     // Task scheduler locked flag
  1694            volatile UInt   curSet;     // Bitmask reflects readyQ states
  1695            Bool            workFlag;   // Scheduler work is pending.
  1696                                        // Optimization. Must be set
  1697                                        // whenever readyQs are modified.
  1698            UInt            vitalTasks; // number of tasks with
  1699                                        // vitalTaskFlag = true
  1700            Handle          curTask;    // current Task instance
  1701            Queue.Handle    curQ;       // current Task's readyQ
  1702            Queue.Object    readyQ[];   // Task ready queues
  1703            Queue.Object    inactiveQ;  // Task's with -1 priority
  1704            Queue.Object    terminatedQ;// terminated dynamically created Tasks
  1705            Handle          idleTask;   // Idle Task
  1706            Handle          constructedTasks[]; // array of statically
  1707                                        // constructed Tasks
  1708        };
  1709    }
  1710
  1711    /*
  1712     *  @(#) ti.sysbios.knl; 2, 0, 0, 0,494; 6-15-2011 16:26:17; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
  1713
  1714     */
  1715


module ti.sysbios.rta.Agent

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Agent.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.rta;
    38
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.LoggerBuf;
    41    import xdc.runtime.Log;
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Error;
    44    import xdc.runtime.Diags;
    45    import ti.sysbios.knl.Clock;
    46    import ti.sysbios.knl.Event;
    47
    48    /*!
    49     *  ======== Agent ========
    50     *  The Agent module provides target support for RTA tools
    51     *
    52     *  The Agent consists of a Task, called the "RTA agent", which
    53     *  periodically takes all of the logs from all of the LoggerBuf instances
    54     *  in the system and sends them to the host over the configured transport.
    55     *
    56     *  The agent sends records to the host from one LoggerBuf instance at a
    57     *  time--it will finish one LoggerBuf before moving on to the next one.
    58     *
    59     *  Before sending the records to the host, the agent will copy them into
    60     *  a transfer buffer. The size of this transfer buffer is configurable using
    61     *  the {@link #transferBufferSize} parameter.
    62     *
    63     *  Because the application may generate logs faster than the agent can send
    64     *  them to the host, there is a limit to how many records the agent will send
    65     *  from one LoggerBuf before moving on to the next one. The limit is
    66     *  approximately the size of the LoggerBuf--the Agent will continue to fill
    67     *  and send transfer buffers of records until the number of records sent is
    68     *  >= the LoggerBuf size.
    69     *
    70     *  The rate at which the logs are sent up depends on two configuration
    71     *  parameters, {@link #period} and {@link #agentPriority}. The RTA agent pends
    72     *  on an Event instance until that Event is posted by a Clock instance with
    73     *  the configured {@link #period}. Once the Event is posted, whether the
    74     *  RTA agent will run depends on the system's load as well as the agent's
    75     *  priority relative to other Tasks in the system; therefore the
    76     *  {@link #period} does not guarantee that the Agent will run that often.
    77     *
    78     *  The {@link #configureSystemLog} parameter allows the Agent to automatically
    79     *  configure logging for key SYS/BIOS system modules. This feature is
    80     *  enabled by default.
    81     *
    82     *  The RTA Agent also responds to commands from the host to configure logging
    83     *  dynamically on the target, such as changing modules' diagnostic masks and
    84     *  enabling or disabling loggers.
    85     *
    86     *  @p(html)
    87     *  <h3> Automatic Transport Configuration </h3>
    88     *  @p
    89     *  The RTA Agent requires a data transport to communicate with the host.
    90     *  The Agent will work with any transport which implements the
    91     *  ti.sdo.io.Stream. The Agent can automatically configure itself for one of a
    92     *  list of known transports. See the {@link #transport} configuration
    93     *  parameter.
    94     *
    95     *  @p(html)
    96     *  <h3> Manual Transport Configuration </h3>
    97     *  @p
    98     *  To configure RTA to use a different transport, or to configure the
    99     *  transport yourself, select Transport_USER.
   100     *
   101     *  RTA requires two target-to-host Streams (one for sending up the Log records
   102     *  and another for sending up command responses), and one host-to-target
   103     *  Stream (for receiving commands). The IO stacks for these Streams are
   104     *  configured using the {@link #dataStream}, {@link #commandStream}, and
   105     *  {@link #responseStream} parameters.
   106     *
   107     *  @p(html)
   108     *  <h3> Example Manual Configuration with RTDX </h3>
   109     *  @p
   110     *  The following code can be used as template for a manual configuration of
   111     *  RTA support using RTDX as the transport.
   112     *
   113     *  @p(code)
   114     *  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
   115     *
   116     *  // Bring in RTDX
   117     *  var RtdxModule = xdc.useModule('ti.rtdx.RtdxModule');
   118     *  var RtdxDvr = xdc.useModule('ti.rtdx.driver.RtdxDvr');
   119     *  var DriverTable = xdc.useModule('ti.sdo.io.DriverTable');
   120     *
   121     *  // Add the RTDX Driver
   122     *  var rtdx = RtdxDvr.create();
   123     *  DriverTable.addMeta("/rtdx", rtdx);
   124     *
   125     *  // Configure RTDX
   126     *  RtdxDvr.numInputChannels = 2;
   127     *  RtdxDvr.numOutputChannels = 2;
   128     *
   129     *  RtdxModule.bufferSizeInWords = 4096;
   130     *
   131     *  //Configure Agent to use RTDX
   132     *  Agent.dataStream = "/rtdx0";
   133     *  Agent.commandStream = "/rtdx1";
   134     *  Agent.responseStream = "/rtdx1";
   135     */
   136
   137    module Agent
   138    {
   139        /*!
   140         *  ======== ModuleView ========
   141         *  @_nodoc
   142         */
   143        metaonly struct ModuleView {
   144            UInt        numLoggers;
   145            String      loggers[];
   146            UInt        totalRecordsSent;
   147        }
   148
   149        /*!
   150         *  ======== rovViewInfo ========
   151         *  @_nodoc
   152         */
   153        @Facet
   154        metaonly config ViewInfo.Instance rovViewInfo =
   155            ViewInfo.create({
   156                viewMap: [
   157                            ['Module',   {type: ViewInfo.MODULE,   viewInitFxn: 'viewInitModule', structName: 'ModuleView'}]
   158                ]
   159            });
   160
   161        /*! Logged on every Stream_issue call from the Agent */
   162        config Log.Event LD_recordsSent = {
   163            mask: Diags.USER2,
   164            msg: "LD_recordsSent: Sent %d records from logger [%d] 0x%x"
   165        };
   166
   167        /*! Logged when the Agent receives a command */
   168        config Log.Event LD_cmdRcvd = {
   169            mask: Diags.USER2,
   170            msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
   171        };
   172
   173        /*! Logged when a diags mask is changed */
   174        config Log.Event LD_writeMask = {
   175            mask: Diags.USER2,
   176            msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
   177        };
   178
   179        /*! Assert if logger id in control command is invalid. */
   180        config Assert.Id A_invalidLogger = {
   181            msg: "A_invalidLogger: The logger id %d is invalid."
   182        };
   183
   184        /*! Error raised if Agent receives an invalid command. */
   185        config Error.Id E_badCommand  = {
   186            msg: "E_badCommand: Received invalid command, id: %d."
   187        };
   188
   189        /*!
   190         *  ======== loadLogging ========
   191         *  Enable the Load module event logging.
   192         *
   193         *  If this is false, the events will be disabled and cannot be enabled
   194         *  at runtime (ALWAYS_OFF).
   195         *  If this is true, the events will be enabled and can also be modified
   196         *  at runtime (RUNTIME_ON).
   197         */
   198        metaonly config Bool loadLogging = true;
   199
   200        /*!
   201         *  ======== loadLoggingRuntimeControl ========
   202         *  Specify whether load logging can be enabled / disabled at runtime.
   203         *
   204         *  This determines what diags settings are applied to the module's diags
   205         *  mask. If 'false', the diags bits will be configured as ALWAYS_OFF or
   206         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   207         *  bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
   208         */
   209        metaonly config Bool loadLoggingRuntimeControl = true;
   210
   211        /*!
   212         *  ======== loadLoggerSize ========
   213         *  Size (in MAUs) of logger used for the Load module Log events.
   214         *
   215         *  To specify the size in number of records, instead of MAUs, use the
   216         *  following code:
   217         *
   218         *  @p(code)
   219         *  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
   220         *  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
   221         *
   222         *  // Set the load logger size to 50 records.
   223         *  Agent.loadLoggerSize = 50 * LoggerBuf.Entry.$sizeof();
   224         *
   225         *  // Print the final size to see how much memory is used.
   226         *  print("Load Logger Size (MAUs): " + Agent.loadLoggerSize);
   227         *  @p
   228         */
   229        metaonly config SizeT loadLoggerSize = 512;
   230
   231        /*!
   232         *  ======== loadLoggerBufferSection ========
   233         *  Section to place the Load LoggerBuf's buffer.
   234         */
   235        metaonly config String loadLoggerBufferSection = "[Default]";
   236
   237        /*!
   238         *  ======== mainLogging ========
   239         *  Enable main and non-XDC modules event logging.
   240         */
   241        metaonly config Bool mainLogging = true;
   242
   243        /*!
   244         *  ======== mainLoggingRuntimeControl ========
   245         *  Specify whether main logging can be enabled / disabled at runtime.
   246         *
   247         *  This determines what diags settings are applied to the module's diags
   248         *  mask. If 'false', the diags bits will be configured as ALWAYS_OFF or
   249         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   250         *  bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
   251         */
   252        metaonly config Bool mainLoggingRuntimeControl = true;
   253
   254        /*!
   255         *  ======== mainLoggerSize ========
   256         *  Size (in MAUs) of logger used for main and non-XDC modules Log events.
   257         *
   258         *  To specify the size in number of records, instead of MAUs, use the
   259         *  following code:
   260         *
   261         *  @p(code)
   262         *  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
   263         *  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
   264         *
   265         *  // Set the main logger size to 50 records.
   266         *  Agent.mainLoggerSize = 50 * LoggerBuf.Entry.$sizeof();
   267         *
   268         *  // Print the final size to see how much memory is used.
   269         *  print("Application Logger Size (MAUs): " + Agent.mainLoggerSize);
   270         *  @p
   271         */
   272        metaonly config SizeT mainLoggerSize = 1024;
   273
   274        /*!
   275         *  ======== mainLoggerBufferSection ========
   276         *  Section to place the Main LoggerBuf's buffer.
   277         */
   278        metaonly config String mainLoggerBufferSection = "[Default]";
   279
   280        /*!
   281         *  ======== sysbiosHwiLogging ========
   282         *  Enable SYSBIOS Hwi module's event logging.
   283         */
   284        metaonly config Bool sysbiosHwiLogging = false;
   285
   286        /*!
   287         *  ======== sysbiosHwiLoggingRuntimeControl ========
   288         *  Specify whether Hwi logging can be enabled / disabled at runtime.
   289         *
   290         *  This determines what diags settings are applied to the module's diags
   291         *  mask. If 'false', the diags bits will be configured as ALWAYS_OFF or
   292         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   293         *  bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
   294         */
   295        metaonly config Bool sysbiosHwiLoggingRuntimeControl = false;
   296
   297        /*!
   298         *  ======== sysbiosSwiLogging ========
   299         *  Enable SYSBIOS Swi module's event logging.
   300         */
   301        metaonly config Bool sysbiosSwiLogging = false;
   302
   303        /*!
   304         *  ======== sysbiosSwiLoggingRuntimeControl ========
   305         *  Specify whether Swi logging can be enabled / disabled at runtime.
   306         *
   307         *  This determines what diags settings are applied to the module's diags
   308         *  mask. If 'false', the diags bits will be configured as ALWAYS_OFF or
   309         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   310         *  bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
   311         */
   312        metaonly config Bool sysbiosSwiLoggingRuntimeControl = false;
   313
   314        /*!
   315         *  ======== sysbiosTaskLogging ========
   316         *  Enable SYSBIOS Task module's event logging.
   317         */
   318        metaonly config Bool sysbiosTaskLogging = true;
   319
   320        /*!
   321         *  ======== sysbiosTaskLoggingRuntimeControl ========
   322         *  Specify whether Task logging can be enabled / disabled at runtime.
   323         *
   324         *  This determines what diags settings are applied to the module's diags
   325         *  mask. If 'false', the diags bits will be configured as ALWAYS_OFF or
   326         *  ALWAYS_ON, meaning they can't be changed at runtime. If 'true', the
   327         *  bits will be configured as 'RUNTIME_OFF' or 'RUNTIME_ON'.
   328         */
   329        metaonly config Bool sysbiosTaskLoggingRuntimeControl = true;
   330
   331        /*!
   332         *  ======== sysbiosLoggerSize ========
   333         *  Size (in MAUs) of the logger used for the SYS/BIOS modules' Log events.
   334         *
   335         *  To specify the size in number of records, instead of MAUs, use the
   336         *  following code:
   337         *
   338         *  @p(code)
   339         *  var Agent = xdc.useModule('ti.sysbios.rta.Agent');
   340         *  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
   341         *
   342         *  // Set the SYS/BIOS logger size to 50 records.
   343         *  Agent.sysbiosLoggerSize = 50 * LoggerBuf.Entry.$sizeof();
   344         *
   345         *  // Print the final size to see how much memory is used.
   346         *  print("SYS/BIOS Logger Size (MAUs): " + Agent.sysbiosLoggerSize);
   347         *  @p
   348         */
   349        metaonly config SizeT sysbiosLoggerSize = 4096;
   350
   351        /*!
   352         *  ======== sysbiosLoggerBufferSection ========
   353         *  Section to place the SYS/BIOS LoggerBuf's buffer.
   354         */
   355        metaonly config String sysbiosLoggerBufferSection = "[Default]";
   356
   357        /*!
   358         *  ======== configureSystemLog ========
   359         *  Deprecated.
   360         */
   361        metaonly config Bool configureSystemLog = true;
   362
   363        /*!
   364         *  ======== numSystemRecords ========
   365         *  Deprecated.
   366         */
   367        metaonly config Int numSystemRecords = 64;
   368
   369        /*!
   370         *  ======== configureLoadLog ========
   371         *  Deprecated.
   372         */
   373        metaonly config Bool configureLoadLog = true;
   374
   375        /*!
   376         *  ======== numLoadRecords ========
   377         *  Deprecated.
   378         */
   379        metaonly config Int numLoadRecords = 64;
   380
   381        /*!
   382         *  ======== periodInMs ========
   383         *  Period in milliseconds of the RTA agent Task.
   384         *
   385         *  Configures how often the RTA agent will try to send logs to the host.
   386         *  The RTA agent sleeps by pending on an Event. A Clock instance
   387         *  periodically posts this Event, which in turn readies the RTA agent.
   388         *  This configuration parameter is used to determine the period of the
   389         *  Clock instance. The actual period will be a multiple of Clock ticks,
   390         *  so the period will be at least as long as one Clock tick.
   391         *
   392         *  This value does not guarantee that the RTA agent will run at this
   393         *  rate. Even if the period has expired, the RTA agent will not run until
   394         *  the current running Task has yielded and there are no other higher
   395         *  priority Tasks ready.
   396         *
   397         *  Default is 100ms.
   398         */
   399        metaonly config Int periodInMs = 100;
   400
   401        /*!
   402         *  ======== priority ========
   403         *  Priority of the RTA agent Task.
   404         *
   405         *  Default is 1, the lowest priority.
   406         */
   407        metaonly config Int priority = 1;
   408
   409        /*!
   410         *  ======== agentStackSize ========
   411         *  Agent Task stack size in MAUs.
   412         *
   413         *  The recommended size is 1024 bytes.
   414         */
   415        metaonly config SizeT agentStackSize = 1024;
   416
   417        /*!
   418         *  ======== agentStackSection ========
   419         *  Memory section used for statically allocating Agent Task's stack.
   420         *
   421         *  If this parameter is not set then the Task.defaultStackSection is used.
   422         *  See the Task module for instructions on creating a stack section in
   423         *  a different memory segment.
   424         */
   425        metaonly config String agentStackSection = "[Default]";
   426
   427        /*!
   428         *  ======== transferBufferSize ========
   429         *  Size, in number of records, of the RTA agent's transfer buffer.
   430         *
   431         *  The Agent will first copy records into the transfer buffer, then
   432         *  send the entire transfer buffer to the host.
   433         *
   434         *  The Agent is "double-buffered"; it creates two buffers of the
   435         *  specified size so that one buffer may be filled while the other
   436         *  is being transmitted. This means that the memory footprint of
   437         *  the Agent's transfer buffers will be twice what is specified here.
   438         *
   439         *  Default is 85 records. On c6x targets a Log record is 48 bytes, so on
   440         *  c6x targets this default corresponds to a transfer buffer size just
   441         *  under 4KB. 4KB has been determined to be an optimum transfer size for
   442         *  RTDX.
   443         */
   444        config Int transferBufferSize = 85;
   445
   446        /*!
   447         *  ======== transferBufferSection ========
   448         *  Memory section used for the transfer buffer.
   449         *
   450         *  Default is .transferBufferSection which gets placed into the platform's
   451         *  data memory.
   452         */
   453        metaonly config String transferBufferSection;
   454
   455        /*!
   456         *  @_nodoc
   457         *  ======== addSupportLogger ========
   458         *  Whether to include the SupportLogger module.
   459         *
   460         *  The SupportLogger module logs Task, Swi, and Hwi instance names so
   461         *  that the RTA tool can use their given labels. The default is true so
   462         *  that including the RTA Agent automatically includes the SupportLogger.
   463         *
   464         *  Default is true.
   465         */
   466        metaonly config Bool addSupportLogger = true;
   467
   468        /*!
   469         *  ======== supportControl ========
   470         *  Whether RTA should support a control channel.
   471         *
   472         *  The RTA tools can send control commands down to the target to
   473         *  configure log settings. This parameter enables and disables that
   474         *  control feature.
   475         *
   476         *  Default is true.
   477         */
   478        config Bool supportControl = true;
   479
   480        /*!
   481         *  ======== Transport ========
   482         *  The Transport enum lists the transports which the Agent is able
   483         *  to automatically configure. See the {@link #transport} config parameter.
   484         */
   485        metaonly enum Transport {
   486            Transport_RTDX,  //! RTDX
   487            Transport_STOP_MODE_ONLY, //! Stop Mode Only
   488            Transport_USER  //! User-specified Stream driver.
   489        };
   490
   491        /*!
   492         *  ======== transport ========
   493         *  The Agent can automatically configure RTA for a known data transport.
   494         *
   495         *  If the target does not support any transports, you may use
   496         *  'STOP_MODE_ONLY' to retrieve RTA data when the target is halted.
   497         *
   498         *  If you want to use a transport which is not listed here, you can
   499         *  specify 'USER' and configure the transport for RTA yourself.
   500         */
   501        metaonly config Transport transport = Transport_RTDX;
   502
   503        /*!
   504         *  ======== dataStream ========
   505         *  Stream name to be used for the RTA data stream.
   506         *
   507         *  Currently only RTDX is supported and this value should not be changed.
   508         */
   509        config String dataStream = "/rtdx0";
   510
   511        /*!
   512         *  ======== commandStream ========
   513         *  Stream name to be used for the RTA command stream.
   514         *
   515         *  Currently only RTDX is supported and this value should not be changed.
   516         */
   517        config String commandStream = "/rtdx1";
   518
   519        /*!
   520         *  ======== responseStream ========
   521         *  Stream name to be used for the RTA response stream.
   522         *
   523         *  Currently only RTDX is supported and this value should not be changed.
   524         */
   525        config String responseStream = "/rtdx1";
   526
   527        /*!
   528         *  @_nodoc
   529         *  ======== taskFxn ========
   530         *  Function used for the RTA Agent Task.
   531         *
   532         *  The Agent C code does not contain any references to this function, so
   533         *  this function has been made public and nodoc'd, rather than being made
   534         *  internal, so that it does not fall away in a ROM build.
   535         */
   536        @DirectCall
   537        Void taskFxn(UArg arg0, UArg arg1);
   538
   539        /*!
   540         *  @_nodoc
   541         *  ======== clockFxn ========
   542         *  Function used for the RTA Agent's Clock instance.
   543         *
   544         *  The Agent C code does not contain any references to this function, so
   545         *  this function has been made public and nodoc'd, rather than being made
   546         *  internal, so that it does not fall away in a ROM build.
   547         */
   548        @DirectCall
   549        Void clockFxn(UArg arg0);
   550
   551        /*!
   552         *  @_nodoc
   553         *  ======== idleFxn ========
   554         *  Function used for the RTA Agent in place of a Task.
   555         *
   556         *  The Agent C code does not contain any references to this function, so
   557         *  this function has been made public and nodoc'd, rather than being made
   558         *  internal, so that it does not fall away in a ROM build.
   559         */
   560        @DirectCall
   561        Void idleFxn();
   562
   563    internal:
   564
   565        /* Helper APIs */
   566
   567        /* Flushes a single logger. */
   568        Void flushLogger(LoggerBuf.Handle logger, UInt loggerNum,
   569                         Ptr handleOut);
   570        /* Fills a transfer buffer with records from one logger. */
   571        Bool fillTxBuffer(Char *txBuffer, LoggerBuf.Handle logger,
   572                          UInt loggerNum, Int16 *entries);
   573        /* Transfers the records and logs the transfer. */
   574        Void issueRecords(LoggerBuf.Handle logger, UInt loggerNum,
   575                          Ptr handleOut, Char *buffer, Int16 numRecs);
   576
   577        /* Idle function Helper APIs */
   578
   579        /* Checks for available commands and processes. */
   580        Void pollForCommand(Agent.CommandPacket *pcmd);
   581
   582        /* Checks for available buffers and flushes records. */
   583        Void flushAvailableRecords();
   584
   585        /* Finds the first non-empty logger and flushes it. */
   586        Bool flushNonEmptyLogger(Char *buffer);
   587
   588        /* Control APIs */
   589        Void processCommand(CommandPacket cmd);
   590        Void acknowledgeCmd(ResponsePacket *resp);
   591        Void readMask(ResponsePacket *resp, UArg addr);
   592        Void writeMask(ResponsePacket *resp, UArg addr, UArg val);
   593        Void enableLog(ResponsePacket *resp, UArg log);
   594        Void disableLog(ResponsePacket *resp, UArg log);
   595        Void getCpuSpeed(ResponsePacket *resp);
   596        Void resetLog(ResponsePacket *resp, UArg log);
   597        Void changePeriod(ResponsePacket *resp, UArg period);
   598
   599        /* Command ids */
   600        enum Command {
   601            Command_READ_MASK = 0,
   602            Command_WRITE_MASK = 1,
   603            Command_LOGGER_OFF = 2,
   604            Command_LOGGER_ON = 3,
   605            Command_GET_CPU_SPEED = 4,
   606            Command_RESET_LOGGER = 5,
   607            Command_CHANGE_PERIOD = 6
   608        };
   609
   610        /* Structure of command received from host */
   611        struct CommandPacket {
   612            UArg     cmdId;
   613            UArg     arg0;
   614            UArg     arg1;
   615        }
   616
   617        /* Structure of response packet sent back to host */
   618        struct ResponsePacket {
   619            UArg     cmdId;
   620            UArg     resp0;
   621            UArg     resp1;
   622        }
   623
   624        /*
   625         * Header placed at the beginning of each transfer to indicate which
   626         * logger the data is coming from.
   627         */
   628        struct DataPacketHeader {
   629            UArg    loggerId;
   630            UArg    size;
   631        }
   632
   633        struct Module_State {
   634            LoggerBuf.Handle        loggers[];
   635            UInt                    numLoggers;
   636            Int                     supportLogId;
   637            UInt32                  totalRecordsSent;
   638    //        Stream.Handle           dataStrm;
   639    //        Stream.Handle           cmdStrm;
   640    //        Stream.Handle           respStrm;
   641            Ptr           dataStrm;
   642            Ptr           cmdStrm;
   643            Ptr           respStrm;
   644            UInt32                  transferBufA[];
   645            UInt32                  transferBufB[];
   646
   647            /* Only used by Task */
   648            Event.Handle            event;
   649            Clock.Handle            clock;
   650
   651            /* Only used by Idle function */
   652            Bool                    firstTimeData;
   653            Bool                    firstTimeCmd;
   654            CommandPacket           cmd;
   655            Ptr                     freeBuffer;
   656            UInt                    curLoggerNum;
   657            UInt                    curRecsSent;
   658        };
   659    }
   660    /*
   661     *  @(#) ti.sysbios.rta; 2, 0, 0, 0,298; 6-15-2011 16:26:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   662
   663     */
   664


package ti.sysbios.rta

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     */
    35
    36    /*!
    37     *  ======== ti.sysbios.rta ========
    38     *  Contains modules that provide support for RTA tools in CCS
    39     *
    40     *  In order to use the Real-Time Analysis (RTA) tools in
    41     *  Code Composer Studio, your application must be configured to include
    42     *  support for RTA. SYS/BIOS 6 includes an RTA "Agent" module,
    43     *  {@link ti.sysbios.rta.Agent}, which retrieves Log data from the target
    44     *  and sends it to the host.
    45     */
    46    package ti.sysbios.rta [2,0,0,0] {
    47        module Agent;
    48        module SupportLogger;
    49    }
    50    /*
    51     *  @(#) ti.sysbios.rta; 2, 0, 0, 0,298; 6-15-2011 16:26:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    52
    53     */
    54


module ti.sysbios.rta.SupportLogger

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== SupportLogger.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.rta;
    38
    39    import xdc.runtime.Log;
    40    import xdc.runtime.Diags;
    41    import xdc.runtime.Error;
    42    import ti.sysbios.interfaces.IHwi;
    43    import ti.sysbios.knl.Swi;
    44    import ti.sysbios.knl.Task;
    45
    46    /*!
    47     *  ======== SupportLogger ========
    48     *  The SupportLogger logs Task, Swi, and Hwi instance names so that the
    49     *  RTA tool in CCS 4 may associate the instance handles with their names.
    50     *
    51     *  This logging is done using create hooks. The logs are placed in the
    52     *  SupportLogger's LoggerBuf instance, which is separate from other
    53     *  modules' LoggerBufs so that none of the records are overwritten.
    54     *  The number of entries in the LoggerBuf is configurable through
    55     *  {@link #createLogSize}.
    56     *
    57     *  The SupportLogger is also used to log the Timestamp frequency so that
    58     *  the RTA tool can convert the log event timestamps into seconds. This log
    59     *  occurs during module startup.
    60     */
    61
    62    @ModuleStartup
    63
    64    module SupportLogger {
    65
    66        /*! Logged on Hwi create */
    67        config Log.Event LM_hwiCreate = {
    68            mask: Diags.USER1 | Diags.USER2,
    69            msg: "LM_hwiCreate: hwi: 0x%x, name: %x %x %x %x %x %x %x"
    70        };
    71
    72        /*! Logged on Swi create */
    73        config Log.Event LM_swiCreate = {
    74            mask: Diags.USER1 | Diags.USER2,
    75            msg: "LM_swiCreate: swi: 0x%x, name: %x %x %x %x %x %x %x"
    76        };
    77
    78        /*! Logged on Task create */
    79        config Log.Event LM_taskCreate = {
    80            mask: Diags.USER1 | Diags.USER2,
    81            msg: "LM_taskCreate: task: 0x%x, name: %x %x %x %x %x %x %x"
    82        };
    83
    84        /*! Logged in Module_startup to record Timestamp freq. */
    85        config Log.Event LM_timestampFreq = {
    86            mask: Diags.USER1 | Diags.USER2,
    87            msg: "LM_timestampFreq: Timestamp Frequency hi: %d, lo: %d"
    88        };
    89
    90        /*!
    91         *  ======== createLogSize ========
    92         *  Size of SupportLogger LoggerBuf in records. Allow one record per
    93         *  Task, Swi, and Hwi instance in the system.
    94         */
    95        config Int createLogSize = 32;
    96
    97        /* Create hooks */
    98        @DirectCall
    99        Void hwiCreateHook(IHwi.Handle hwi, Error.Block *eb);
   100        @DirectCall
   101        Void swiCreateHook(Swi.Handle swi, Error.Block *eb);
   102        @DirectCall
   103        Void taskCreateHook(Task.Handle task, Error.Block *eb);
   104
   105    }
   106    /*
   107     *  @(#) ti.sysbios.rta; 2, 0, 0, 0,298; 6-15-2011 16:26:27; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   108
   109     */
   110


package ti.sysbios.syncs

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.syncs ========
    39     *  Contains modules that implement the ISync interface.
    40     *
    41     *  This package contains implementations of {@link xdc.runtime.knl.ISync}
    42     *  that use modules in the {@link ti.sysbios.knl} package for the
    43     *  implementation.
    44     *
    45     */
    46    package ti.sysbios.syncs [2,0,0,0] {
    47        module SyncSem;
    48        module SyncSwi;
    49        module SyncEvent;
    50    }
    51    /*
    52     *  @(#) ti.sysbios.syncs; 2, 0, 0, 0,329; 6-15-2011 16:26:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    53
    54     */
    55


module ti.sysbios.syncs.SyncEvent

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== SyncEvent.xdc ========
    34     *
    35     */
    36
    37    import xdc.rov.ViewInfo;
    38    import xdc.runtime.Assert;
    39
    40    import ti.sysbios.knl.Event;
    41
    42    /*!
    43     *  ======== SyncEvent ========
    44     *  Implements ISync using events.
    45     *
    46     *  Module that implements {@link xdc.runtime.knl.ISync} using
    47     *  {@link ti.sysbios.knl.Event}
    48     *
    49     *  This module uses {@link ti.sysbios.knl.Event#post} to implement
    50     *  {@link xdc.runtime.knl.ISync#signal}
    51     *
    52     *  The implementation of {@link xdc.runtime.knl.ISync#wait} is empty
    53     *  and returns
    54     *  FALSE for timeout, since with events the pend call is made outside.
    55     *
    56     *  Modules like {@link ti.sdo.io.Stream} use an ISync.Handle for
    57     *  selecting the synchronization mechanism. This allows Stream to be
    58     *  independent of the synchronization mechanism.
    59     *
    60     *  An instance of SyncEvent requires an Event.Handle. When given a null
    61     *  Event.Handle, SynEvent will assert.
    62     */
    63
    64    module SyncEvent inherits xdc.runtime.knl.ISync
    65    {
    66
    67        /*!
    68         *  ======== BasicView ========
    69         *  @_nodoc
    70         */
    71        metaonly struct BasicView {
    72            String label;
    73            String EventHandle;
    74            UInt   EventId;
    75            String pendedTask;
    76        }
    77
    78        /*!
    79         *  ======== rovViewInfo ========
    80         *  @_nodoc
    81         */
    82        @Facet
    83        metaonly config ViewInfo.Instance rovViewInfo =
    84            ViewInfo.create({
    85                viewMap: [
    86                [
    87                    'Basic',
    88                    {
    89                        type: ViewInfo.INSTANCE,
    90                        viewInitFxn: 'viewInitBasic',
    91                        structName: 'BasicView'
    92                    }
    93                ],
    94                ]
    95            });
    96
    97        /*!
    98         *  Assert when baseHandle is null
    99         */
   100        config Assert.Id A_nullHandle  = {
   101            msg: "A_nullHandle: Null handle passed to create"
   102        };
   103
   104    instance:
   105        /*!
   106         *  Event handle must be provided.
   107         */
   108        config Event.Handle event = null;
   109
   110        /*! Event id to be when signal() gets invoked. */
   111        config UInt eventId = Event.Id_00;
   112
   113    internal:
   114
   115        /* -------- Internal Structures -------- */
   116        struct Instance_State {
   117            Event.Handle         evt;
   118            UInt                 evtId;
   119        };
   120
   121    }
   122    /*
   123     *  @(#) ti.sysbios.syncs; 2, 0, 0, 0,329; 6-15-2011 16:26:28; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   124
   125     */
   126


module ti.sysbios.syncs.SyncSem

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== SyncSem.xdc ========
    34     *
    35     */
    36
    37    import xdc.rov.ViewInfo;
    38
    39    import ti.sysbios.knl.Semaphore;
    40
    41    /*!
    42     *  ======== SyncSem ========
    43     *  Implements ISyncs using semaphores.
    44     *
    45     *  Module that implements {@link xdc.runtime.knl.ISync} using
    46     *  {@link ti.sysbios.knl.Semaphore}
    47     *
    48     *  This module uses {@link ti.sysbios.knl.Semaphore#pend} to implement
    49     *  {@link xdc.runtime.knl.ISync#wait} and {@link ti.sysbios.knl.Semaphore#post}
    50     *  to implement {@link xdc.runtime.knl.ISync#signal}.
    51     *
    52     *  Modules like {@link ti.sdo.io.Stream} use an ISync.Handle for
    53     *  selecting the synchronization mechanism. This allows Stream to be
    54     *  independent of the synchronization mechanism.
    55     *
    56     *  An instance of SyncSem requires a Semaphore.Handle. When given a null
    57     *  Semaphore.Handle, SynSem will create a Semaphore for its use. Note that
    58     *  the underlying Semaphore has to be binary in nature and initialized as
    59     *  being unavailable.
    60     */
    61
    62    @InstanceFinalize
    63    @InstanceInitError
    64
    65    module SyncSem inherits xdc.runtime.knl.ISync
    66    {
    67
    68        /*!
    69         *  ======== BasicView ========
    70         *  @_nodoc
    71         */
    72        metaonly struct BasicView {
    73            String label;
    74            String SemaphoreHandle;
    75            String pendedTasks[];
    76        }
    77
    78        /*!
    79         *  ======== rovViewInfo ========
    80         *  @_nodoc
    81         */
    82        @Facet
    83        metaonly config ViewInfo.Instance rovViewInfo =
    84            ViewInfo.create({
    85                viewMap: [
    86                    ['Basic', {type: ViewInfo.INSTANCE, viewInitFxn: 'viewInitBasic', structName: 'BasicView'}],
    87                ]
    88            });
    89
    90    instance:
    91
    92        /*!
    93         *  Semaphore handle to be used. When Semaphore.Handle is null SyncSem
    94         *  will create a Semaphore instance.
    95         */
    96        config Semaphore.Handle sem = null;
    97
    98    internal:
    99
   100        /* -------- Internal Structures -------- */
   101        struct Instance_State {
   102            Bool                userSem;
   103            Semaphore.Handle    sem;
   104        };
   105
   106    }
   107    /*
   108     *  @(#) ti.sysbios.syncs; 2, 0, 0, 0,329; 6-15-2011 16:26:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   109
   110     */
   111


module ti.sysbios.syncs.SyncSwi

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== SyncSwi.xdc ========
    34     *
    35     */
    36
    37    import xdc.rov.ViewInfo;
    38    import xdc.runtime.Assert;
    39
    40    import ti.sysbios.knl.Swi;
    41
    42    /*!
    43     *  ======== SyncSwi ========
    44     *  Implements ISync using Swis
    45     *
    46     *  Module that implements {@link xdc.runtime.knl.ISync} using
    47     *  {@link ti.sysbios.knl.Swi}
    48     *
    49     *  This module uses {@link ti.sysbios.knl.Swi#post} to implement
    50     *  {@link xdc.runtime.knl.ISync#signal}
    51     *  The implementation of {@link xdc.runtime.knl.ISync#wait} is empty and
    52     *  returns
    53     *  FALSE for timeout, since Swis are asynchronous in nature.
    54     *
    55     *  Modules like {@link ti.sdo.io.Stream} use an ISync.Handle for
    56     *  selecting the synchronization mechanism. This allows Stream to be
    57     *  independent of the synchronization mechanism.
    58     *
    59     *  An instance of SyncSwi requires an Swi.Handle. When given a null
    60     *  Swi.Handle, SynSwi will assert.
    61     */
    62
    63    module SyncSwi inherits xdc.runtime.knl.ISync
    64    {
    65
    66        /*!
    67         *  ======== BasicView ========
    68         *  @_nodoc
    69         */
    70        metaonly struct BasicView {
    71            String label;
    72            String SwiHandle;
    73            String fxn[];
    74        }
    75
    76        /*!
    77         *  ======== rovViewInfo ========
    78         *  @_nodoc
    79         */
    80        @Facet
    81        metaonly config ViewInfo.Instance rovViewInfo =
    82            ViewInfo.create({
    83                viewMap: [
    84                [
    85                    'Basic',
    86                    {
    87                        type: ViewInfo.INSTANCE,
    88                        viewInitFxn: 'viewInitBasic',
    89                        structName: 'BasicView'
    90                    }
    91                ],
    92                ]
    93            });
    94
    95        /*!
    96         *  Assert when baseHandle is null
    97         */
    98        config Assert.Id A_nullHandle  = {
    99            msg: "A_nullHandle: Null handle passed to create"
   100        };
   101
   102    instance:
   103
   104        /*!
   105         *  Swi handle to be used.
   106         */
   107        config Swi.Handle swi = null;
   108
   109    internal:
   110
   111        /* -------- Internal Structures -------- */
   112        struct Instance_State {
   113            Swi.Handle         swi;
   114        };
   115
   116    }
   117    /*
   118     *  @(#) ti.sysbios.syncs; 2, 0, 0, 0,329; 6-15-2011 16:26:29; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   119
   120     */
   121


package ti.sysbios.timers

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.timer ========
    39     *  Contains various timer modules
    40     *
    41     *  This package contains Timer modules that manage the timer peripherals
    42     *  available on various devices.  For the IDs, names, and base addresses of
    43     *  supported devices, see the following Timer Mapping Tables:
    44     *  @p(blist)
    45     *  - {@link ./dmtimer/doc-files/TimerTables.html DMTimer Timer Mapping Table}
    46     *  - {@link ./gptimer/doc-files/TimerTables.html GPTimer Timer Mapping Table}
    47     *  - {@link ./timer64/doc-files/TimerTables.html Timer64 Timer Mapping Table}
    48     *  @p
    49     *  The Timer modules let you use and configure various timers that exist
    50     *  on a particular device. This is achieved by specifying a timer ID when
    51     *  calling Timer_create().
    52     *
    53     *  By default, the {@link ti.sysbios.knl.Clock} module statically configures
    54     *  a {@link ti.sysbios.hal.Timer}
    55     *  timer instance to provide the periodic 1 ms tick interrupt. If you
    56     *  want to use a custom configured timer for the Clock module's tick source,
    57     *  use the following example configuration as a guide:
    58     *
    59     *  @p(code)
    60     *  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
    61     *
    62     *  // Tell the Clock module that YOU are providing the periodic interrupt
    63     *  Clock.tickSource = Clock.TickSource_USER;
    64     *
    65     *  // this example uses the ti.sysbios.timers.dmtimer.Timer module
    66     *  var Timer = xdc.useModule('ti.sysbios.timers.dmtimer.Timer');
    67     *
    68     *  // create a dmtimer config parameter object
    69     *  var timerParams = new Timer.Params();
    70     *
    71     *  // make sure you set the period to 1000 us (1ms)
    72     *  timerParams.period = 1000;
    73     *
    74     *  // custom dmtimer config parameters here...
    75     *  timerParams.twer.ovf_wup_ena = 1;
    76     *
    77     *  // Create the timer.
    78     *  // This example uses timer id 3.
    79     *  // The timer interrupt handler must be set to 'Clock.tick'.
    80     *  Timer.create(3, Clock.tick, timerParams);
    81     *  @p
    82     */
    83    package ti.sysbios.timers [2,0,0,0] {
    84    }
    85    /*
    86     *  @(#) ti.sysbios.timers; 2, 0, 0, 0,114; 6-15-2011 16:26:25; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    87
    88     */
    89


package ti.sysbios.timers.dmtimer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.timer.dmtimer ========
    41     *  Contains specifications for the DMTimer.
    42     *
    43     */
    44    package ti.sysbios.timers.dmtimer [2,0,0,0] {
    45        module Timer;
    46        module TimestampProvider;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.timers.dmtimer; 2, 0, 0, 0,200; 6-15-2011 16:26:37; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.timers.dmtimer.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.timers.dmtimer;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Types;
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.hal.Hwi;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripheral Manager.
    50     *
    51     *  This Timer module manages the Dual Mode timer (dmtimer) peripherals
    52     *  available on the ARM and C6000 devices (see
    53     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables} for supported
    54     *  device information).
    55     *
    56     *  The dmtimer Timer module supports the timer in 'one shot', 'continuous',
    57     *  and 'dynamic' modes.
    58     *
    59     *  In 'one shot' mode, a timer function will "fire" (run) when the timer period
    60     *  expires (counts up to zero). In 'one shot' mode this will only happen
    61     *  once.
    62     *
    63     *  In 'continuous' mode, the specified timer function will "fire" every
    64     *  time the period expires, throughout the lifetime of the program.  When the
    65     *  period expires in 'continuous mode', the period is then reset to its
    66     *  original value and then begins counting up to zero again.  At this point
    67     *  the timer function will fire again and the cycle repeats itself.
    68     *
    69     *  In 'dynamic' mode, the specified timer function will "fire" every
    70     *  time the period expires.  But the period of the timer can be changed
    71     *  dynamically, to correspond to the next tick interrupt needed from the
    72     *  timer.  The timer will continually count upwards, and the timer's compare
    73     *  mode is used to generate an interrupt when a specific threshold count is
    74     *  reached.  This mode is used by the SYS/BIOS Clock module, for implementing
    75     *  dynamic tick suppression, which reduces the number of interrupts from the
    76     *  timer to the minimum required for currently scheduled timeouts.
    77     *
    78     *  @p(html)
    79     *  <h3> Calling Context </h3>
    80     *  <table border="1" cellpadding="3">
    81     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    82     *  </colgroup>
    83     *
    84     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    85     *  <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    86     *    <!--                                                          -->
    87     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    88     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    89     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    90     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    91     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
    92     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
    94     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    95     *    <tr><td> {@link #create}                  </td><td>   N    </td>
    96     *  <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    97     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
    98     *  <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    99     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
   100     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   101     *    <tr><td> {@link #getCount}                </td><td>   Y    </td>
   102     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   103     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
   104     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   105     *    <tr><td> {@link #getFunc}                 </td><td>   Y    </td>
   106     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   107     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
   108     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   109     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td>
   110     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   111     *    <tr><td> {@link #setFunc}                 </td><td>   Y    </td>
   112     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   113     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   114     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   115     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   116     *  <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   117     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   118     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   119     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   120     *  <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   121     *    <tr><td colspan="6"> Definitions: <br />
   122     *       <ul>
   123     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   124     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   125     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   126     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   127     *           <ul>
   128     *             <li> In your module startup after this module is started
   129     *  (e.g. Timer_Module_startupDone() returns TRUE). </li>
   130     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   131     *             <li> During main().</li>
   132     *             <li> During BIOS.startupFxns.</li>
   133     *           </ul>
   134     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   135     *           <ul>
   136     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   137     *             <li> In your module startup before this module is started
   138     *  (e.g. Timer_Module_startupDone() returns FALSE).</li>
   139     *           </ul>
   140     *       </ul>
   141     *    </td></tr>
   142     *
   143     *  </table>
   144     *  @p
   145     *
   146     *  @p(html)
   147     *  <h3> Timer Mapping Tables </h3>
   148     *  <p>
   149     *  The Timer module allows the user to use and configure the various timers
   150     *  that exist on a particular device.  This is achieved by specifying a timer
   151     *  ID when calling {@link ti.sysbios.hal.Timer#Timer_create}.
   152     *  However, the timer ID
   153     *  specified may not always map to that timer; for example, specifying an ID
   154     *  value of 1 does not necessarily mean that this will map to "GPTimer1".
   155     *  These tables are provided to show which timers map to which timer IDs.
   156     *  </p>
   157     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables}
   158     *  @p
   159     */
   160    @InstanceFinalize       /* To cleanup */
   161    @InstanceInitError      /* To report unavailability of timer */
   162    @ModuleStartup          /* to configure static timers */
   163
   164    module Timer inherits ti.sysbios.interfaces.ITimer
   165    {
   166        /*! override supportsDynamic - this Timer does support RunMode_DYNAMIC */
   167        override metaonly config Bool supportsDynamic = true;
   168
   169        /*! Max value of Timer period for PeriodType_COUNTS*/
   170        const UInt MAX_PERIOD = 0xffffffff;
   171
   172        /*! L4 interface Configuration Register (TIOCP_CFG). */
   173        struct TiocpCfg {
   174            Bits8 idlemode;  /*! 0=force-idle;1=no-idle;2=Smart-idle;3=Smart-idle */
   175            Bits8 emufree;   /*! 0=counter frozen; 1=counter free-running */
   176            Bits8 softreset; /*! 0=normal mode; 1=soft reset */
   177        };
   178
   179        /*! Interrupt Enable Register (TIER). */
   180        struct Tier {
   181            Bits8 mat_it_ena;  /*! Enable match interrupt */
   182            Bits8 ovf_it_ena;  /*! Enable overflow interrupt */
   183            Bits8 tcar_it_ena; /*! Enable capture interrupt */
   184        };
   185
   186        /*! WakepUp Enable Register (TWER). */
   187        struct Twer {
   188            Bits8 mat_wup_ena;  /*! Enable match wake-up */
   189            Bits8 ovf_wup_ena;  /*! Enable overflow wake-up */
   190            Bits8 tcar_wup_ena; /*! Enable capture wake-up */
   191        };
   192
   193        /*! Control Register (TCLR). */
   194        struct Tclr {
   195            Bits32 ptv; /*! Trigger output mode */
   196            Bits8 pre;  /*! Prescalar enable */
   197            Bits8 ce;   /*! Compare enable */
   198            Bits8 scpwm;/*! Pulse-width modulation */
   199            Bits16 tcm; /*! Transition capture mode */
   200            Bits16 trg; /*! Trigger output mode */
   201            Bits8 pt;   /*! Pulse or toggle select bit */
   202            Bits8 captmode; /*! Capture mode select bit */
   203            Bits8 gpocfg; /*! PWM output/event detection input pin */
   204        };
   205
   206        /*! L4 Interface Synchronization Control Register (TSICR). */
   207        struct Tsicr {
   208            Bits8 sft;    /*! Reset software functional registers */
   209            Bits8 posted; /*! Posted mode selection */
   210        };
   211
   212        /*! Timer Settings. */
   213        metaonly struct TimerSetting {
   214            Bool master;    /*! specifies whether this is the master */
   215            Ptr baseAddr;   /*! specify the base address  */
   216            Int intNum;     /*! specify which interrupt vector */
   217            String name;    /*! specify the timer name */
   218        };
   219
   220        /*! @_nodoc */
   221        metaonly struct BasicView {
   222            Ptr         halTimerHandle;
   223            String      label;
   224            UInt        id;
   225            String      name;
   226            String      startMode;
   227            String      runMode;
   228            UInt        period;
   229            String      periodType;
   230            UInt        intNum;
   231            String      tickFxn[];
   232            UArg        arg;
   233            String      extFreqLow;
   234            String      extFreqHigh;
   235            String      hwiHandle;
   236        };
   237
   238
   239        /*! @_nodoc */
   240        metaonly struct ModuleView {
   241            String          availMask;      /* avaliable 32-bit timer halves */
   242            String intFrequency;    /* internal frequency in Hz */
   243        }
   244
   245        @Facet
   246        metaonly config ViewInfo.Instance rovViewInfo =
   247            ViewInfo.create({
   248                viewMap: [
   249                [
   250                    'Basic',
   251                    {
   252                        type: ViewInfo.INSTANCE,
   253                        viewInitFxn: 'viewInitBasic',
   254                        structName: 'BasicView'
   255                    }
   256                ],
   257                [
   258                    'Module',
   259                    {
   260                        type: ViewInfo.MODULE,
   261                        viewInitFxn: 'viewInitModule',
   262                        structName: 'ModuleView'
   263                    }
   264                ],
   265                ]
   266            });
   267
   268        /*!
   269         *  Error raised when timer id specified is not supported.
   270         */
   271        config Error.Id E_invalidTimer = {
   272            msg: "E_invalidTimer: Invalid Timer Id %d"
   273        };
   274
   275        /*!
   276         *  Error raised when timer requested is in use
   277         */
   278        config Error.Id E_notAvailable  = {
   279            msg: "E_notAvailable: Timer not available %d"
   280        };
   281
   282        /*!
   283         *  Error raised when period requested is not supported
   284         */
   285        config Error.Id E_cannotSupport = {
   286            msg: "E_cannotSupport: Timer cannot support requested period %d"
   287        };
   288
   289        /*!
   290         *  ======== anyMask ========
   291         *  Available mask to be used when select = Timer_ANY. Set in xs file.
   292         */
   293        config Bits32 anyMask;
   294
   295        /*!
   296         *  ======== timerSettings ========
   297         *  Global Control configuration for each physical timer.
   298         */
   299        metaonly config TimerSetting timerSettings[] = [];
   300
   301        /*!
   302         *  ======== intFreq ========
   303         *  Internal frequency for Timer
   304         */
   305        metaonly config Types.FreqHz intFreq = {lo: 0, hi: 0};
   306
   307        /*!
   308         *  ======== stub  ========
   309         *  @_nodoc
   310         *  Timer requires acknowledgement
   311         *
   312         *  @param(arg)     timer object passed in as argument.
   313         */
   314        @DirectCall
   315        Void stub(UArg arg);
   316
   317        /*!
   318         *  ======== dynStub  ========
   319         *  @_nodoc
   320         *  Acknowledges timer interrupt and sets next threshold for interrupt.
   321         *
   322         *  @param(arg)     timer object passed in as argument.
   323         */
   324        @DirectCall
   325        Void dynStub(UArg arg);
   326
   327    instance:
   328
   329        /*!
   330         *  ======== tiocpCfg ========
   331         */
   332        config TiocpCfg tiocpCfg = {idlemode: 0, emufree: 0, softreset: 1};
   333
   334        /*!
   335         *  ======== tier ========
   336         */
   337        config Tier tier = {mat_it_ena: 0, ovf_it_ena: 1, tcar_it_ena: 0};
   338
   339        /*!
   340         *  ======== twer ========
   341         */
   342        config Twer twer = {mat_wup_ena: 0, ovf_wup_ena: 0, tcar_wup_ena: 0};
   343
   344        /*!
   345         *  ======== tclr ========
   346         */
   347        config Tclr tclr = {ptv: 0, pre: 0, ce: 0, scpwm: 0, tcm: 0, trg: 0,
   348            pt: 0, captmode: 0, gpocfg: 0};
   349
   350        /*!
   351         *  ======== tsicr ========
   352         */
   353        config Tsicr tsicr = {sft: 0, posted: 1};
   354
   355        /*!
   356         *  ======== tmar ========
   357         */
   358        config UInt32 tmar = 0;
   359
   360        /*! Hwi Params for Hwi Object. Default is null. */
   361        config Hwi.Params *hwiParams = null;
   362
   363        /*!
   364         *  ======== reconfig ========
   365         *  Used to modify static timer instances at runtime.
   366         *
   367         *  @param(timerParams)     timer Params
   368         *  @param(tickFxn)         functions that runs when timer expires
   369         */
   370        @DirectCall
   371        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   372
   373        /*!
   374         *  ======== getRollovers  ========
   375         *  @_nodoc
   376         *  Returns the total number of timer rollovers since the timer was
   377         *  started.  This API is used internally for implementing timestamping
   378         *  when the timer is shared with Clock, and running with RunMode_DYNAMIC.
   379         *  It has no other intended purpose.
   380         *
   381         *  @b(returns)     number of rollovers since timer was started
   382         */
   383        @DirectCall
   384        UInt32 getRollovers();
   385
   386        /*!
   387         *  ======== enableTimestamping  ========
   388         *  @_nodoc
   389         *  Enables the timer to be used for timestamping purposes.  This API is
   390         *  used internally for enabling timestamping when the timer is shared with
   391         *  Clock, and running with RunMode_DYNAMIC. It has no other intended
   392         *  purpose.
   393         *
   394         */
   395        @DirectCall
   396        Void enableTimestamping();
   397
   398    internal:   /* not for client use */
   399
   400        /*! Device-specific Timer implementation. */
   401        proxy TimerSupportProxy inherits ti.sysbios.interfaces.ITimerSupport;
   402
   403        /*!
   404         *  ======== startupNeeded ========
   405         *  This flag is use to prevent Timer_startup code (includes postInit(),
   406         *  deviceConfig(), initDevice() to be brought in un-necessarily.
   407         */
   408        config Bool startupNeeded = false;
   409
   410        /*! Information about timer */
   411        struct TimerDevice {
   412            UInt intNum;
   413            UInt eventId;
   414            Ptr  baseAddr;
   415        };
   416
   417        /*!
   418         *  ======== numTimerDevices ========
   419         *  The number of logical timers on a device.
   420         */
   421        config Int numTimerDevices;
   422
   423        /*!
   424         *  ======== spinLoop ========
   425         *  used by trigger function.
   426         */
   427        Void spinLoop(UInt count);
   428
   429        /*! Instance state structure */
   430        struct Instance_State {
   431            Bool                    staticInst;     /* statically created or not */
   432            Int                     id;             /* logical timer id. */
   433            UInt                    tiocpCfg;
   434            UInt                    tmar;
   435            UInt                    tier;
   436            UInt                    twer;
   437            UInt                    tclr;
   438            UInt                    tsicr;
   439            ITimer.RunMode          runMode;        /* timer mode */
   440            ITimer.StartMode        startMode;      /* timer mode */
   441            UInt                    period;         /* period */
   442            ITimer.PeriodType       periodType;     /* type (microsecs, inst) */
   443            UInt                    intNum;         /* intr num */
   444            UArg                    arg;            /* isrFxn arg */
   445            Hwi.FuncPtr             tickFxn;        /* Timer fxn plugged into Hwi */
   446            Types.FreqHz            extFreq;        /* ext freq */
   447            Hwi.Handle              hwi;            /* hwi inst */
   448            UInt                    prevThreshold;  /* previous interrupt thresh */
   449            UInt                    rollovers;      /* total timer rollovers */
   450        }
   451
   452        /*! Module state structure */
   453        struct Module_State {
   454            Bits32          availMask;      /* avaliable 32-bit timer halves */
   455            Types.FreqHz    intFreq;        /* internal frequency in Hz */
   456            TimerDevice     device[];       /* timer device information */
   457            Handle          handles[];      /* handles based on logical id */
   458        }
   459    }
   460    /*
   461     *  @(#) ti.sysbios.timers.dmtimer; 2, 0, 0, 0,200; 6-15-2011 16:26:36; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   462
   463     */
   464


module ti.sysbios.timers.dmtimer.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.timers.dmtimer;
    39
    40    /*!
    41     *  ======== TimestampProvider ========
    42     *
    43     *  @p(html)
    44     *  <h3> Calling Context </h3>
    45     *  <table border="1" cellpadding="3">
    46     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    47     *
    48     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main**  </th><th>  Startup***  </th></tr>
    49     *    <!--                                                                                                                 -->
    50     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    51     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    52     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    53     *
    54     *  </table>
    55     *  @p
    56     */
    57
    58    @ModuleStartup          /* To get Clock Timer Handle */
    59
    60    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    61    {
    62        /*!
    63         *  ======== timerId ========
    64         *  TimestampProvider timer id
    65         *
    66         *  A value of {@link Timer#ANY Timer.ANY} (-1) indicates any timer is ok.
    67         */
    68        config UInt timerId = Timer.ANY;
    69
    70        /*!
    71         *
    72         *  ======== useClockTimer ========
    73         *  Use the same timer as Clock
    74         *
    75         *  Set this parameter when you want TimestampProvider is use the same
    76         *  timer as the BIOS {@link ti.sysbios.knl.Clock Clock} module.
    77         *
    78         *  This parameter overrides the {@link #timerId timeId} setting.
    79         */
    80        config Bool useClockTimer;
    81
    82        /*!
    83         *  ======== startTimer ========
    84         *  Function that starts timer before main
    85         *
    86         *  @_nodoc Internal use.
    87         */
    88        Void startTimer();
    89
    90        /*!
    91         *  ======== rolloverFunc ========
    92         *  Timer rollover interrupt handler
    93         *
    94         *  @_nodoc Internal use.
    95         */
    96        Void rolloverFunc(UArg unused);
    97
    98    internal:   /* not for client use */
    99
   100        struct Module_State {
   101            Timer.Handle    timer;          /* timer instance used */
   102            volatile UInt32 rollovers;      /* timer rollover counts */
   103        }
   104    }
   105    /*
   106     *  @(#) ti.sysbios.timers.dmtimer; 2, 0, 0, 0,200; 6-15-2011 16:26:37; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   107
   108     */
   109


package ti.sysbios.timers.gptimer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.timer.gptimer ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.timers.gptimer [2,0,0,0] {
    45        module Timer;
    46    }
    47    /*
    48     *  @(#) ti.sysbios.timers.gptimer; 2, 0, 0, 0,324; 6-15-2011 16:26:39; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    49
    50     */
    51


module ti.sysbios.timers.gptimer.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.timers.gptimer;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Types;
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.hal.Hwi;
    46
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripheral Manager.
    50     *
    51     *  This Timer module manages the general purpose timer (gptimer) peripherals
    52     *  available on the ARM and C6000 devices (see
    53     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables} for supported
    54     *  device information).
    55     *
    56     *  The gptimer Timer  module supports the timer in 'one shot' and 'continuous'
    57     *  modes.
    58     *
    59     *  In 'one shot' mode, a timer function will "fire" (run) when the timer period
    60     *  expires (counts down to zero). In 'one shot' mode this will only happen
    61     *  once.  In 'continuous' mode, the specified timer function will "fire" every
    62     *  time the period expires, throughout the lifetime of the program.  When the
    63     *  period expires in 'continuous mode', the period is then reset to its
    64     *  original value and then begins counting down to zero again.  At this point
    65     *  the timer function will fire again and the cycle repeats itself.
    66     *
    67     *  @p(html)
    68     *  <h3> Calling Context </h3>
    69     *  <table border="1" cellpadding="3">
    70     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    71     *    </colgroup>
    72     *
    73     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    74     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    75     *    <!--                                    -->
    76     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    77     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
    81     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
    83     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #create}                  </td><td>   N    </td>
    85     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
    87     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
    89     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #getCount}                </td><td>   Y    </td>
    91     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
    93     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #getFunc}                 </td><td>   Y    </td>
    95     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
    97     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td>
    99     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   100     *    <tr><td> {@link #setFunc}                 </td><td>   Y    </td>
   101     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   103     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   105     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   107     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   109     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   110     *    <tr><td colspan="6"> Definitions: <br />
   111     *       <ul>
   112     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   113     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   114     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   115     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   116     *           <ul>
   117     *             <li> In your module startup after this module is started
   118     *    (e.g. Timer_Module_startupDone() returns TRUE). </li>
   119     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   120     *             <li> During main().</li>
   121     *             <li> During BIOS.startupFxns.</li>
   122     *           </ul>
   123     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   124     *           <ul>
   125     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   126     *             <li> In your module startup before this module is started
   127     *    (e.g. Timer_Module_startupDone() returns FALSE).</li>
   128     *           </ul>
   129     *       </ul>
   130     *    </td></tr>
   131     *
   132     *  </table>
   133     *  @p
   134     *
   135     *  @p(html)
   136     *  <h3> Timer Mapping Tables </h3>
   137     *  <p>
   138     *  The Timer module allows the user to use and configure the various timers
   139     *  that exist on a particular device.  This is achieved by specifying a timer
   140     *  ID when calling {@link ti.sysbios.hal.Timer#Timer_create}.
   141     *  However, the timer ID
   142     *  specified may not always map to that timer; for example, specifying an ID
   143     *  value of 1 does not necessarily mean that this will map to "GPTimer1".
   144     *  These tables are provided to show which timers map to which timer IDs.
   145     *  </p>
   146     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables}
   147     *  @p
   148     *
   149     */
   150    @InstanceFinalize       /* To cleanup */
   151    @InstanceInitError      /* To report unavailability of timer */
   152    @ModuleStartup          /* to configure static timers */
   153
   154    module Timer inherits ti.sysbios.interfaces.ITimer
   155    {
   156        /*! Max value of Timer period for PeriodType_COUNTS*/
   157        const UInt MAX_PERIOD = 0xffffffff;
   158
   159        /*! L4 interface Configuration Register (TIOCP_CFG). */
   160        struct TiocpCfg {
   161            Bits8 autoidle;  /*! 0=L4 interface is free running; 1=Automatic */
   162            Bits8 softreset; /*! 0=normal mode; 1=soft reset */
   163            Bits8 enawakeup; /*! 0=no wakeup; 1=wake-up line assertion enabled */
   164            Bits16 idlemode; /*! 0=force-idle; 1=no-idle; 2=Smart-idle */
   165            Bits8 emufree;   /*! 0=counter frozen; 1=counter free-running */
   166            Bits16 clockactivity; /*! Clock activity during wakeup mode period */
   167        };
   168
   169        /*! Interrupt Enable Register (TIER). */
   170        struct Tier {
   171            Bits8 mat_it_ena;  /*! Enable match interrupt */
   172            Bits8 ovf_it_ena;  /*! Enable overflow interrupt */
   173            Bits8 tcar_it_ena; /*! Enable capture interrupt */
   174        };
   175
   176        /*! WakepUp Enable Register (TWER). */
   177        struct Twer {
   178            Bits8 mat_wup_ena;  /*! Enable match wake-up */
   179            Bits8 ovf_wup_ena;  /*! Enable overflow wake-up */
   180            Bits8 tcar_wup_ena; /*! Enable capture wake-up */
   181        };
   182
   183        /*! Control Register (TCLR). */
   184        struct Tclr {
   185            Bits32 ptv; /*! Trigger output mode */
   186            Bits8 pre;  /*! Prescalar enable */
   187            Bits8 ce;   /*! Compare enable */
   188            Bits8 scpwm;/*! Pulse-width modulation */
   189            Bits16 tcm; /*! Transition capture mode */
   190            Bits16 trg; /*! Trigger output mode */
   191            Bits8 pt;   /*! Pulse or toggle select bit */
   192            Bits8 captmode; /*! Capture mode select bit */
   193            Bits8 gpocfg; /*! PWM output/event detection input pin */
   194        };
   195
   196        /*! L4 Interface Synchronization Control Register (TSICR). */
   197        struct Tsicr {
   198            Bits8 sft;    /*! Reset software functional registers */
   199            Bits8 posted; /*! Posted mode selection */
   200        };
   201
   202        /*! Timer Settings. */
   203        metaonly struct TimerSetting {
   204            Bool master;    /*! specifies whether this is the master */
   205            Ptr baseAddr;   /*! specify the base address  */
   206            Int intNum;     /*! specify which interrupt vector */
   207        };
   208
   209        /*!
   210         *  ======== BasicView ========
   211         *  @_nodoc
   212         */
   213        metaonly struct BasicView {
   214            Ptr         halTimerHandle;
   215            String      label;
   216            UInt        id;
   217            String      startMode;
   218            String      runMode;
   219            UInt        period;
   220            String      periodType;
   221            UInt        intNum;
   222            String      tickFxn[];
   223            UArg        arg;
   224            String      extFreqLow;
   225            String      extFreqHigh;
   226            String      hwiHandle;
   227        };
   228
   229
   230        /*!
   231         *  ======== ModuleView ========
   232         *  @_nodoc
   233         */
   234        metaonly struct ModuleView {
   235            String          availMask;      /* avaliable 32-bit timer halves */
   236            String intFrequency;    /* internal frequency in Hz */
   237        }
   238
   239        /*!
   240         *  ======== rovViewInfo ========
   241         *  @_nodoc
   242         */
   243        @Facet
   244        metaonly config ViewInfo.Instance rovViewInfo =
   245            ViewInfo.create({
   246                viewMap: [
   247                [
   248                    'Basic',
   249                    {
   250                        type: ViewInfo.INSTANCE,
   251                        viewInitFxn: 'viewInitBasic',
   252                        structName: 'BasicView'
   253                    }
   254                ],
   255                [
   256                    'Module',
   257                    {
   258                        type: ViewInfo.MODULE,
   259                        viewInitFxn: 'viewInitModule',
   260                        structName: 'ModuleView'
   261                    }
   262                ],
   263                ]
   264            });
   265
   266        /*!
   267         *  Error raised when timer id specified is not supported.
   268         */
   269        config Error.Id E_invalidTimer = {
   270            msg: "E_invalidTimer: Invalid Timer Id %d"
   271        };
   272
   273        /*!
   274         *  Error raised when timer requested is in use
   275         */
   276        config Error.Id E_notAvailable  = {
   277            msg: "E_notAvailable: Timer not available %d"
   278        };
   279
   280        /*!
   281         *  Error raised when period requested is not supported
   282         */
   283        config Error.Id E_cannotSupport = {
   284            msg: "E_cannotSupport: Timer cannot support requested period %d"
   285        };
   286
   287        /*!
   288         *  ======== anyMask ========
   289         *  Available mask to be used when select = Timer_ANY. Set in xs file.
   290         */
   291        config Bits32 anyMask;
   292
   293        /*!
   294         *  ======== timerSettings ========
   295         *  Global Control configuration for each physical timer.
   296         */
   297        metaonly config TimerSetting timerSettings[] = [];
   298
   299        /*!
   300         *  ======== intFreq ========
   301         *  Internal frequency for Timer
   302         */
   303        metaonly config Types.FreqHz intFreq = {lo: 0, hi: 0};
   304
   305        /*!
   306         *  ======== stub  ========
   307         *  @_nodoc
   308         *  Timer requires acknowledgement
   309         *
   310         *  @param(arg)     timer object passed in as argument.
   311         */
   312        @DirectCall
   313        Void stub(UArg arg);
   314
   315
   316    instance:
   317
   318        /*!
   319         *  ======== tiocpCfg ========
   320         */
   321        config TiocpCfg tiocpCfg = {autoidle: 0, softreset: 1, enawakeup: 0,
   322            idlemode: 0, emufree: 0, clockactivity: 0};
   323
   324        /*!
   325         *  ======== tier ========
   326         */
   327        config Tier tier = {mat_it_ena: 0, ovf_it_ena: 1, tcar_it_ena: 0};
   328
   329        /*!
   330         *  ======== twer ========
   331         */
   332        config Twer twer = {mat_wup_ena: 0, ovf_wup_ena: 0, tcar_wup_ena: 0};
   333
   334        /*!
   335         *  ======== tclr ========
   336         */
   337        config Tclr tclr = {ptv: 0, pre: 0, ce: 0, scpwm: 0, tcm: 0, trg: 0,
   338            pt: 0, captmode: 0, gpocfg: 0};
   339
   340        /*!
   341         *  ======== tsicr ========
   342         */
   343        config Tsicr tsicr = {sft: 0, posted: 1};
   344
   345        /*!
   346         *  ======== tmar ========
   347         */
   348        config UInt32 tmar = 0;
   349
   350        /*! Hwi Params for Hwi Object. Default is null. */
   351        config Hwi.Params *hwiParams = null;
   352
   353        /*!
   354         *  ======== reconfig ========
   355         *  Used to modify static timer instances at runtime.
   356         *
   357         *  @param(timerParams)     timer Params
   358         *  @param(tickFxn)         functions that runs when timer expires
   359         */
   360        @DirectCall
   361        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   362
   363
   364    internal:   /* not for client use */
   365
   366        /*! Device-specific Timer implementation. */
   367        proxy TimerSupportProxy inherits ti.sysbios.interfaces.ITimerSupport;
   368
   369        /*!
   370         *  ======== startupNeeded ========
   371         *  This flag is use to prevent Timer_startup code (includes postInit(),
   372         *  deviceConfig(), initDevice() to be brought in un-necessarily.
   373         */
   374        config Bool startupNeeded = false;
   375
   376        /*! Information about timer */
   377        struct TimerDevice {
   378            UInt intNum;
   379            UInt eventId;
   380            Ptr  baseAddr;
   381        };
   382
   383        /*!
   384         *  ======== numTimerDevices ========
   385         *  The number of logical timers on a device.
   386         */
   387        config Int numTimerDevices;
   388
   389        /*!
   390         *  ======== spinLoop ========
   391         *  used by trigger function.
   392         */
   393        Void spinLoop(UInt count);
   394
   395        /*! Instance state structure */
   396        struct Instance_State {
   397            Bool                    staticInst;     /* statically created or not */
   398            Int                     id;             /* logical timer id. */
   399            UInt                    tiocpCfg;
   400            UInt                    tmar;
   401            UInt                    tier;
   402            UInt                    twer;
   403            UInt                    tclr;
   404            UInt                    tsicr;
   405            ITimer.RunMode          runMode;        /* timer mode */
   406            ITimer.StartMode        startMode;      /* timer mode */
   407            UInt                    period;         /* period */
   408            ITimer.PeriodType       periodType;     /* type (microsecs, inst) */
   409            UInt                    intNum;         /* intr num */
   410            UArg                    arg;            /* isrFxn arg */
   411            Hwi.FuncPtr             tickFxn;        /* Timer fxn plugged into Hwi */
   412            Types.FreqHz            extFreq;        /* ext freq */
   413            Hwi.Handle              hwi;            /* hwi inst */
   414        }
   415
   416        /*! Module state structure */
   417        struct Module_State {
   418            Bits32          availMask;      /* avaliable 32-bit timer halves */
   419            Types.FreqHz    intFreq;        /* internal frequency in Hz */
   420            TimerDevice     device[];       /* timer device information */
   421            Handle          handles[];      /* handles based on logical id */
   422        }
   423    }
   424    /*
   425     *  @(#) ti.sysbios.timers.gptimer; 2, 0, 0, 0,324; 6-15-2011 16:26:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   426
   427     */
   428


package ti.sysbios.timers.timer64

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    requires ti.sysbios.interfaces;
    38
    39    /*!
    40     *  ======== ti.sysbios.timer.timer64 ========
    41     *  Contains specifications for the C64P specific SYS/BIOS functions.
    42     *
    43     */
    44    package ti.sysbios.timers.timer64 [2,0,0,0] {
    45        module Timer;
    46        module TimestampProvider;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.timers.timer64; 2, 0, 0, 0,350; 6-15-2011 16:26:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module ti.sysbios.timers.timer64.Timer

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Timer.xdc ========
    34     *
    35     *
    36     */
    37
    38    package ti.sysbios.timers.timer64;
    39
    40    import xdc.rov.ViewInfo;
    41
    42    import xdc.runtime.Assert;
    43    import xdc.runtime.Error;
    44    import xdc.runtime.Types;
    45    import ti.sysbios.interfaces.ITimer;
    46    import ti.sysbios.hal.Hwi;
    47
    48    /*!
    49     *  ======== Timer ========
    50     *  Timer Peripheral Manager.
    51     *
    52     *  This Timer module manages the timer64 peripheral available on many devices.
    53     *  It is supported on the ARM and c64x+ DSP targets. This module supports the
    54     *  timer in '32-bit chained' and '32-bit unchained' mode.  In the
    55     *  '32-bit unchained' mode, specify the lower or upper half to be use.
    56     *  The physical timer being used will be taken out of reset, only when
    57     *  its specified to be the master.
    58     *
    59     *  For shared timers on a homogeneous multicore device (ie. c6472), each
    60     *  core can create the timer, but only one core will initialize the timer
    61     *  and take it out of reset.  The core that does the initialization can be
    62     *  specified by the module configuration parameter
    63     *  timerSettings[].ownerCoreId in the *.cfg file.
    64     *  By default, Core 0 is the owner for all shared timers.
    65     *
    66     *  Note:  Creating a timer with 'Timer.ANY' specified as the id will not
    67     *         return a shared timer on a homogeneous multicore device.  To use
    68     *         a shared timer, specify the timer id explicitly when creating it.
    69     *         On these devices Timer.ANY specifies the local timer id.  This
    70     *         allows a single image to run on multiple cores since each core
    71     *         will program a different local timer.
    72     *
    73     *  The following sample .cfg code sets core 1 to initialize a shared timer
    74     *  with id 4.
    75     *
    76     *  @p(code)
    77     *  var Timer = xdc.useModule('ti.sysbios.timers.timer64.Timer');
    78     *
    79     *  // sets core 1 to init and release Timer 4.
    80     *  Timer.timerSettings[4].ownerCoreId = 1;
    81     *  @p
    82     *
    83     *  The following sample .cfg code sets core 0 to initialize a shared timer
    84     *  with id 4.  It also configures the Clock module to use this timer.
    85     *  This allows multiple cores to share timer 4 for the Clock module's
    86     *  interrupt source.
    87     *
    88     *  @p(code)
    89     *  // sets core 0 to init and release Timer 4.
    90     *  var Timer = xdc.useModule('ti.sysbios.timers.timer64.Timer');
    91     *  Timer.timerSettings[4].ownerCoreId = 0;
    92     *
    93     *  var Clock = xdc.useModule('ti.sysbios.knl.Clock');
    94     *  Clock.timerId = 4;
    95     *  @p
    96     *
    97     *  @p(html)
    98     *  <h3> Calling Context </h3>
    99     *  <table border="1" cellpadding="3">
   100     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   101     *    </colgroup>
   102     *
   103     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   104     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   105     *    <!--                                                                -->
   106     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
   107     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
   109     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   110     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
   111     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   112     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
   113     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   114     *    <tr><td> {@link #create}                  </td><td>   N    </td>
   115     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   116     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
   117     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   118     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
   119     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   120     *    <tr><td> {@link #getCount}                </td><td>   Y    </td>
   121     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   122     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
   123     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   124     *    <tr><td> {@link #getFunc}                 </td><td>   Y    </td>
   125     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   126     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
   127     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   128     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td>
   129     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   130     *    <tr><td> {@link #setFunc}                 </td><td>   Y    </td>
   131     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   132     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   133     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   134     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   135     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   136     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   137     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   138     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   139     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   140     *    <tr><td colspan="6"> Definitions: <br />
   141     *       <ul>
   142     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   143     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   144     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   145     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   146     *           <ul>
   147     *             <li> In your module startup after this module is started
   148     *    (e.g. Timer_Module_startupDone() returns TRUE). </li>
   149     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   150     *             <li> During main().</li>
   151     *             <li> During BIOS.startupFxns.</li>
   152     *           </ul>
   153     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   154     *           <ul>
   155     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   156     *             <li> In your module startup before this module is started
   157     *   (e.g. Timer_Module_startupDone() returns FALSE).</li>
   158     *           </ul>
   159     *       </ul>
   160     *    </td></tr>
   161     *
   162     *  </table>
   163     *  @p
   164     *
   165     *  @p(html)
   166     *  <h3> Timer Mapping Tables </h3>
   167     *  <p>
   168     *  The Timer module allows the user to use and configure the various timers
   169     *  that exist on a particular device.  This is achieved by specifying a timer
   170     *  ID when calling {@link ti.sysbios.hal.Timer#Timer_create}.
   171     *  However, the timer ID
   172     *  specified may not always map to that timer; for example, specifying an ID
   173     *  value of 1 does not necessarily mean that this will map to "GPTimer1".
   174     *  These tables are provided to show which timers map to which timer IDs.
   175     *  </p>
   176     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables}
   177     *  @p
   178     *
   179     */
   180    @InstanceFinalize       /* To cleanup */
   181    @InstanceInitError      /* To report unavailability of timer */
   182    @ModuleStartup                /* to configure static timers */
   183
   184    module Timer inherits ti.sysbios.interfaces.ITimer
   185    {
   186        /*! In 32-bit modes, used to specify which half of Timer to use */
   187        enum Half {
   188            Half_LOWER,
   189            Half_UPPER,
   190            Half_DEFAULT
   191        };
   192
   193        /*!
   194         *  The different modes of the Timer. These values match the TIMMODE
   195         *  bit fields of the Timer Global Control Register.
   196         */
   197        enum Mode {
   198            Mode_64BITGPTIMER = 0,
   199            Mode_UNCHAINED = 1,
   200            Mode_WATCHDOG = 2,
   201            Mode_CHAINED = 3
   202        };
   203
   204        /*! Max value of Timer period for PeriodType_COUNTS*/
   205        const UInt MAX_PERIOD = 0xffffffff;
   206
   207        /*! Timer Control Register struct. */
   208        struct Control {
   209            Bits8 tien;      /*! 0=Clock not gated by TINP; 1=Clock gated */
   210            Bits8 invout;    /*! 0=Uninverted TSTAT drives TOUT; 1=Inverted TSTAT */
   211            Bits8 invin;     /*! 0=Uninverted TINP drives Timer; 1=Inverted TINP */
   212            UInt8 pwid;      /*! TSTATx goes inactive after pwid cycles (CP=0) */
   213            Bits8 cp;        /*! 0=pulse mode; 1=clock mode */
   214        };
   215
   216        /*! Timer Emulation Management Register struct. */
   217        struct EmuMgt {
   218            Bool free;        /*! 0=suspend for emu halt; 1=don't suspend */
   219            Bool soft;        /*! 0=stop immediately; 1=stop when count==period */
   220        };
   221
   222        /*! Timer GPIO interrupt control and enable Management Register struct. */
   223        struct GpioIntEn {
   224            Bits8 gpint12_eni;  /*! 0=source by timer; 1=input to source event */
   225            Bits8 gpint12_eno;  /*! 0=source by timer; 1=output to source event */
   226            Bits8 gpint12_invi; /*! 0=don't invert invput; 1=invert input */
   227            Bits8 gpint12_invo; /*! 0=don't invert output; 1=invert output */
   228            Bits8 gpint34_eni;  /*! 0=source by timer; 1=input to source event */
   229            Bits8 gpint34_eno;  /*! 0=source by timer; 1=output to source event */
   230            Bits8 gpint34_invi; /*! 0=don't invert invput; 1=invert input */
   231            Bits8 gpint34_invo; /*! 0=don't invert output; 1=invert output */
   232            Bits8 gpio_eni12;   /*! 0=TINP12 as timer input; 1=TINP12 as GPIO */
   233            Bits8 gpio_eno12;   /*! 0=TOUTP12 as timer output; 1=TOUTP12 as GPIO */
   234            Bits8 gpio_eni34;   /*! 0=TINP34 as timer input; 1=TINP34 as GPIO */
   235            Bits8 gpio_eno34;   /*! 0=TOUTP34 as timer output; 1=TOUTP12 as GPIO */
   236        };
   237
   238        /*! Timer GPIO Data and Direction Management Register struct. */
   239        struct GpioDatDir {
   240            Bits8 gpio_dati12; /*! 0=TINP12 is input; 1=TINP12 is output */
   241            Bits8 gpio_dato12; /*! 0=TOUTP12 is input; 1=TOUTP12 is output */
   242            Bits8 gpio_dati34; /*! 0=TINP34 is input; 1=TINP34 is output */
   243            Bits8 gpio_dato34; /*! 0=TOUTP34 is input; 1=TOUTP34 is output */
   244            Bits8 gpio_diri12; /*! 0=input as GPIO input; 1=input as GPIO output */
   245            Bits8 gpio_diro12; /*! 0=output as GPIO input;1=output as GPIO output */
   246            Bits8 gpio_diri34; /*! 0=input as GPIO input; 1=input as GPIO output */
   247            Bits8 gpio_diro34; /*! 0=output as GPIO input;1=output as GPIO output */
   248        };
   249
   250        /*! Timer Settings. */
   251        struct TimerSetting {
   252            Mode mode ;         /*! mode to put each Timer into */
   253            Bool master;        /*! for 'unchained' mode; 1=set mode and reset */
   254            UInt16 ownerCoreId; /*! used only for homogeneous multicore DSPs */
   255        };
   256
   257        /*! @_nodoc */
   258        @XmlDtd
   259        metaonly struct BasicView {
   260            Ptr         halTimerHandle;
   261            String      label;
   262            UInt        id;
   263            String      startMode;
   264            String      runMode;
   265            UInt        period;
   266            String      periodType;
   267            String      half;
   268            UInt        prescalar;
   269            UInt        intNum;
   270            String      tickFxn[];
   271            UArg        arg;
   272            String      extFreqLow;
   273            String      extFreqHigh;
   274            String      hwiHandle;
   275        };
   276
   277
   278        /*! @_nodoc */
   279        metaonly struct ModuleView {
   280            String      availMask;      /* avaliable 32-bit timer halves */
   281            String      intFrequency[];    /* internal frequency in Hz */
   282        }
   283
   284        /*! @_nodoc */
   285        metaonly struct Device_View {
   286            UInt        id;
   287            Bool        inUse;
   288            UInt32      intFreq;
   289            UInt        intNum;
   290            UInt        eventId;
   291            String      baseAddress;
   292        };
   293
   294        /*! @_nodoc */
   295        @Facet
   296        metaonly config ViewInfo.Instance rovViewInfo =
   297            ViewInfo.create({
   298                viewMap: [
   299                [
   300                    'Basic',
   301                    {
   302                        type: ViewInfo.INSTANCE,
   303                        viewInitFxn: 'viewInitBasic',
   304                        structName: 'BasicView'
   305                    }
   306                ],
   307                [
   308                    'Module',
   309                    {
   310                        type: ViewInfo.MODULE,
   311                        viewInitFxn: 'viewInitModule',
   312                        structName: 'ModuleView'
   313                    }
   314                ],
   315                ]
   316            });
   317
   318        /*!
   319         *  Assert raised when static created timer is not available
   320         */
   321        config xdc.runtime.Assert.Id A_notAvailable =
   322            {msg: "A_notAvailable: static created timer not available"};
   323
   324        /*!
   325         *  Error raised when timer id specified is not supported.
   326         */
   327        config Error.Id E_invalidTimer = {
   328            msg: "E_invalidTimer: Invalid Timer Id %d"
   329        };
   330
   331        /*!
   332         *  Error raised when timer requested is in use
   333         */
   334        config Error.Id E_notAvailable  = {
   335            msg: "E_notAvailable: Timer not available %d"
   336        };
   337
   338        /*!
   339         *  Error raised when period requested is not supported
   340         */
   341        config Error.Id E_cannotSupport = {
   342            msg: "E_cannotSupport: Timer cannot support requested period %d"
   343        };
   344
   345        /*!======== anyMask ========
   346         *  Available mask to be used when select = Timer_ANY. Set in xs file.
   347         */
   348        config Bits32 anyMask;
   349
   350        /*!
   351         *  ======== defaultHalf ========
   352         *        The default 32-bit half of the timer to be used.
   353         */
   354        config Half defaultHalf = Half_LOWER;
   355
   356        /*!
   357         *  ======== timerSettings ========
   358         *  Global Control configuration for each physical timer.
   359         *
   360         *  mode: Mode_UNCHAINED        32-bit unchained mode.
   361         *  master: TRUE                If TRUE, release Timer from reset.
   362         */
   363        config TimerSetting timerSettings[] = [];
   364
   365        /*!
   366         *  ======== intFreq ========
   367         *  @_nodoc
   368         *  Internal frequency for Timer
   369         */
   370        metaonly config Types.FreqHz intFreq;
   371
   372        /*!
   373         *  ======== intFreq ========
   374         *  Internal frequency for Timers
   375         */
   376        metaonly config Types.FreqHz intFreqs[];
   377
   378    instance:
   379
   380        /*!
   381         *  ======== controlInit ========
   382         *  Control configuration. Default is all fields 0 or false except:
   383         *
   384         *      pwid: 1
   385         */
   386        config Control controlInit = {tien: 0, invout: 0, invin: 0,
   387                                      pwid: 1, cp: 0};
   388
   389        /*!
   390         *  ======== emuMgtInit ========
   391         *  Emulation Management configuration. Default is:
   392         *
   393         *      free: 0
   394         *      soft: 0
   395         */
   396        config EmuMgt emuMgtInit = {free: 0, soft: 0};
   397
   398        /*!
   399         *  ======== gpioIntEn ========
   400         *  General Purpose IO interrupt control and enable Management
   401         *  configuration. The default for all fields is 0.
   402         */
   403        config GpioIntEn gpioIntEn = {
   404            gpint12_eni: 0, gpint12_eno: 0, gpint12_invi: 0, gpint12_invo: 0,
   405            gpint34_eni: 0, gpint34_eno: 0, gpint34_invi: 0, gpint34_invo: 0,
   406            gpio_eni12:  0, gpio_eno12:  0, gpio_eni34:   0, gpio_eno34:   0};
   407
   408        /*!
   409         *  ======== gpioDatDir ========
   410         *  General Purpose IO data and direction Management configuration
   411         *  The default is all fields is 0.
   412         */
   413        config GpioDatDir gpioDatDir = {
   414            gpio_dati12: 0, gpio_dato12: 0, gpio_dati34: 0, gpio_dato34: 0,
   415            gpio_diri12: 0, gpio_diro12: 0, gpio_diri34: 0, gpio_diro34: 0};
   416
   417        /*!
   418         *  ======== half ========
   419         *  In 32-bit unchained mode, this field is used to specify which half
   420         *  of the timer to use.
   421         */
   422        config Half half = Half_DEFAULT;
   423
   424        /*! Hwi Params for Hwi Object. Default is null. */
   425        config Hwi.Params *hwiParams = null;
   426
   427        /*! Hwi interrupt number to be used by Timer. */
   428        config Int intNum = -1;
   429
   430        /*!
   431         *  ======== prescalar ========
   432         *  32-bit pre-scalar to TIM12 in '32-bit chained' mode.
   433         *  The default is 0.
   434         */
   435        config UInt prescalar = 0;
   436
   437        /*!
   438         *  ======== reconfig ========
   439         *  Used to modify static timer instances at runtime.
   440         *
   441         *  @param(timerParams)     timer Params
   442         *  @param(tickFxn)                functions that runs when timer expires
   443         */
   444        @DirectCall
   445        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   446
   447
   448    internal:   /* not for client use */
   449
   450        /*! Device-specific Timer implementation. */
   451        proxy TimerSupportProxy inherits ti.sysbios.interfaces.ITimerSupport;
   452
   453        /*!
   454         *  ======== staticAvailMask ========
   455         *  The number of statically available 32-bit timer halves
   456         *
   457         *  This is required for supporting timers that are local to a
   458         *  particular processor.  The module availMask keeps track of
   459         *  what timers are available at runtime.  The two mask are the
   460         *  same if there is no concept of local timers.
   461         */
   462        metaonly config Int staticAvailMask;
   463
   464        /*!
   465         *  ======== startupNeeded ========
   466         *  This flag is use to prevent Timer_startup code (includes postInit(),
   467         *  deviceConfig(), initDevice() to be brought in un-necessarily.
   468         */
   469        config Bool startupNeeded = false;
   470
   471        /*!
   472         *  ======== freqDivisor ========
   473         *  For some devices, the timer frequency is determined by the CPU
   474         *  frequency divided by a value.  This parameter captures that value
   475         *  and is used during runtime to re-calculate the timer frequency
   476         *  when the CPU frequency is changed and Timer_getFreq is called.
   477         *  For devices with a fix timer frequency, this value is 0.
   478         */
   479        config UInt freqDivisor = 0;
   480
   481        /*! Information about timer */
   482        struct TimerDevice {
   483            UInt intNum;
   484            UInt eventId;
   485            Ptr  baseAddr;
   486        };
   487
   488        /*!
   489         *  ======== numTimerDevices ========
   490         *  The number of logical timers on a device.
   491         */
   492        config Int numTimerDevices;
   493
   494        /*!
   495         *  ======== numLocalTimers ========
   496         *  The number of physical local timers on a device.
   497         */
   498        config Int numLocalTimers = 0;
   499
   500        /*!
   501         *  ======== spinLoop ========
   502         *  used by trigger function.
   503         */
   504        Void spinLoop(UInt count);
   505
   506        /*! Instance state structure */
   507        struct Instance_State {
   508            Bool              staticInst;   /* statically created or not */
   509            Int               id;           /* logical timer id. */
   510            Half              half;         /* which half */
   511            UInt              tcrInit;      /* tcr  */
   512            UInt              emumgtInit;   /* emu mgt */
   513            UInt              gpioIntEn;    /* GPIO interrupt control */
   514            UInt              gpioDatDir;   /* GPIO data and direction */
   515            ITimer.RunMode    runMode;      /* timer mode */
   516            ITimer.StartMode  startMode;    /* timer mode */
   517            UInt              period;       /* period */
   518            ITimer.PeriodType periodType;   /* type (microsecs, inst) */
   519            UInt              prescalar;    /* pre-scalar for TIM12 */
   520            UInt              intNum;       /* intr num */
   521            UArg              arg;          /* isrFxn arg */
   522            Hwi.FuncPtr       tickFxn;      /* Timer fxn plugged into Hwi */
   523            Types.FreqHz      extFreq;      /* ext freq */
   524            Hwi.Handle        hwi;          /* hwi inst */
   525        }
   526
   527        /*! Module state structure */
   528        struct Module_State {
   529            Bits32        availMask;    /* avaliable 32-bit timer halves */
   530            Types.FreqHz  intFreqs[];   /* internal frequency in Hz */
   531            TimerSetting  gctrl[];      /* global control information */
   532            TimerDevice   device[];     /* timer device information */
   533            Handle        handles[];    /* handles based on logical id */
   534        }
   535    }
   536    /*
   537     *  @(#) ti.sysbios.timers.timer64; 2, 0, 0, 0,350; 6-15-2011 16:26:40; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   538
   539     */
   540


module ti.sysbios.timers.timer64.TimestampProvider

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== TimestampProvider.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.timers.timer64;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import ti.sysbios.timers.timer64.Timer;
    42
    43    /*!
    44     *  ======== TimestampProvider ========
    45     *  Provides dm6446 specific timestamp APIs to xdc.runtime.Timestamp
    46     *
    47     *  @p(html)
    48     *  <h3> Calling Context </h3>
    49     *  <table border="1" cellpadding="3">
    50     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    51     *    </colgroup>
    52     *
    53     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    54     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    55     *    <!--                                                      -->
    56     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td>
    57     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td>
    59     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td>
    61     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td colspan="6"> Definitions: <br />
    63     *       <ul>
    64     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    65     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    66     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    67     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    68     *           <ul>
    69     *             <li> In your module startup after this module is started
    70     *    (e.g. TimestampProvider_Module_startupDone() returns TRUE). </li>
    71     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    72     *             <li> During main().</li>
    73     *             <li> During BIOS.startupFxns.</li>
    74     *           </ul>
    75     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    76     *           <ul>
    77     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    78     *             <li> In your module startup before this module is started
    79     *    (e.g. TimestampProvider_Module_startupDone() returns FALSE).</li>
    80     *           </ul>
    81     *       </ul>
    82     *    </td></tr>
    83     *
    84     *
    85     *  </table>
    86     *  @p
    87     */
    88
    89    @ModuleStartup          /* To get Clock Timer Handle */
    90
    91    module TimestampProvider inherits xdc.runtime.ITimestampProvider
    92    {
    93        /*! @_nodoc */
    94        metaonly struct Module_View {
    95            //Timer.Instance_View timer;
    96            Bool    usesClockTimer;
    97        };
    98
    99        /*! TimestampProvider timer id. Max id value is 2 */
   100        config UInt timerId = Timer.ANY;
   101
   102        /*!
   103         *  Set this parameter when you want TimestampProvider is use the same timer
   104         *  as the Clock module
   105         *
   106         *  This parameter overrides the timeId setting.
   107         */
   108        config Bool useClockTimer = false;
   109
   110        /*!@_nodoc
   111         *  Internal use. Function that starts timer before main
   112         */
   113        Void startTimer();
   114
   115        /*!@_nodoc
   116         *  Internal use. Timer rollover interrupt handler.
   117         */
   118        Void rolloverFunc(UArg unused);
   119
   120    internal:   /* not for client use */
   121
   122        struct Module_State {
   123            Timer.Handle    timer;          /* timer instance used */
   124            volatile UInt32 hi;             /* upper 32 bits */
   125        }
   126    }
   127    /*
   128     *  @(#) ti.sysbios.timers.timer64; 2, 0, 0, 0,350; 6-15-2011 16:26:41; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   129
   130     */
   131


module ti.sysbios.utils.Load

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Load.xdc ========
    34     *
    35     */
    36
    37    package ti.sysbios.utils;
    38
    39    import xdc.rov.ViewInfo;
    40
    41    import ti.sysbios.knl.Queue;
    42    import ti.sysbios.knl.Task;
    43    import ti.sysbios.knl.Swi;
    44    import ti.sysbios.gates.GateMutex;
    45    import ti.sysbios.interfaces.IHwi;
    46
    47    import xdc.rov.ViewInfo;
    48    import xdc.runtime.Diags;
    49    import xdc.runtime.Log;
    50    import xdc.runtime.Error;
    51
    52    /*!
    53     *  ======== Load ========
    54     *  The Load module reports execution times and load information for threads
    55     *  in a system.
    56     *
    57     *  SYS/BIOS manages four distinct levels of execution threads: hardware
    58     *  interrupt service routines, software interrupt routines, tasks, and
    59     *  background idle functions. This module reports execution time and load on a
    60     *  per-task basis, and also provides information globally for hardware
    61     *  interrupt service routines, software interrupt routines and idle functions
    62     *  (in the form of the idle task). It can also report an estimate of the
    63     *  global CPU load, which is computed as the percentage of time in the
    64     *  benchmark window which was NOT spent in the idle loop.
    65     *  More specifically, the load is computed as follows:
    66     *
    67     *  global CPU load = 100 * (1 - (min. time for a trip around idle loop *
    68     *      # times in idle loop)/(benchmark time window) )
    69     *
    70     *  Any work done in the idle loop is included in the CPU load - in other
    71     *  words, any time spent in the loop beyond the shortest trip around the idle
    72     *  loop is counted as non-idle time.
    73     *
    74     *  Execution time is reported in units of
    75     *  {@link xdc.runtime.Timestamp Timestamp} counts, and load is reported
    76     *  in percentages.
    77     *
    78     *  By default, load data is gathered in all threads.
    79     *  {@link #hwiEnabled hwiEnabled}, {@link #swiEnabled swiEnabled}
    80     *  and {@link #taskEnabled taskEnabled} can be used to select which
    81     *  type(s) of threads are monitored. These statistics are automatically
    82     *  recorded to the load module's logger instance. Users can also choose
    83     *  to call {@link #getTaskLoad}, {@link #getGlobalSwiLoad},
    84     *  {@link #getGlobalHwiLoad} and {@link #getCPULoad} at any time to obtain the
    85     *  statistics at runtime.
    86     *
    87     *  The module relies on {@link #update} to be called to compute load and
    88     *  execution times from the time when {@link #update} was last called. This
    89     *  is automatically done for every period specified by
    90     *  {@link #windowInMs windowInMs} in an {@link ti.sysbios.knl.Idle Idle}
    91     *  function when {@link #updateInIdle updateInIdle} is
    92     *  set to true. The time between 2 calls to {@link #update} is called the
    93     *  benchmark time window.
    94     *
    95     *  By passing in a function pointer of type
    96     *  Void(*{@link #postUpdate})(Void) through the
    97     *  {@link #postUpdate postUpdate} config parameter, one can specify a
    98     *  {@link #postUpdate postUpdate} function that is
    99     *  automatically called by {@link #update} immediately after the statistics
   100     *  have been computed at the end of a benchmark time window.  Setting this
   101     *  function allows the user to optionally post-process the thread statistics
   102     *  once and only once per benchmark window.
   103     *
   104     *  Advanced users could optionally omit calling {@link #update} in the idle
   105     *  loop by setting {@link #updateInIdle updateInIdle} to false. They can
   106     *  then call {@link #update} somewhere else (e.g. in a periodic higher
   107     *  priority Task) instead to ensure statistics are computed even when the
   108     *  system is never idle.
   109     *
   110     *  @a(Examples)
   111     *  Configuration example: The following statements configure the Load module
   112     *  to obtain output in the CCS output window. This is useful for early
   113     *  development without RTA tools support in SYS/BIOS:
   114     *
   115     *  @p(code)
   116     *  var System = xdc.useModule('xdc.runtime.System');
   117     *  var SysStd = xdc.useModule('xdc.runtime.SysStd');
   118     *  System.SupportProxy = SysStd;
   119     *
   120     *  var Load = xdc.useModule('ti.sysbios.utils.Load');
   121     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
   122     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
   123     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   124     *
   125     *  // Turn on statistics log messages for Load module
   126     *  Load.common$.diags_USER4 = Diags.ALWAYS_ON;
   127     *  // Define a program-wide logger to be the System Logger
   128     *  Defaults.common$.logger = LoggerSys.create();
   129     *  @p
   130     *
   131     *  Notes on above example:
   132     *  @p(blist)
   133     *  - When using the {@link xdc.runtime.LoggerSys System Logger},
   134     *  {@link xdc.runtime.System#printf System_printf} calls are made to produce
   135     *  the output in the output window. These calls are highly intrusive
   136     *  and are only suited for early development.
   137     *
   138     *  - Also make sure your task stack sizes are large enough when using the
   139     *  {@link xdc.runtime.LoggerSys System Logger} - particularly the idle task
   140     *  stack size since logging is done in the idle task by default.
   141     *  @p
   142     *
   143     *  @a(Caveats)
   144     *  @p(nlist)
   145     *  - For the module to return accurate load values, the {@link #update}
   146     *  function must be run at least once before the Timestamp count gets to
   147     *  wrap around. This means on a platform with a 32-bit
   148     *  {@link xdc.runtime.Timestamp Timestamp} frequency that runs at 200 MHz,
   149     *  the function must be called at least once every 21 sec. With faster
   150     *  {@link xdc.runtime.Timestamp Timestamp} frequencies it would have to be
   151     *  called even more frequently.
   152     *
   153     *  - If the {@link #updateInIdle updateInIdle} option is enabled, the
   154     *  module will call {@link #update} periodically according to
   155     *  {@link #windowInMs windowInMs}. The latter must be set to a time
   156     *  interval that is below
   157     *  (2^32) * 1000 / ({@link xdc.runtime.Timestamp Timestamp} Frequency)
   158     *  milliseconds
   159     *
   160     *  - If the {@link #updateInIdle updateInIdle} option is disabled, the user is
   161     *  then responsible for calling {@link #update} more often than the above
   162     *  time interval.
   163     *
   164     *  - Load values might not add up to 100%. Because the module minimizes
   165     *  its interrupt latency and avoids locking up the system to compute all
   166     *  thread loads at once, each thread's execution time is evaluated separately
   167     *  over its own time window, which could be slightly different to that of
   168     *  another thread.
   169     *
   170     *  - When disabling monitoring of a thread type of higher priority, the
   171     *  time spent in that thread type will be counted towards time spent in
   172     *  threads of lower priority. E.g. if {@link #hwiEnabled hwiEnabled} and
   173     *  {@link #swiEnabled swiEnabled} are both false, then time spent in Hwi's and
   174     *  Swi's will be counted towards the Tasks in which the interrupts happened.
   175     *  Thus, for better accuracy, it is best to leave monitoring on for threads of
   176     *  a higher priority relative to the thread type of interest.
   177     *
   178     *  - The implementation of {@link #getCPULoad()} self-calibrates the shortest
   179     *  path through the idle loop. It does this by keeping track of the shortest
   180     *  time between invocations of an idle function automatically inserted by the
   181     *  Load module, and assumes that to be the time it takes for one iteration
   182     *  through the idle loop. Because of this, the CPU load value is only an
   183     *  estimate since the idle loop might occasionally take longer to run
   184     *  (e.g. due to caching effects, stalls). The reported CPU load tends to be
   185     *  slightly higher than reality, especially when the load is low.
   186     *
   187     *  - If {@link #taskEnabled taskEnabled} is set to true,
   188     *  task name support will be automatically turned on so that the Load module
   189     *  can print out the task names in its log output.
   190     *
   191     *  - Currently does not support {@link xdc.runtime.Timestamp Timestamp}
   192     *  frequencies over 4 GHz.
   193     *  @p
   194     *
   195     *  @p(html)
   196     *  <h3> Calling Context </h3>
   197     *  <table border="1" cellpadding="3">
   198     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
   199     *    </colgroup>
   200     *
   201     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
   202     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
   203     *    <!--                                                          -->
   204     *    <tr><td> {@link #getCPULoad}      </td><td>   Y    </td><td>   Y    </td>
   205     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   206     *    <tr><td> {@link #getGlobalHwiLoad}</td><td>   Y    </td><td>   Y    </td>
   207     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   208     *    <tr><td> {@link #getGlobalSwiLoad}</td><td>   Y    </td><td>   Y    </td>
   209     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   210     *    <tr><td> {@link #getTaskLoad}     </td><td>   Y    </td><td>   Y    </td>
   211     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   212     *    <tr><td> {@link #reset}           </td><td>   Y*   </td><td>   Y*   </td>
   213     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   214     *    <tr><td> {@link #update}          </td><td>   Y*   </td><td>   Y*   </td>
   215     *    <td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   216     *    <tr><td colspan="6"> Definitions: <br />
   217     *       <ul>
   218     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   219     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   220     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   221     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   222     *           <ul>
   223     *             <li> In your module startup after this module is started
   224     *    (e.g. Load_Module_startupDone() returns TRUE). </li>
   225     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   226     *             <li> During main().</li>
   227     *             <li> During BIOS.startupFxns.</li>
   228     *           </ul>
   229     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   230     *           <ul>
   231     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   232     *             <li> In your module startup before this module is started
   233     *    (e.g. Load_Module_startupDone() returns FALSE).</li>
   234     *           </ul>
   235     *       <li> <b>*</b>: Indicates only when {@link #taskEnabled taskEnabled}
   236     *    is set to false. </li>
   237     *       </ul>
   238     *    </td></tr>
   239     *  </table>
   240     *  @p
   241     */
   242    module Load
   243    {
   244        /*!
   245         *  ======== ModuleView ========
   246         *  @_nodoc
   247         */
   248        metaonly struct ModuleView {
   249            String cpuLoad;     /* total cpu load, in percent */
   250            String swiLoad;     /* cpu load due to Swi's, in percent */
   251            String hwiLoad;     /* cpu load due to Hwi's, in percent */
   252            String idleError;   /* estimated measurement error in one pass of idle
   253                                 * loop, in percent
   254                                 */
   255        }
   256
   257        /*!
   258         *  ======== rovViewInfo ========
   259         *  @_nodoc
   260         */
   261        @Facet
   262        metaonly config ViewInfo.Instance rovViewInfo =
   263            ViewInfo.create({
   264                viewMap: [
   265                [
   266                    'Module',
   267                    {
   268                        type: ViewInfo.MODULE,
   269                        viewInitFxn: 'viewInitModule',
   270                        structName: 'ModuleView'
   271                    }
   272                ],
   273                ]
   274            });
   275
   276
   277        /* -------- Module Types -------- */
   278
   279        /*!
   280         *  ======== FuncPtr ========
   281         *  Callback function type
   282         */
   283        typedef Void (*FuncPtr)();
   284
   285        /*!
   286         *  ======== Stat ========
   287         *  Load statistics info
   288         */
   289        struct Stat {
   290            UInt32 threadTime;
   291            UInt32 totalTime;
   292        };
   293
   294
   295        /* -------- Module Configuration Parameters -------- */
   296
   297        /*!
   298         *  ======== LS_cpuLoad ========
   299         *  This event logs the global CPU load as a percentage
   300         *
   301         *  This event is logged whenever the Diags.USER4 level is enabled
   302         *  and the load is measured.
   303         *
   304         */
   305        config Log.Event LS_cpuLoad = {
   306            mask: Diags.USER4,
   307            msg: "LS_cpuLoad: %d%%"
   308        };
   309
   310        /*!
   311         *  ======== LS_hwiLoad ========
   312         *  This event logs the Hwi load
   313         *
   314         *  This event is logged whenever the Diags.USER4 level is enabled
   315         *  {@link #hwiEnabled} is true, and the load is measured.
   316         *
   317         *  This event logs the Hwi load, with the form:
   318         *  <load time>,<measurement time>
   319         *
   320         *  Percentage load = <load time> / <measurement time> x 100%
   321         */
   322        config Log.Event LS_hwiLoad = {
   323            mask: Diags.USER4,
   324            msg: "LS_hwiLoad: %d,%d"
   325        };
   326
   327        /*!
   328         *  ======== LS_swiLoad ========
   329         *  This event logs the Swi load
   330         *
   331         *  This event is logged whenever the Diags.USER4 level is enabled
   332         *  {@link #swiEnabled} is true, and the load is measured.
   333         *
   334         *  This event logs the Swi load, with the form:
   335         *  <load time>,<measurement time>
   336         *
   337         *  Percentage load = <load time> / <measurement time> x 100%
   338         */
   339        config Log.Event LS_swiLoad = {
   340            mask: Diags.USER4,
   341            msg: "LS_swiLoad: %d,%d"
   342        };
   343
   344        /*!
   345         *  ======== LS_taskLoad ========
   346         *  This event logs Task thread loads
   347         *
   348         *  This event is logged whenever the Diags.USER4 level is enabled,
   349         *  {@link #taskEnabled} is true, and the load is measured.
   350         *
   351         *  This event logs Task thread loads, with the form:
   352         *  <Task handle>,<load time>,<measurement time>,<Task function pointer>
   353         *
   354         *  Percentage load = <load time> / <measurement time> x 100%
   355         */
   356        config Log.Event LS_taskLoad = {
   357            mask: Diags.USER4,
   358            msg: "LS_taskLoad: 0x%x,%d,%d,0x%x"
   359        };
   360
   361        /*!
   362         *  ======== postUpdate ========
   363         *  User function called after each load update
   364         *
   365         *  If non-NULL, postUpdate is run immediately after each update.
   366         */
   367        config FuncPtr postUpdate = null;
   368
   369        /*!
   370         *  ======== updateInIdle ========
   371         *  Automatically call {@link #update} in Idle loop
   372         *
   373         *  If this parameter is set to `true`, an {@link ti.sysbios.knl.Idle Idle}
   374         *  function, which computes and updates the CPU load, is added to the
   375         *  {@link ti.sysbios.knl.Idle#run Idle loop}.
   376         */
   377        config Bool updateInIdle = true;
   378
   379        /*!
   380         *  ======== minIdle ========
   381         *  Specifies the minimum time used to compute idle time
   382         *
   383         *  During CPU load measurement, the minimum time observed executing
   384         *  the idle loop together with the count of the number of times the idle
   385         *  loop runs id used to compute the total idle time.  However, since the
   386         *  _actual_ time spent in the idle loop will almost always be greater
   387         *  then the observed minimum, the idle time is almost always under
   388         *  estimated.
   389         *
   390         *  This configuration parameter can be used to compensate for this
   391         *  underestimate by placing a lower bound on the minimum time used in
   392         *  the CPU measurements.  The minimum idle time used to compute CPU
   393         *  load is guarenteed to be greater than or equal to `minIdle`.
   394         */
   395        metaonly config UInt32 minIdle = 0;
   396
   397        /*!
   398         *  ======== windowInMs ========
   399         *  Load averaging period
   400         *
   401         *  When {@link #updateInIdle} is enabled, this period determines the
   402         *  minimum elapsed time between updates of the load statistics in the
   403         *  idle loop.
   404         */
   405        config UInt windowInMs = 500;
   406
   407        /*!
   408         *  ======== hwiEnabled ========
   409         *  Enables Hwi time monitoring
   410         *
   411         *  When this parameter is set to `true`, {@link ti.sysbios.hal.Hwi Hwi}
   412         *  processing time is accumulated between successive calls of
   413         *  {@link #update} and, as part of Load_update, an
   414         *  {@link #LS_hwiLoad event} with this cumulative time is logged.  This
   415         *  time, together with the total elapsed time, is used to estimate the
   416         *  CPU load due to any Hwi instances run between these updates.
   417         */
   418        config Bool hwiEnabled = false;
   419
   420        /*!
   421         *  ======== swiEnabled ========
   422         *  Enables Swi time monitoring
   423         *
   424         *  When this parameter is set to `true`, Swi processing time is
   425         *  accumulated between successive calls of {@link #update} and, as
   426         *  part of Load_update, an {@link #LS_swiLoad event} with this
   427         *  cumulative time is logged.  This time together with the total
   428         *  elapsed time is used to estimate the CPU load due to any Swi
   429         *  instances run between these updates.
   430         */
   431        config Bool swiEnabled = false;
   432
   433        /*!
   434         *  ======== taskEnabled ========
   435         *  Enables Task time monitoring
   436         *
   437         *  When this parameter is set to `true`, each Task's processing time is
   438         *  accumulated between successive calls of {@link #update} and, as
   439         *  part of Load_update, an {@link #LS_taskLoad event} with this
   440         *  cumulative time is logged for each task.  This time together with the
   441         *  total elapsed time is used to estimate the CPU load due to each Task
   442         *  run between these updates.
   443         */
   444        config Bool taskEnabled = true;
   445
   446        /* -------- Module Functions -------- */
   447
   448        /*!
   449         *  ======== getTaskLoad ========
   450         *  Return the load and time spent in a specific task
   451         *
   452         *  This function returns the load and time spent in a specific task
   453         *  along with the duration over which the measurement was done. Numbers
   454         *  are reported in  {@link xdc.runtime.Timestamp Timestamp} counts.
   455         *
   456         *  Task handle must be valid and have been registered with Load.
   457         *
   458         *  @param(task) Handle of the Task which time we are interested in.
   459         *  @param(stat) Load and time statistics info
   460         *  @b(returns) TRUE if success, FALSE if failure
   461         *
   462         */
   463        @DirectCall
   464        Bool getTaskLoad(Task.Handle task, Stat *stat);
   465
   466        /*!
   467         *  ======== update ========
   468         *  Record thread statistics and reset all counters
   469         *
   470         *  If {@link #taskEnabled taskEnabled} is set to true, this function can
   471         *  only be called in task context.
   472         */
   473        @DirectCall
   474        Void update();
   475
   476        /*!
   477         *  ======== reset ========
   478         *  Reset all internal load counters
   479         *
   480         *  If {@link #taskEnabled taskEnabled} is set to true, this function can
   481         *  only be called in task context.
   482         */
   483        @DirectCall
   484        Void reset();
   485
   486        /*!
   487         *  ======== getGlobalSwiLoad ========
   488         *  Return the load and time spent in Swi's
   489         *
   490         *  This function returns the load and time spent in Swi's along with
   491         *  the time duration over which the measurement was done. Numbers are
   492         *  reported in  {@link xdc.runtime.Timestamp Timestamp} counts.
   493         *
   494         *  @param(stat) Load and time statistics info
   495         *  @b(returns) TRUE if success, FALSE if failure
   496         *
   497         */
   498        @DirectCall
   499        Bool getGlobalSwiLoad(Stat *stat);
   500
   501        /*!
   502         *  ======== getGlobalHwiLoad ========
   503         *  Return the load and time spent in hwi's
   504         *
   505         *  This function computes the load and time spent in Hwi's along
   506         *  with the time duration over which the measurement was done. Numbers
   507         *  are reported in  {@link xdc.runtime.Timestamp Timestamp} counts.
   508         *
   509         *  @param(stat) Load and time statistics info
   510         *
   511         *  @b(returns) TRUE if success, FALSE if failure
   512         */
   513        @DirectCall
   514        Bool getGlobalHwiLoad(Stat *stat);
   515
   516        /*!
   517         *  ======== getCPULoad ========
   518         *  Return an estimate of the global CPU load
   519         *
   520         *  This function returns an estimate of CPU load (% utilization of the
   521         *  CPU), with the idle time determined based on number of trips through
   522         *  the idle loop multiplied by the shortest amount of time through the
   523         *  loop.
   524         *
   525         *  This function requires the idle loop to be run during a benchmark time
   526         *  window.
   527         *
   528         *  Note: Time spent in kernel while switching to a Hwi/Swi/Task is
   529         *        considered non-idle time.
   530         *
   531         *  @b(returns) CPU load in %
   532         *
   533         */
   534        @DirectCall
   535        UInt32 getCPULoad();
   536
   537        /*!
   538         *  ======== calculateLoad ========
   539         *  Compute total CPU load from a Load_Stat structure
   540         *
   541         *  This function computes percent load from the
   542         *  values in a Load_Stat structure.
   543         *
   544         *  @a(returns) Load value of a Load_Stat structure in %.
   545         */
   546        @DirectCall
   547        UInt32 calculateLoad(Stat *stat);
   548
   549        /*!
   550         *  ======== setMinIdle ========
   551         *  Set lower bound on idle loop time used to compute CPU load
   552         *
   553         *  @see #minIdle
   554         */
   555        @DirectCall
   556        UInt32 setMinIdle(UInt32 newMinIdleTime);
   557
   558        /*! @_nodoc
   559         *  ======== addTask ========
   560         *  Add a task to the list for benchmarking
   561         *
   562         *  Returns TRUE if task is successfully added to the list.
   563         *
   564         *  If {@link #taskEnabled} is set to true, this function can only be
   565         *  called in task context.
   566         *
   567         *  @param(task) Handle of the Task to be added to the list.
   568         *  @param(env) Handle of context structure to be used by the Task
   569         *  @b(returns) TRUE if success, FALSE if failure
   570         *
   571         */
   572        @DirectCall
   573        Bool addTask(Task.Handle task, HookContext *env);
   574
   575        /*! @_nodoc
   576         *  ======== removeTask ========
   577         *  Remove a task from the list for benchmarking
   578         *
   579         *  Returns TRUE if task is successfully removed from the list.
   580         *
   581         *  If {@link #taskEnabled} is set to true, this funciton can only be
   582         *  called in task context.
   583         *
   584         *  @param(taskHandle) Handle of the Task to be removed from the list.
   585         *  @b(returns) TRUE if success, FALSE if failure
   586         *
   587         */
   588        @DirectCall
   589        Bool removeTask(Task.Handle task);
   590
   591        /*!
   592         *  @_nodoc
   593         *  ======== idleFxn ========
   594         *  Idle function used to periodically update the Task time values
   595         *
   596         */
   597        @DirectCall
   598        Void idleFxn();
   599
   600        /* -------- Hook Functions -------- */
   601
   602        /*!
   603         *  @_nodoc
   604         *  ======== taskCreateHook ========
   605         *  Create hook function used to initialize all task's hook context
   606         *  to NULL during creation time. Also adds the task's hook context
   607         *  when {@link #autoAddTasks} is set to true.
   608         *
   609         *  @param(task) Handle of the Task to initialize.
   610         *  @param(eb) Error block.
   611         *
   612         */
   613        @DirectCall
   614        Void taskCreateHook(Task.Handle task, Error.Block *eb);
   615
   616        /*!
   617         *  @_nodoc
   618         *  ======== taskDeleteHook ========
   619         *  Delete hook function used to remove the task's hook context
   620         *  when {@link #autoAddTasks} is set to true.
   621         *
   622         *  @param(task) Handle of the Task to delete.
   623         *
   624         */
   625        @DirectCall
   626        Void taskDeleteHook(Task.Handle task);
   627
   628        /*!
   629         *  @_nodoc
   630         *  ======== taskSwitchHook ========
   631         *  Switch hook function used to perform benchmarks
   632         *
   633         *  @param(curTask) Handle of currently executing Task.
   634         *  @param(nextTask) Handle of the next Task to run
   635         *
   636         */
   637        @DirectCall
   638        Void taskSwitchHook(Task.Handle curTask, Task.Handle nextTask);
   639
   640        /*!
   641         *  @_nodoc
   642         *  ======== swiBeginHook ========
   643         *  Swi begin hook function used to perform benchmarks
   644         *
   645         *  @param(swi) Handle of Swi to begin execution.
   646         *
   647         */
   648        @DirectCall
   649        Void swiBeginHook(Swi.Handle swi);
   650
   651        /*!
   652         *  @_nodoc
   653         *  ======== swiEndHook ========
   654         *  Swi end hook function used to perform benchmarks
   655         *
   656         *  @param(swi) Handle of Swi to end execution.
   657         *
   658         */
   659        @DirectCall
   660        Void swiEndHook(Swi.Handle swi);
   661
   662        /*!
   663         *  @_nodoc
   664         *  ======== hwiBeginHook ========
   665         *  Hwi begin hook function used to perform benchmarks
   666         *
   667         *  @param hwi Handle of Hwi to begin execution.
   668         *
   669         */
   670        @DirectCall
   671        Void hwiBeginHook(IHwi.Handle hwi);
   672
   673        /*!
   674         *  @_nodoc
   675         *  ======== hwiEndHook ========
   676         *  Hwi end hook function used to perform benchmarks
   677         *
   678         *  @param hwi Handle of Hwi to end execution.
   679         *
   680         */
   681        @DirectCall
   682        Void hwiEndHook(IHwi.Handle hwi);
   683
   684        /*!
   685         *  @_nodoc
   686         *  ======== taskRegHook ========
   687         *  Registration function for the module's hook
   688         *
   689         *  Moved out of the internal section for ROM purposes. This function
   690         *  is not referenced directly, so it must be a "public" function so
   691         *  that the linker does not drop it when creating a ROM image.
   692         *
   693         *  @param(id) The id of the hook for use in load.
   694         *
   695         */
   696        @DirectCall
   697        Void taskRegHook(Int id);
   698
   699    internal:   /* not for client use */
   700
   701        /* -------- Internal Module Types -------- */
   702
   703        /*!
   704         *  @_nodoc
   705         *  Hook Context
   706         */
   707        struct HookContext {
   708            Queue.Elem qElem;        /*! Queue element */
   709            UInt32 totalTimeElapsed; /*! Total amount of time elapsed */
   710            UInt32 totalTime;        /*! time spent in thread */
   711            UInt32 nextTotalTime;    /*! working counter of time spent in thread */
   712            UInt32 timeOfLastUpdate; /*! time when update was last called */
   713            Ptr threadHandle;        /*! handle to thread whose context this is */
   714        };
   715
   716        /* -------- Internal Module Parameters -------- */
   717
   718        /*! @_nodoc
   719         *  Automatically add all tasks
   720         */
   721        config Bool autoAddTasks = true;
   722
   723        /* -------- Internal Module Functions -------- */
   724
   725        /*!
   726         *  @_nodoc
   727         *  ======== logLoads ========
   728         *  Logs load values for all monitored threads.
   729         *  Statistics messages from the kernel must be enabled
   730         *  (via Load.common$.diags_USER4) in order to see the output.
   731         *
   732         *  If {@link #taskEnabled} is set to TRUE, this function can only be
   733         *  called in task context.
   734         */
   735        Void logLoads();
   736
   737
   738        struct Module_State {
   739            Queue.Object taskList;   /* List to hold registered task instances */
   740
   741            Int taskHId;             /* Task Hook Context Id for this module */
   742
   743            UInt32 taskStartTime;    /* The start time of the current task */
   744            UInt32 timeElapsed;      /* Working count of time elapsed */
   745            Task.Handle runningTask; /* Currently running task */
   746            Bool firstSwitchDone;    /* Flag for first task switch */
   747
   748            UInt32 swiStartTime;     /* Start time of the current Swi */
   749            HookContext swiEnv;      /* Singleton hook context for swi's */
   750            UInt32 swiCnt;           /* number of Swi's currently executing */
   751
   752            UInt32 hwiStartTime;     /* Start time of the current Hwi */
   753            HookContext hwiEnv;      /* Singleton hook context for hwi's */
   754            UInt32 hwiCnt;           /* number of Hwi's currently executing */
   755
   756            UInt32 timeSlotCnt;      /* count of number of time windows printed */
   757
   758            UInt32 minLoop;          /* shortest time thru the idle loop */
   759            UInt32 minIdle;          /* minLoop is never set below this value */
   760            UInt32 t0;               /* start time of previous call to idle fxn */
   761            UInt32 idleCnt;          /* number of times through idle loop */
   762            UInt32 cpuLoad;          /* CPU load in previous time window */
   763
   764            GateMutex.Object gate;   /* Gate to Task list */
   765        };
   766    }
   767    /*
   768     *  @(#) ti.sysbios.utils; 2, 0, 0, 0,490; 6-15-2011 16:26:42; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   769
   770     */
   771


package ti.sysbios.utils

     1    /*
     2     * Copyright (c) 2011, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36
    37    /*!
    38     *  ======== ti.sysbios.utils ========
    39     *  Miscellaneous utility modules
    40     *
    41     *  This package contains the `{@link Load}` module, which reports the
    42     *  global CPU load and may be configured to also report thread-specific load.
    43     *
    44     */
    45    package ti.sysbios.utils [2,0,0,0] {
    46        module Load;
    47    }
    48    /*
    49     *  @(#) ti.sysbios.utils; 2, 0, 0, 0,490; 6-15-2011 16:26:42; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
    50
    51     */
    52


module xdc.runtime.Assert

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Assert.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== Assert ========
    19     *  Runtime assertion manager
    20     *
    21     *  The `Assert` module provides configurable diagnostics to the program.
    22     *  Similar to the standard C `assert()` macro, `Assert` methods are
    23     *  interspersed with other code to add diagnostics to a program. Unlike
    24     *  the standard C assert support, the `Assert` module provides greater
    25     *  flexibility in managing the messages displayed, the message string
    26     *  space overhead, and the runtime handling of failures. In addition,
    27     *  because the `Assert` methods build atop the Diags module, you can
    28     *  precisely control which asserts remain in the final application, if any.
    29     *
    30     *  The `Assert` module works in conjunction with the `{@link Diags}` module.
    31     *  `Assert` statements are added to the code using the
    32     *  `{@link #isTrue Assert_isTrue()}` function. Execution of assert
    33     *  statements is controlled by the `{@link Diags#ASSERT}` and
    34     *  `{@link Diags#INTERNAL}` bits in a module's diagnostics mask. By default,
    35     *  all module's `Diags_ASSERT` bit is enabled and the `Diags_INTERNAL` bit
    36     *  is disabled.  See `{@link Types#Common$ Types.Common$}` for the
    37     *  declaration of the bits in the diagnostics mask and
    38     *  `{@link Defaults#common$ Default.common$}` for the default module settings.
    39     *
    40     *  Two types of asserts are supported: public asserts and internal asserts.
    41     *
    42     *  @p(blist)
    43     *  - Public asserts have an assert ID and are, by default, controlled
    44     *  by the `{@link Diags#ASSERT}` bit.
    45     *  - Internal asserts don't have an assert ID (other than NULL) and
    46     *  are active only when both the `{@link Diags#ASSERT}` and
    47     *  `{@link Diags#INTERNAL}` bits of the module's diagnostics mask are set.
    48     *  @p
    49     *
    50     *  `Assert` IDs are small integer values that index into a table of
    51     *  assertion descriptors. These descriptors hold an error message
    52     *  and a diagnostics mask that is used to enable and disable the
    53     *  assertion at runtime.
    54     *
    55     *  You can remap individual public asserts to different bits in the
    56     *  diagnostics mask, or can disable the assert altogether. This is
    57     *  done by setting the mask property of the assert ID. Setting the
    58     *  mask to 0 disables the assert. In all other cases, the `Diags.ASSERT`
    59     *  bit is OR'd together with the mask to define the controlling bits.
    60     *  For example, the module's diagnostics mask must have the `Diags.ASSERT`
    61     *  bit set and any other bit specified in the mask property of the
    62     *  assert ID in order to activate the assert.
    63     *
    64     *  @a(Examples)
    65     *  @p(html)
    66     *  <hr />
    67     *  @p
    68     *  Example 1: The following C code adds an assert to application code
    69     *  which is not in a module. This assert does not have an assert
    70     *  identifier (the second argument is NULL); this makes it an internal
    71     *  assert.
    72     *
    73     *  @p(code)
    74     *  // file.c
    75     *  #include <xdc/runtime/Assert.h>
    76     *
    77     *  Assert_isTrue(count > 0, NULL);
    78     *  @p
    79     *
    80     *  The following XDC configuration statements set both the ASSERT and
    81     *  INTERNAL bits in the diagnostics mask to enable the internal assert
    82     *  created in the previous C code. Since the C code is not in a module,
    83     *  you must set the bits in the diagnostics mask of the
    84     *  `{@link xdc.runtime.Main xdc.runtime.Main}` module. The Main module
    85     *  is used to control all `{@link Log}` and `Assert` statements that are
    86     *  not part of the implementation of a module; for example, top-level
    87     *  application code or any existing sources that simply call the `Log` or
    88     *  `Assert` methods.
    89     *
    90     *  @p(code)
    91     *  // program.cfg
    92     *  var Assert = xdc.useModule('xdc.runtime.Assert');
    93     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    94     *  var Main = xdc.useModule('xdc.runtime.Main');
    95     *
    96     *  Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
    97     *  Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;
    98     *  @p
    99     *
   100     *  @p(html)
   101     *  <hr />
   102     *  @p
   103     *  Example 2: The following example shows how to use and configure an
   104     *  assert ID that is declared by a module. It adds that assert to the
   105     *  application's C source code, and configures the application to
   106     *  execute the assert.
   107     *
   108     *  This is part of the XDC file for the module that declares an `Assert` Id:
   109     *
   110     *  @p(code)
   111     *  // Mod.xdc
   112     *  import xdc.runtime.Assert;
   113     *  import xdc.runtime.Diags;
   114     *
   115     *  config Assert.Id A_nonZero = {
   116     *      msg: "A_nonZero: value must be non-zero"
   117     *  };
   118     *  @p
   119     *
   120     *  This is part of the C code for the application:
   121     *
   122     *  @p(code)
   123     *  // Mod.c
   124     *  #include <xdc/runtime/Assert.h>
   125     *
   126     *  Assert_isTrue(x != 0, Mod_A_nonZero);
   127     *  @p
   128     *
   129     *  This is part of the XDC configuration file for the application:
   130     *
   131     *  @p(code)
   132     *  // program.cfg
   133     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   134     *  var Mod = xdc.useModule('my.pkg.Mod');
   135     *  Mod.common$.diags_ASSERT = Diags.ALWAYS_ON;
   136     *  @p
   137     */
   138
   139    @CustomHeader
   140
   141    module Assert {
   142
   143        /*!
   144         *  ======== Assert_Desc ========
   145         *  Assert descriptor
   146         *
   147         *  Each public assert is defined with an assert descriptor. This
   148         *  structure defines which bits in the module's diagnostics mask
   149         *  control this assert, and the message raised when the assert fails.
   150         *  The mask property is optional, it defaults to the
   151         *  `{@link Diags#ASSERT}` bit.
   152         *
   153         *  @field(mask)    Specifies which bits enable the assert.
   154         *  @field(msg)     The message printed when the assert fails.
   155         */
   156        metaonly struct Desc {
   157            Diags.Mask mask;
   158            String msg;
   159        };
   160
   161        /*!
   162         *  ======== Assert_Id ========
   163         *  Assert identifier
   164         *
   165         *  Each metaonly assert descriptor is encoded into a target accessable
   166         *  assert Id type which can be passed to the `{@link #isTrue}` function.
   167         */
   168        @Encoded typedef Desc Id;
   169
   170        /*!
   171         *  ======== E_assertFailed ========
   172         *  The `{@link Error#Id}` raised when an assertion violation is detected
   173         *
   174         *  When an assertion violation is triggered, an error is raised via
   175         *  `Error_raise()`.  `E_assert_Failed` is the `{@link Error#Id}` passed
   176         *  to `Error_raise()`.
   177         *
   178         *  The first string argument (%s) will be either "", if the assertion Id
   179         *  is `NULL` (for internal asserts), or ": " (for public asserts).
   180         *  The second string argument (%s) is the
   181         *  `Assert.Desc.msg` string associated with the assertion Id; if the
   182         *  Id is `NULL`  (an internal assert) or if text is not loaded
   183         *  (`!{@link Text#isLoaded}()`), this string is "".
   184         *
   185         *  @see #isTrue
   186         *  @see Error#Id
   187         */
   188        readonly config Error.Id E_assertFailed = {msg: "assertion failure%s%s"};
   189
   190        /*!
   191         *  ======== Assert_isTrue ========
   192         *  Test an assertion
   193         *
   194         *  `Assert_isTrue()` statements may be conditionally enabled (disabled)
   195         *  on a per module basis by setting the calling module's
   196         *  `{@link IModule#$common $common.diags_ASSERT}` configuration
   197         *  parameter.  If
   198         *  the `Assert_isTrue()` statement is not in a module, the calling
   199         *  module is the `{@link Main}` module.  You must enable the
   200         *  `{@link Diags#ASSERT}` bit in the module's diagnostics mask for this
   201         *  call to be enabled.  If a `NULL` assert id is specified, then you
   202         *  must enable the `{@link Diags#INTERNAL}` in addition to the
   203         *  `ASSERT` bit.
   204         *
   205         *  If the `Assert_isTrue()` statement is enabled and `expr` evaluates to
   206         *  false, the assert specified by `id` is raised; i.e., the
   207         *  `{@link #E_assertFailed}` error is raised with a `NULL`
   208         *  error block.  In other words, the standard `{@link Error#raise}`
   209         *  handling hooks will be run, `{@link System#abort()}` will be called,
   210         *  and control does not return to the caller.  The `id` may be `null`, in
   211         *  which case you will get a generic assert message.
   212         *
   213         *  @param(expr)    the expression which should evaluate to true
   214         *  @param(id)      identifies the assert being raised
   215         *
   216         *  @a(Examples)
   217         *  C Code
   218         *  @p(code)
   219         *  #include <xdc/runtime/Assert.h>
   220         *
   221         *  Assert_isTrue(count > 0, NULL);
   222         *  @p
   223         */
   224        @Macro Void isTrue(Bool expr, Id id);
   225
   226    internal:
   227
   228        Void raise(Types.ModuleId mod, String file, Int line, Id id);
   229
   230    }
   231    /*
   232     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   233     */
   234


module xdc.runtime.Defaults

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Defaults.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Defaults ========
    21     *  Default attributes inherited by all target modules
    22     *
    23     *  This module defines default values for `common$` structure. If other
    24     *  modules do not set `common$` properties explicitly, these values will be
    25     *  used.
    26     */
    27    module Defaults {
    28
    29        /*!
    30         *  ======== common$ ========
    31         *  Defaults inherited by all target modules
    32         *
    33         *  This structure defines the default values for the configuration
    34         *  parameters shared by all modules in a system.  Unless otherwise
    35         *  noted, setting one of the fields defined below will set the
    36         *  corresponding value for all modules in the system which have not
    37         *  been explicitly set; i.e., it will establish a default value for
    38         *  the parameter.
    39         *
    40         *  However, the modules from this package (`xdc.runtime`) are an
    41         *  exception. The values from `Default.common$` are not copied to
    42         *  `logger` and `diags_` properties of `common$` in `xdc.runtime`
    43         *  modules. The property `diags_ASSERT` is an exception to that exception.
    44         *  Its value from 'Default.common$` is copied to all modules for which
    45         *  `diags_ASSERT` has not been explicitly set.
    46         *
    47         *  @a(diags_ASSERT)
    48         *  Enables asserts at runtime. Default is `ALWAYS_ON`
    49         *
    50         *  @a(diags_ENTRY)
    51         *  Enables entry trace for all functions. Default is `ALWAYS_OFF`
    52         *
    53         *  @a(diags_EXIT)
    54         *  Enables exit trace for all functions. Default is `ALWAYS_OFF`
    55         *
    56         *  @a(diags_INTERNAL)
    57         *  Enables internal asserts. Default is `ALWAYS_OFF`. When set to
    58         *  `ALWAYS_ON`, requires `diags_ASSERT` to be `ALWAYS_ON`.
    59         *
    60         *  @a(diags_LIFECYCLE)
    61         *  Enables logging of lifecycle events. These events are logged during
    62         *  creates and deletes. Default is `ALWAYS_OFF`.
    63         *
    64         *  @a(diags_STATUS)
    65         *  Enables logging of status events, such as error and warning events.
    66         *  Default is `ALWAYS_ON`. Note that this does not mean that logging will
    67         *  occur by default--a logger instance must also be configured for the
    68         *  module in order for events to be logged.
    69         *
    70         *  @a(diags_INFO)
    71         *  Enables logging of generic informational events. Default is
    72         *  `ALWAYS_OFF`.
    73         *
    74         *  @a(diags_ANALYSIS)
    75         *  Enables logging of analysis events, such as benchmarking events.
    76         *  Default is `ALWAYS_OFF`.
    77         *
    78         *  @a(diags_USER)
    79         *  Each `diags_USER` field controls a separate user-defined
    80         *  logging level. Default is `ALWAYS_OFF` for all `diags_USER` fileds.
    81         *
    82         *  @a(gate)
    83         *  Default gate used by all modules which are declared as being `@Gated`.
    84         *  By default, this parameter points to an instance of `{@link GateNull}`,
    85         *  which means there is no protection.
    86         *
    87         *  @a(gateParams)
    88         *  The default parameters used to create gates at runtime. See
    89         *  `{@link Types#Common$.gateParams}`.  Default is `null`.
    90         *
    91         *  @a(instanceHeap)
    92         *  Specify heap to be used for module instances. Default is `null`.
    93         *  If `instanceHeap` is `null`, instances will be allocated from
    94         *  the heap specified by `{@link Memory#defaultHeapInstance}`.
    95         *
    96         *  @a(instanceSection)
    97         *  Specify section to be used to place module instances. Default is
    98         *  `null`.
    99         *
   100         *  @a(logger)
   101         *  Default logger used by modules to write logs. By default there is
   102         *  no logger.
   103         *
   104         *  @a(memoryPolicy)
   105         *  Used to specify type of application. `Types.STATIC_POLICY` is used when
   106         *  all objects are created statically. `Types.CREATE_POLICY` is used when
   107         *  the application creates objects at runtime. `Types.DELETE_POLICY` is
   108         *  used when the application creates and deletes objects at runtime. This
   109         *  helps eliminate unwanted create and delete code.
   110         *
   111         *  @a(namedInstance)
   112         *  This parameter should be set to true if space needs to be allocated in
   113         *  instance objects for instance names. Allocating space for a name
   114         *  allows object view tools to display the names. The runtime functions
   115         *  `Mod_Handle_name()` and `Mod_Handle_label()` defined for each module
   116         *  `Mod` can be used to retrieve the name at runtime.
   117         *
   118         *  @a(namedModule)
   119         *  This field allows the name of the module to be retained on the target.
   120         *  Setting this to `false` will save space but will also prevent
   121         *  the target from being able to display the module names appearing
   122         *  in `Log` events and `Error`s.
   123         *
   124         *  Setting `namedModule` to `false` causes all modules, except for
   125         *  `{@link Memory}` and `{@link Main}` to be unnamed by default.  To
   126         *  eliminate the string names for these modules you must explicitly
   127         *  set their `common$.namedModule` parameters to `false`; without these
   128         *  two names, target-side display of error messages is somewhat cryptic.
   129         *
   130         *  @a(romPatchTable)
   131         *  Specify whether modules that are allocated to ROM are patchable.
   132         */
   133        override metaonly config Types.Common$ common$ = {
   134            diags_ASSERT:       Diags.ALWAYS_ON,
   135            diags_ENTRY:        Diags.ALWAYS_OFF,
   136            diags_EXIT:         Diags.ALWAYS_OFF,
   137            diags_INTERNAL:     Diags.ALWAYS_OFF,
   138            diags_LIFECYCLE:    Diags.ALWAYS_OFF,
   139            diags_STATUS:       Diags.ALWAYS_ON,
   140            diags_USER1:        Diags.ALWAYS_OFF,
   141            diags_USER2:        Diags.ALWAYS_OFF,
   142            diags_USER3:        Diags.ALWAYS_OFF,
   143            diags_USER4:        Diags.ALWAYS_OFF,
   144            diags_USER5:        Diags.ALWAYS_OFF,
   145            diags_USER6:        Diags.ALWAYS_OFF,
   146            diags_USER7:        Diags.ALWAYS_OFF,
   147            diags_INFO:         Diags.ALWAYS_OFF,
   148            diags_USER8:        Diags.ALWAYS_OFF,
   149            diags_ANALYSIS:     Diags.ALWAYS_OFF,
   150            fxntab:             true,
   151            gate:               null,
   152            gateParams:         null,
   153            instanceHeap:       null,
   154            instanceSection:    null,
   155            logger:             null,
   156            memoryPolicy:       Types.DELETE_POLICY,
   157            namedInstance:      false,
   158            namedModule:        true,
   159            romPatchTable:      false,
   160        };
   161
   162        /*!
   163         *  ======== noRuntimeCommon$ ========
   164         *  Defaults inherited by the target modules that do not need the runtime
   165         *  support.
   166         *
   167         *  Modules for which the attribute NoRuntime is set do not use any
   168         *  functionality controlled by the parameters in their `common$`
   169         *  structures. For such modules, these parameters are set to the
   170         *  following values, and cannot be changed, to guarantee that NoRuntime
   171         *  modules do not accidentally request functionality they don not use.
   172         */
   173        metaonly readonly config Types.Common$ noRuntimeCommon$ = {
   174            diags_ASSERT:       Diags.ALWAYS_OFF,
   175            diags_ENTRY:        Diags.ALWAYS_OFF,
   176            diags_EXIT:         Diags.ALWAYS_OFF,
   177            diags_INTERNAL:     Diags.ALWAYS_OFF,
   178            diags_LIFECYCLE:    Diags.ALWAYS_OFF,
   179            diags_STATUS:       Diags.ALWAYS_OFF,
   180            diags_USER1:        Diags.ALWAYS_OFF,
   181            diags_USER2:        Diags.ALWAYS_OFF,
   182            diags_USER3:        Diags.ALWAYS_OFF,
   183            diags_USER4:        Diags.ALWAYS_OFF,
   184            diags_USER5:        Diags.ALWAYS_OFF,
   185            diags_USER6:        Diags.ALWAYS_OFF,
   186            diags_USER7:        Diags.ALWAYS_OFF,
   187            diags_INFO:         Diags.ALWAYS_OFF,
   188            diags_USER8:        Diags.ALWAYS_OFF,
   189            diags_ANALYSIS:     Diags.ALWAYS_OFF,
   190            fxntab:             false,
   191            gate:               null,
   192            gateParams:         null,
   193            instanceHeap:       null,
   194            instanceSection:    null,
   195            logger:             null,
   196            memoryPolicy:       Types.STATIC_POLICY,
   197            namedInstance:      false,
   198            namedModule:        false,
   199            romPatchTable:      false,
   200        };
   201
   202        /*!
   203         *  ======== getCommon ========
   204         *  Get a specified common parameter from a module
   205         *
   206         *  Get the value of a member of the structure `common$` based on
   207         *  defaults and the current value of the parameter. If the current value
   208         *  of `param` is `undefined`, the function returns the default value
   209         *  for that parameter from `Default.common$`.
   210         *
   211         *  @param(eb)  module whose parameter is queried
   212         *
   213         *  @param(param)   string naming the queried parameter
   214         *
   215         *  @a(returns)
   216         *  Returns the value of the parameter named `param` from the module
   217         *  `mod`.
   218         */
   219        metaonly Any getCommon(IModule.Module mod, String param);
   220    };
   221    /*
   222     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   223     */
   224


module xdc.runtime.Diags

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Diags.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== Diags ========
    19     *  Diagnostics manager
    20     *
    21     *  Every XDC module has a "diagnostics mask" that allows clients to
    22     *  enable or disable diagnostics on a per module basis both at
    23     *  configuration time and at runtime. The `Diags` module manages a
    24     *  module's diagnostics mask.
    25     *
    26     *  You use the `Diags` module to set and clear bits in a module's
    27     *  diagnostics mask for the purpose of controlling diagnostics
    28     *  within that module. Each bit corresponds to a "category" of diagnostic
    29     *  that can be individually enabled or disabled.
    30     *
    31     *  A module's diagnostics mask controls both `{@link Assert}` and
    32     *  `{@link Log}` statements within that module. A module's diagnostics
    33     *  mask may also be used to conditionally execute blocks of code using
    34     *  the `{@link #query Diags_query()}` runtime function.
    35     *
    36     *  A module's diagnostics mask can be set at configuration time and
    37     *  at runtime. The implementation of diagnostics is such that when they
    38     *  are permanently turned off at configuration time
    39     *  (`{@link #ALWAYS_OFF Mode.ALWAYS_OFF}`), an optimizer can
    40     *  completely eliminate the diagnostics code from the program. Similarly,
    41     *  if diagnostics are permanently turned on at configuration time
    42     *  (`{@link #ALWAYS_ON Mode.ALWAYS_ON}`), the optimizer can
    43     *  eliminate all runtime conditional checking and simply
    44     *  invoke the diagnostics code directly. Runtime checking of the
    45     *  diagnostics mask is performed only when the diagnostics are configured
    46     *  to be runtime modifiable (`{@link #RUNTIME_OFF Mode.RUNTIME_OFF}` or
    47     *  `{@link #RUNTIME_ON Mode.RUNTIME_ON}`).
    48     *
    49     *  Each bit of the diagnostics mask is controlled by one of the following
    50     *  constants.
    51     *
    52     *  @p(code)
    53     *  Constant    Meaning
    54     *  --------------------------
    55     *  ENTRY       Function entry
    56     *  EXIT        Function exit
    57     *  LIFECYCLE   Object life-cycle
    58     *  INTERNAL    Internal diagnostics
    59     *  ASSERT      Assert checking
    60     *  STATUS      Warning or Error events
    61     *  USER1       User defined diagnostics
    62     *  USER2       User defined diagnostics
    63     *  USER3       User defined diagnostics
    64     *  USER4       User defined diagnostics
    65     *  USER5       User defined diagnostics
    66     *  USER6       User defined diagnostics
    67     *  USER7       User defined diagnostics
    68     *  INFO        Informational event
    69     *  USER8       User defined diagnostics
    70     *  ANALYSIS    Analysis event
    71     *  @p
    72     *
    73     *  These constants can be used from either JavaScript configuration
    74     *  scripts or C code and, therefore, have two "names". For example,
    75     *  to reference the ENTRY constant from JavaScript you must use
    76     *  `Diags.ENTRY` whereas from C you would use `Diags_ENTRY`.
    77     *
    78     *  The `ENTRY` and `EXIT` categories are for log statements at the entry and
    79     *  exit points, respectively, to each function within a module. This
    80     *  is useful for tracking the execution flow of your program.
    81     *
    82     *  The `LIFECYCLE` category is for log events at the create/construct
    83     *  and delete/destruct points of each instance object for the module.
    84     *  This is useful for tracking the life-cycle of a module instance object.
    85     *
    86     *  `ASSERT` and `INTERNAL` are unique in that they are not related to logging,
    87     *  but instead control the Assert statements in a module. These categories
    88     *  control the two classes of asserts:
    89     *
    90     *  @p(blist)
    91     *  - Public asserts, which have an `{@link Assert#Id Assert_Id}` and
    92     *  are documented in the module's reference pages. These asserts are
    93     *  on by default and are meant to help developers validate code that
    94     *  invokes a module's functions.
    95     *  - Internal asserts, which have no `{@link Assert#Id Assert_Id}`.
    96     *  These asserts are off by default and are typically used only when
    97     *  developing code. That is, like the standard C assert() mechanism,
    98     *  these asserts are not part of a deployed application.
    99     *  @p
   100     *
   101     *  When a module has enabled the `ASSERT` category (which is enabled by
   102     *  default) in its diagnostics mask, the module executes all of its public
   103     *  assert statements. To enable internal asserts, you must enable both the
   104     *  `ASSERT` and `INTERNAL` categories.
   105     *
   106     *  The `ASSERT` and `INTERNAL` categories are not intended for use as log
   107     *  event categories. If an event is defined with either of these categories,
   108     *  you will receive a validation error during configuration.
   109     *
   110     *  The `STATUS` category is used for error and warning type events. The
   111     *  four event levels within the `STATUS` category have defined meanings,
   112     *  see {@link #EMERGENCY}
   113     *
   114     *  The `INFO` category is used for generic informational events. Any event
   115     *  which does not belong to a more specific category of events may simply
   116     *  be an `INFO` event.
   117     *
   118     *  The `ANALYSIS` category is used for events related to benchmarks and
   119     *  performance analysis.
   120     *
   121     *  The `USER1`-`6` categories are available to each module writer to use as
   122     *  he or she wishes.
   123     *
   124     *  The USER7 and USER8 categories are still defined, but their bits have been
   125     *  repurposed for the INFO and ANALYSIS categories, respectively, so the use
   126     *  of USER7 and USER8 has been deprecated.
   127     *
   128     *  @a(Examples)
   129     *  Configuration example: The following XDC configuration statements set
   130     *  a module's diagnostics mask in a configuration script. (In this case,
   131     *  the `Task` module of the `ti.sysbios.knl` package is used.) In this
   132     *  example, the `ENTRY` bit is turned on and the `EXIT` bit is turned off.
   133     *  Both bits are configured to be runtime modifiable.
   134     *
   135     *  @p(code)
   136     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   137     *  var Task = xdc.useModule('ti.sysbios.knl.Task');
   138     *
   139     *  Task.common$.diags_ENTRY = Diags.RUNTIME_ON;
   140     *  Task.common$.diags_EXIT = Diags.RUNTIME_OFF;
   141     *  @p
   142     *
   143     *  @p(html)
   144     *  <hr />
   145     *  @p
   146     *
   147     *  Runtime example: The following C code shows how to disable and
   148     *  reenable `ENTER` diagnostics at runtime for the `ti.sysbios.knl.Task`
   149     *  module configured in the previous example. The first call to
   150     *  `{@link Diags#setMask Diag_setMask()}` enables entry diagnostics
   151     *  (`"+E"`) for just the `ti.sysbios.knl.Task` module; any call to any
   152     *  `Task` method in the application causes an "entry" `Log` event to be
   153     *  generated. The second call disables ("-E") the generation of these
   154     *  events. See `{@link #setMask Diags_setMask()}` for a complete
   155     *  description of the strings accepted by this function.
   156     *
   157     *  @p(code)
   158     *  #include <xdc/runtime/Diags.h>
   159     *  :
   160     *  Diags_setMask("ti.sysbios.knl.Task+E");
   161     *  :
   162     *  Diags_setMask("ti.sysbios.knl.Task-E");
   163     *  @p
   164     *
   165     *  @p(html)
   166     *  <hr />
   167     *  @p
   168     *
   169     *  Configuration example: The following XDC configuration statements
   170     *  turn on asserts in the entire program.
   171     *
   172     *  @p(code)
   173     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   174     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
   175     *
   176     *  Defaults.diags_ASSERT = Diags.ALWAYS_ON;
   177     *  @p
   178     *
   179     *  @p(html)
   180     *  <hr />
   181     *  @p
   182     *
   183     *  Configuration example: Using the
   184     *  `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function, the
   185     *  following XDC configuration statements turn on asserts in all
   186     *  of the modules whose name begins with "`ti.sysbios.`" In this case,
   187     *  no change to the application code is necessary to enable these
   188     *  events. It is important to note that, while the configuration
   189     *  step must be re-run and the application must be re-linked, no
   190     *  application sources need to be recompiled.
   191     *
   192     *  @p(code)
   193     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   194     *  Diags.setMaskMeta("ti.sysbios.%", Diags.ASSERT, Diags.ALWAYS_ON);
   195     *  @p
   196     */
   197
   198    @CustomHeader
   199    @Template("./Diags.xdt")
   200
   201    module Diags {
   202
   203        /*!
   204         *  ======== Mode ========
   205         *  Diagnostics mask bit value used at configuration time.
   206         *
   207         *  At run-time a module's diagnostics mask is an ordinary data word
   208         *  with each bit value being 0 or 1 indicating whether or not the
   209         *  corresponding diagnostic is disabled or enabled.  At configuration
   210         *  time, however, each bit of the diagnostics mask can be
   211         *  placed in one of several `Mode`s; these modes determine its initial
   212         *  runtime value and whether or not the bit is modifiable at runtime.
   213         *
   214         *  When setting a module's diagnostics mask at configuration time,
   215         *  use one of the enumerated values of type `Mode`. These
   216         *  values will either set or clear a bit in the mask and also define
   217         *  if the bit can be changed at run-time. For example, using
   218         *  `ALWAYS_OFF` as the bit value means that bit cannot be set
   219         *  at run-time. This fact can be used by an optimizer to perform
   220         *  constant-folding and dead-code elimination.
   221         */
   222        metaonly enum Mode {
   223            ALWAYS_OFF,     //! permanently disabled
   224            ALWAYS_ON,      //! permanently enabled
   225            RUNTIME_OFF,    //! run-time settable, initially disabled
   226            RUNTIME_ON      //! run-time settable, initially enabled
   227        };
   228
   229        /*! Type used to specify bits in the diags mask. */
   230        typedef Types.DiagsMask Mask;
   231
   232        const Mask ENTRY        = 0x0001;   //! Function entry
   233        const Mask EXIT         = 0x0002;   //! Function exit
   234        const Mask LIFECYCLE    = 0x0004;   //! Object life-cycle
   235        const Mask INTERNAL     = 0x0008;   //! Internal diagnostics
   236
   237        const Mask ASSERT       = 0x0010;   //! Assert checking
   238
   239        const Mask STATUS       = 0x0080;   //! Warning or error event
   240
   241        /*! @_nodoc */
   242        const Mask LEVEL        = 0x0060;   //! Mask to retrieve the level bits
   243
   244        const Mask USER1        = 0x0100;   //! User defined diagnostics
   245        const Mask USER2        = 0x0200;   //! User defined diagnostics
   246        const Mask USER3        = 0x0400;   //! User defined diagnostics
   247        const Mask USER4        = 0x0800;   //! User defined diagnostics
   248
   249        const Mask USER5        = 0x1000;   //! User defined diagnostics
   250        const Mask USER6        = 0x2000;   //! User defined diagnostics
   251        const Mask USER7        = 0x4000;   //! Alias for informational event
   252        const Mask INFO         = USER7;    //! Informational event
   253        const Mask USER8        = 0x8000;   //! Alias for analysis event
   254        const Mask ANALYSIS     = USER8;    //! Analysis (e.g., benchmark) event
   255
   256        /*!
   257         *  ======== ALL ========
   258         *  Mask of all diagnostics categories, including both logging and asserts
   259         */
   260        const Mask ALL          = 0xFF9F;
   261
   262        /*!
   263         *  ======== ALL_LOGGING ========
   264         *  Mask of all logging diagnostic categories (does not include asserts)
   265         */
   266        const Mask ALL_LOGGING  = ALL & (~ASSERT) & (~INTERNAL);
   267
   268        /*!
   269         *  ======== EventLevel =========
   270         *  The level of an event.
   271         *
   272         *  The diagnostics bits each represent a different category of event,
   273         *  for example: an analysis event, a lifecycle event, or an informational
   274         *  event. Within each of these categories, events may have one of four
   275         *  levels to enable filtering based on the level of information desired.
   276         *
   277         *  The meaning of these levels and the distinction between them is left
   278         *  open to the user. Depending on the meaning given, different terminology
   279         *  may be used to describe them--they may be levels of detail, priority,
   280         *  severity, etc. The heirarchy of the events is set such that `LEVEL1` is
   281         *  the highest priority and `LEVEL4` is the lowest. That is, enabling
   282         *  `LEVEL4` events implies that events of all four levels will be logged.
   283         *  @p(dlist)
   284         *      - `LEVEL1`
   285         *        Least detail, highest priority, most severe, etc.
   286         *      - `LEVEL2`
   287         *      - `LEVEL3`
   288         *      - `LEVEL4`
   289         *        Most detail, lowest priority, least severe, etc.
   290         *  @p
   291         *  The `STATUS` bit is the only category where the levels are given
   292         *  explicit meaning to ensure consistency. Within the `STATUS` category,
   293         *  the meaning of the levels is defined by the constants `EMERGENCY`,
   294         *  `CRITICAL`, `ERROR`, and `WARNING`.
   295         *
   296         *  Events which don't define a level will receive `LEVEL1` by default.
   297         */
   298        enum EventLevel {
   299            LEVEL1 = 0x0,
   300            LEVEL2 = 0x20,
   301            LEVEL3 = 0x40,
   302            LEVEL4 = 0x60
   303        };
   304
   305        /*!
   306         *  ======== EMERGENCY ========
   307         *  A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'
   308         *
   309         *  For STATUS events only, the meaning of the four EventLevels has been
   310         *  defined. These constants are simply aliases for the four event levels.
   311         *
   312         *  The highest three levels are different severities of an error event.
   313         *  For example, an EMERGENCY event may represent an unrecoverable system
   314         *  failure, a CRITICAL event may require notification of an operator,
   315         *  and an ERROR may be a recoverable error.
   316         *
   317         *  The lowest level is reserved for warnings, such as when a resource
   318         *  becomes dangerously low.
   319         */
   320        const EventLevel EMERGENCY = LEVEL1;
   321
   322        /*!
   323         *  ======== CRITICAL ========
   324         *  A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'
   325         *
   326         *  See '{@link #EMERGENCY}' for details.
   327         */
   328        const EventLevel CRITICAL = LEVEL2;
   329
   330        /*!
   331         *  ======== ERROR ========
   332         *  A 'LEVEL3' 'STATUS' event is defined as 'ERROR'
   333         *
   334         *  See '{@link #EMERGENCY}' for details.
   335         */
   336        const EventLevel ERROR = LEVEL3;
   337
   338        /*!
   339         *  ======== WARNING ========
   340         *  A 'LEVEL4' 'STATUS' event is defined as 'WARNING'
   341         *
   342         *  See '{@link #EMERGENCY}' for details.
   343         */
   344        const EventLevel WARNING = LEVEL4;
   345
   346        /*!
   347         *  ======== DiagsMaskView ========
   348         *  @_nodoc
   349         */
   350        metaonly struct DiagsMaskView {
   351            String Module;
   352            String logger;
   353            String USER1;
   354            String USER2;
   355            String USER3;
   356            String USER4;
   357            String USER5;
   358            String USER6;
   359            String INFO;
   360            String ANALYSIS;
   361            String STATUS;
   362            String ENTRY;
   363            String EXIT;
   364            String LIFECYCLE;
   365            String INTERNAL;
   366            String ASSERT;
   367        }
   368
   369        /*!
   370         *  ======== rovViewInfo ========
   371         *  @_nodoc
   372         */
   373        @Facet
   374        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   375            xdc.rov.ViewInfo.create({
   376                viewMap: [
   377                    ['DiagsMasks',
   378                        {
   379                            type: xdc.rov.ViewInfo.TREE_TABLE,
   380                            viewInitFxn: 'viewInitDiagsMasks',
   381                            structName: 'DiagsMaskView'
   382                        }
   383                    ]
   384                ]
   385            });
   386
   387        /*!
   388         *  ======== query ========
   389         *  Query the module's diagnostics mask against the given mask
   390         *
   391         *  Use this query function to test the state of a module's
   392         *  diagnostics mask at runtime. This function will perform a logical
   393         *  `AND` operation on the module's diagnostics mask and the given mask.
   394         *  If any bits survive the operation, the function returns `true`.
   395         *
   396         *  @p(code)
   397         *  result = moduleMask & givenMask ? true : false;
   398         *  @p
   399         *
   400         *  This query function has a compile-time binding to the module's
   401         *  diagnostics mask. If the query function is part of the C code
   402         *  implementation of a module, then it will use that module's
   403         *  diagnostics mask. Otherwise, it will use the diagnostics mask
   404         *  of the `{@link Main xdc.runtime.Main}` module.
   405         *
   406         *  The implementation of the diagnostics mask and the query function
   407         *  is such that an optimizer can take advantage of dead code elimination
   408         *  and/or constant folding to eliminate or reduce code size. For example,
   409         *  if the query function is used in a conditional test, and the given
   410         *  mask contains only bits which have been configured to be permanently
   411         *  off, then the code for the entire conditional statement can be removed
   412         *  at link time. If the bits in the given mask have been configured to be
   413         *  permanently on, then the conditional code can be removed leaving the
   414         *  body of the conditional as direct in-line code.
   415         *
   416         *  @param(mask) mask of diagnostics bits to test
   417         *
   418         *  This given mask is constructed by `OR`'ing together
   419         *  the desired bits of the diagnostics mask using the constants listed
   420         *  in the {@link #ALL Mask Summary} above. The module's diagnostics
   421         *  mask will be logically `AND`'ed with the given mask, and return `true`
   422         *  if the result is non-zero and `false` otherwise.
   423         *
   424         *  @p(code)
   425         *      if (Diags_query(Diags_USER1 | Diags_USER4)) {
   426         *          :
   427         *      }
   428         *  @p
   429         *
   430         *  @a(Examples)
   431         *  In the following example, the `{@link #USER1 USER1}` bit of the
   432         *  module's diagnostics mask has been configured to be permanently off,
   433         *  thus the entire conditional code block can be removed at link time.
   434         *  Note, the C code below is part of the module itself.
   435         *
   436         *  Configuration Script
   437         *  @p(code)
   438         *  var Diags = xdc.useModule('xdc.runtime.Diags');
   439         *  var ModA = xdc.useModule('my.package.ModuleA');
   440         *  ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
   441         *  @p
   442         *
   443         *  C Code, ModA.c
   444         *  @p(code)
   445         *  if (Diags_query(Diags_USER1)) {         // this code removed
   446         *      ...additional code here...          // this code removed
   447         *  }                                       // this code removed
   448         *  @p
   449         *
   450         *  @p(html)
   451         *  <hr />
   452         *  @p
   453         *
   454         *  In the following example, the `{@link #USER1 USER1}` bit of the
   455         *  module's diagnostics mask has been configured to be permanently on,
   456         *  thus the conditional code can be removed leaving the code contained
   457         *  within the conditional statement. Note, the C code below is part of
   458         *  the module itself.
   459         *
   460         *  Configuration Script
   461         *  @p(code)
   462         *  var Diags = xdc.useModule('xdc.runtime.Diags');
   463         *  var ModA = xdc.useModule('my.package.ModuleA');
   464         *  ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
   465         *  @p
   466         *
   467         *  C Code, ModA.c
   468         *  @p(code)
   469         *  if (Diags_query(Diags_USER1) {          // this code removed
   470         *      ...additional code here...          // this code remains
   471         *  }                                       // this code removed
   472         *  @p
   473         *
   474         */
   475        @Macro Bool query(Mask mask);
   476
   477        /*!
   478         *  ======== getLevel ========
   479         *  Get the event level set in the given mask
   480         *
   481         *  See '{@link #EventLevel}' for a description of event levels.
   482         *
   483         *  @param(mask) mask of diagnostics bits to read filter level from.
   484         */
   485        @Macro EventLevel getLevel(Mask mask);
   486
   487        /*!
   488         *  ========= compareLevels ========
   489         *  Returns false if levelA is lower than levelB
   490         *
   491         *  This API is intended to be used to determine if a given event
   492         *  passes a filtering threshold and should be logged. Conceptually (though
   493         *  not necessarily in implementation), this API is equivalent to the
   494         *  expression (levelA < levelB). The values of the EventLevels have
   495         *  internal meaning, so a direct comparison of two levels should not done;
   496         *  this API must be used to correctly compare them.
   497         *
   498         *  LEVEL1 is the highest level and LEVEL4 is the lowest. So LEVEL4 is
   499         *  less than LEVEL3, which is less than LEVEL2, which is less than LEVEL1.
   500         */
   501        @Macro Bool compareLevels(EventLevel levelA, EventLevel levelB);
   502
   503        /*!
   504         *  ======== setMask ========
   505         *  Set a module's diagnostics mask at runtime
   506         *
   507         *  Use the given control string to set or clear bits in a module's
   508         *  diagnostics mask. The control string defines one or more actions
   509         *  where each action modifies the diagnostics mask in one or more
   510         *  modules. Each action can either set, clear, or assign a module's
   511         *  diagnostics mask. To both set and clear bits in the same diagnostics
   512         *  mask requires two actions, or you can assign the entire mask
   513         *  explicitly in one action. Each action can specify a given module or
   514         *  a set of modules using name prefix matching.
   515         *
   516         *  @a(Warning)
   517         *
   518         *  Each bit of a module's diagnostics mask that is to be modified at
   519         *  runtime, must be configured to be runtime modifiable in the
   520         *  program's configuration script. Use either `{@link #Mode RUNTIME_OFF}`
   521         *  or `{@link #Mode RUNTIME_ON}` as the configuration value for the
   522         *  desired bit in the diagnostics mask. In addition, the
   523         *  `{@link Diags#setMaskEnabled Diags.setMaskEnabled}` configuration
   524         *  parameter must be set to `true` in order to load this function onto
   525         *  the target. Finally, the following configuration parameters must
   526         *  have the values indicated (which are their default values):
   527         *
   528         *  @p(blist)
   529         *  - `{@link IModule#common$ <module>.common$.namedModule} = true;`
   530         *  - `{@link Text#isLoaded} = true;`
   531         *  @p
   532         *
   533         *  Note: any error that occurs during the parsing of the control string
   534         *  causes `Diags_setmask()` to return without processing the remainder
   535         *  of the control string.
   536         *
   537         *  @param(control) diagnostic mask control string
   538         *
   539         *  This control string defines one or more actions
   540         *  where each action consists of a module name, an operator character,
   541         *  and a list of bit specifiers. Use the `%` character as a wildcard
   542         *  to turn the module name into a prefix matching pattern for a set
   543         *  of modules. Multiple actions are separated with the `;` character.
   544         *
   545         *  @p
   546         *  The control string has the following format:
   547         *
   548         *  @p(code)
   549         *  <module[%]><op><bits>[;<module[%]><op><bits>]
   550         *  @p
   551         *
   552         *  Specify individual module names explicitly (e.g.
   553         *  `ti.sysbios.knl.Task`), or match multiple modules using a prefix
   554         *  matching pattern specified with the `%` character (e.g.
   555         *  `ti.sysbios.knl.%`).
   556         *
   557         *  @p
   558         *  The operator is specified with a single character from the following
   559         *  table.
   560         *
   561         *  @p(code)
   562         *  Operator    Description
   563         *  --------------------------------------------------
   564         *  +           Set only the specified bits (other bits preserved)
   565         *  -           Clear only the specified bits (other bits preserved)
   566         *  =           Assign the entire mask to the given value where the
   567         *              specified bits are set and all other bits are cleared
   568         *  @p
   569         *
   570         *  The bits are specified with a list of characters from the following
   571         *  table. Refer to the {@link #ALL Mask Summary} for a list of each
   572         *  bit of the diagnostics mask.
   573         *
   574         *  @p(code)
   575         *  Control     Diagnostics
   576         *  Character   Constant        Description
   577         *  --------------------------------------------------
   578         *  E           ENTRY           Function entry
   579         *  X           EXIT            Function exit
   580         *  L           LIFECYCLE       Object life-cycle
   581         *  I           INTERNAL        Internal diagnostics
   582         *  A           ASSERT          Assert checking
   583         *  Z           ANALYSIS        Analysis event
   584         *  F           INFO            Informational event
   585         *  S           STATUS          Status (error, warning) event
   586         *  1           USER1           User defined diagnostics
   587         *  2           USER2           User defined diagnostics
   588         *  3           USER3           User defined diagnostics
   589         *  4           USER4           User defined diagnostics
   590         *  5           USER5           User defined diagnostics
   591         *  6           USER6           User defined diagnostics
   592         *  7           USER7           User defined diagnostics
   593         *  8           USER8           User defined diagnostics
   594         *  @p
   595         *
   596         *  @a(Examples)
   597         *  The following example demonstrates how to set a module's diagnostics
   598         *  mask (the `Task` module in this case) at runtime. In this example, the
   599         *  `{@link #USER1 USER1}` bit is turned on. Note that the module's
   600         *  `{@link #USER1 USER1}` diagnostics bit must be configured to be runtime
   601         *  modifiable. In this instance, the bit is initialized to off.
   602         *
   603         *  Configuration Script
   604         *  @p(code)
   605         *  var Diags = xdc.useModule('xdc.runtime.Diags');
   606         *  var Task = xdc.useModule('ti.sysbios.knl.Task');
   607         *  Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
   608         *  @p
   609         *
   610         *  C Code
   611         *  @p(code)
   612         *  Diags_setMask("ti.sysbios.knl.Task+1");
   613         *  @p
   614         *
   615         *  @p(html)
   616         *  <hr />
   617         *  @p
   618         *
   619         *  The following example demonstrates the use of the `%` wildcard
   620         *  character to set the `{@link #USER1 USER1}` bit at runtime for
   621         *  all modules in the `ti.sysbios.knl` package. The meta-only
   622         *  `{@link #setMaskMeta Diags.setMaskMeta}` function is used to configure
   623         *  the `{@link #USER1 USER1}` bit to be runtime modifiable. The `setMask`
   624         *  function is used to actually set the `{@link #USER1 USER1}` bit at
   625         *  runtime in all the `ti.sysbios.knl` modules.
   626         *  Note the use of the `%` character in both functions to match all the
   627         *  module names within the given package.
   628         *
   629         *  Configuration Script
   630         *  @p(code)
   631         *  var Diags = xdc.useModule('xdc.runtime.Diags');
   632         *  Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
   633         *  @p
   634         *
   635         *  C Code
   636         *  @p(code)
   637         *  Diags_setMask("ti.sysbios.knl.%+1");
   638         *  @p
   639         *
   640         *  @p(html)
   641         *  <hr />
   642         *  @p
   643         *
   644         *  In the following example, the `{@link #ENTRY ENTRY}`,
   645         *  `{@link #EXIT EXIT}` and `{@link #LIFECYCLE LIFECYCLE}` trace is
   646         *  enabled for all modules in the `ti.sysbios.knl` package but is
   647         *  initially off; i.e., no events will occur until explicitly turned
   648         *  on at runtime.
   649         *
   650         *  At runtime the call to `Diags_setMask` turns on
   651         *  `{@link #ENTRY ENTRY}` and `{@link #EXIT EXIT}` trace and turns off
   652         *  `{@link #LIFECYCLE LIFECYCLE}` trace for all modules in
   653         *  the application for which trace has been enabled during
   654         *  configuration.  In this case, the only modules that can generate
   655         *  events are those in the `ti.sysbios.knl` package.
   656         *
   657         *  Configuration Script
   658         *  @p(code)
   659         *  var Diags = xdc.useModule('xdc.runtime.Diags');
   660         *  Diags.setMaskMeta("ti.sysbios.knl.%",
   661         *      Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
   662         *  @p
   663         *
   664         *  C Code
   665         *  @p(code)
   666         *  Diags_setMask("%+EX;%-L");
   667         *  @p
   668         */
   669        Void setMask(String control);
   670
   671        /*!
   672         *  ======== setMaskMeta ========
   673         *  Set the module's diagnostics mask at config time
   674         *
   675         *  @param(pattern) module prefix or regular expression
   676         *
   677         *  The `pattern` is used to match a module's name. If `pattern` is
   678         *  specified as a string, then name prefix matching is used. The
   679         *  pattern may also be a regular expression.  Only the masks of the
   680         *  modules matching `pattern` are set.
   681         *
   682         *  @param(mask) diagnostic fields to modify
   683         *
   684         *  The `mask` is used to determine which fields in the diags mask are
   685         *  modified. Each field specified in the mask is set to the given
   686         *  `mode` value.
   687         *
   688         *  @param(mode) mode to assign to the specified `mask` fields
   689         */
   690        metaonly Void setMaskMeta(Any pattern, Mask mask, Mode mode);
   691
   692    internal:
   693
   694        /*!
   695         *  ======== setMaskEnabled ========
   696         *  Controls the ability to set the diags mask at run-time
   697         *
   698         *  This configuration parameter allows whole program optimizers to reduce
   699         *  the code size. The default is `false`, which means the diags mask will
   700         *  not be modified at run-time and thus the code is not needed.
   701         *
   702         *  For now, this should be internal because its value is determined
   703         *  automatically, rather than through user's input. See CQ19111 for more
   704         *  details.
   705         */
   706        config Bool setMaskEnabled = false;
   707
   708        /*
   709         *  ======== dictBase ========
   710         *  Array of module-id:diags-mask pairs in which each module is named
   711         *
   712         *  This array, generated by Diags.xdt, is terminated by an element
   713         *  with modId == 0.
   714         */
   715        config DictElem *dictBase = null;
   716
   717        struct DictElem {
   718            Types.ModuleId  modId;      /* statically computed module id */
   719            Mask           *maskAddr;   /* module's diags mask address */
   720        };
   721    }
   722    /*
   723     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   724     */
   725


module xdc.runtime.Error

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Error.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== Error ========
    19     *  Runtime error manager
    20     *
    21     *  The `Error` module provides mechanisms for raising, checking, and
    22     *  handling errors in a program. You can configure it via the
    23     *  `{@link Error#policy Error.policy}` and
    24     *  `{@link Error#raiseHook Error.raiseHook}` configuration parameters.
    25     *
    26     *  Modules may define specific error types and reference these when
    27     *  raising an error. Each error type has a custom error message and
    28     *  can be parameterized with up to `{@link #NUMARGS}` arguments. A
    29     *  generic error type is provided for raising errors when not in a module.
    30     *
    31     *  Use the `{@link #check Error_check()}` function to determine if an
    32     *  error has been raised. It is important to understand that it is the
    33     *  caller's responsibility to check the error block after calling a
    34     *  function that takes an error block as an argument. Otherwise, a raised
    35     *  error may go undetected, which could compromise the integrity of the
    36     *  system. For example:
    37     *
    38     *  @p(code)
    39     *  Task_create(..., &eb);
    40     *
    41     *  if (Error_check(&eb)) {
    42     *      ...an error has been raised...
    43     *  }
    44     *  @p
    45     *
    46     *  The `{@link #raiseHook Error.raiseHook}` configuration parameter allows
    47     *  a configured function to be invoked when any error is raised. This
    48     *  function is passed a pointer to the error's error block and makes it
    49     *  easy to manage all errors from a common point. For example, you can
    50     *  trap any error (fatal or not) by simply setting a breakpoint in this
    51     *  function. You can use the following functions to extract information
    52     *  from an error block.
    53     *
    54     *  @p(blist)
    55     *  - `{@link #getData Error_getData()}`
    56     *  - `{@link #getCode Error_getCode()}`
    57     *  - `{@link #getId Error_getId()}`
    58     *  - `{@link #getMsg Error_getMsg()}`
    59     *  - `{@link #getSite Error_getSite()}`
    60     *  @p
    61     *
    62     *  The Error module provides facilities for handling errors, but the Log
    63     *  module also provides features for logging error events. These are separate
    64     *  concepts; however, to ensure that users do not have to both raise and log
    65     *  an error, the Error module will automatically log an error event when one
    66     *  is raised. The Error module logs the standard {@link Log#L_error} event,
    67     *  passing it the error message and arguments.
    68     *
    69     *  The error event is logged to the Error module's logger using the Error
    70     *  module's diags mask. Logging of errors is enabled by default in the diags
    71     *  mask, but the event will not be logged unless a logger is configured for
    72     *  the Error module as well.
    73     *
    74     *  To make the error event appear as though it is coming from the module which
    75     *  called Error_raise, the event is logged with the caller's module id and
    76     *  with the caller's call site information.
    77     *
    78     *  @a(Examples)
    79     *  Example 1: The following example shows how a module, named ModA,
    80     *  defines a custom error type and shows how this error is raised by
    81     *  the module. The module defines an `Id` of `E_notEven` in its module
    82     *  specification file (in this case, `ModA.xdc`). The error's message
    83     *  string takes only one argument. The module also defines a `mayFail()`
    84     *  function that takes an error block. In the module's C source file,
    85     *  the function checks for the error condition and raises the error if
    86     *  needed.
    87     *
    88     *  This is part of ModA's XDC specification file for the module:
    89     *
    90     *  @p(code)
    91     *  config xdc.runtime.Error.Id E_notEven = {
    92     *      msg: "expected an even number (%d)"
    93     *  };
    94     *
    95     *  Void mayFail(Int x, xdc.runtime.Error.Block *eb);
    96     *  @p
    97     *
    98     *  This is part of the C code for the module:
    99     *
   100     *  @p(code)
   101     *  Void ModA_mayFail(Int x, Error_Block *eb)
   102     *  {
   103     *      if ((x % 2) != 0) {
   104     *          Error_raise(eb, ModA_E_notEven, x, 0);
   105     *          ...add error handling code here...
   106     *          return;
   107     *      }
   108     *      ...
   109     *  }
   110     *  @p
   111     *
   112     *  @p(html)
   113     *  <hr />
   114     *  @p
   115     *
   116     *  Example 2: The following C code supplies an error block to a function
   117     *  that requires one and tests the error block to see if the function
   118     *  raised an error. Note that an error block must be initialized before
   119     *  it can be used and same error block may be passed to several functions.
   120     *
   121     *  @p(code)
   122     *  #include <xdc/runtime/Error.h>
   123     *  #include <ti/sysbios/knl/Task.h>
   124     *  Error_Block eb;
   125     *  Task_Handle tsk;
   126     *
   127     *  Error_init(&eb);
   128     *  tsk = Task_create(..., &eb);
   129     *
   130     *  if (Error_check(&eb)) {
   131     *      ...an error has been raised...
   132     *  }
   133     *  @p
   134     *
   135     *  @p(html)
   136     *  <hr />
   137     *  @p
   138     *
   139     *  Example 3: The following C code shows that you may pass `NULL` to a
   140     *  function requiring an error block. In this case, if the function
   141     *  raises an error, the program is aborted (via
   142     *  `{@link System#abort xdc_runtime_System_abort()}`), thus execution
   143     *  control will never return to the caller.
   144     *
   145     *  @p(code)
   146     *  #include <xdc/runtime/Error.h>
   147     *  #include <ti/sysbios/knl/Task.h>
   148     *
   149     *  tsk = Task_create(..., NULL);
   150     *  ...will never get here if an error was raised in Task_create...
   151     *  @p
   152     *
   153     *  @p(html)
   154     *  <hr />
   155     *  @p
   156     *
   157     *  Example 4: The following C code shows how to write a function that
   158     *  is not part of a module and that takes an error block and raises
   159     *  the generic error type provided by the Error module. Note, if the
   160     *  caller passes `NULL` for the error block or if the error policy is
   161     *  `{@link #Policy TERMINATE}`, then the call to
   162     *  `{@link #raise Error_raise()}` will call
   163     *  `{@link System#abort xdc_runtime_System_abort()}` and never return.
   164     *
   165     *  @p(code)
   166     *  #include <xdc/runtime/Error.h>
   167     *
   168     *  Void myFunc(..., Error_Block *eb)
   169     *  {
   170     *      ...
   171     *
   172     *      if (...error condition detected...) {
   173     *          String  myErrorMsg = "my custom error message";
   174     *          Error_raise(eb, Error_E_generic, myErrorMsg, 0);
   175     *          ...add error handling code here...
   176     *          return;
   177     *      }
   178     *  }
   179     *  @p
   180     */
   181
   182    module Error {
   183
   184        /*!
   185         *  ======== Policy ========
   186         *  Error handling policies
   187         *
   188         *  Regardless of the current policy in use, raising an error by
   189         *  calling `{@link #raise Error_raise}` will always invoke the
   190         *  error raise hook function assigned to the
   191         *  `{@link #raiseHook Error.raiseHook}` configuration parameter.
   192         *
   193         *  @field(TERMINATE) All raised errors are fatal. A call to
   194         *  `{@link #raise Error_raise}` will never return to the caller.
   195         *
   196         *  @field(UNWIND) Errors are returned to the caller. A call to
   197         *  `{@link #raise Error_raise}` will return back to the caller.
   198         */
   199        enum Policy {
   200            TERMINATE,
   201            UNWIND
   202        };
   203
   204        /*!
   205         *  ======== Desc ========
   206         *  Error descriptor
   207         *
   208         *  Each type of error is defined with an error descriptor. This
   209         *  structure groups common information about the errors of this type.
   210         *
   211         *  @field(msg) The error message using a `printf` style format string,
   212         *              but limited to `{@link #NUMARGS}` arguments.
   213         *              This format string together with the two arguments passed
   214         *              to `Error_raise`` are used to create a human readable
   215         *              error message.
   216         *
   217         *  @field(code) A user assignable code, 0 by default. The user may
   218         *              optionally set this field during config to give the
   219         *              error a well-known numeric code.
   220         */
   221        metaonly struct Desc {
   222            String msg;
   223            UInt16 code;
   224        };
   225
   226        /*!
   227         *  ======== Id ========
   228         *  Error identifier
   229         *
   230         *  Each type of error raised is defined with a metaonly
   231         *  `{@link Error#Desc}`.  An `Error_Id` is a 32-bit target value that
   232         *  encodes the information in the `Desc`.  Target programs use
   233         *  `Error_Id` values to "raise" and check for specific errors.
   234         *
   235         *  @a(Warning) `{@link #Id}` values may vary among different
   236         *  configurations of an application.  For example, the addition of a
   237         *  new module to a program may result in a different absolute value for
   238         *  `{@link #E_generic}`.  If you need error numbers that remain
   239         *  invariant, use the user definable `{@link #Desc Desc.code}` field.
   240         */
   241        @Encoded typedef Desc Id;
   242
   243        /*!
   244         *  ======== HookFxn ========
   245         *  Function called whenever an error is raised
   246         *
   247         *  The first parameter and only parameter passed to this function is a
   248         *  pointer to an `Error_Block`.  Even if the client passes a `NULL` error
   249         *  block pointer to `{@link #raise Error_raise}`, this parameter passed
   250         *  to this "hook" function is always `non-NULL`.
   251         */
   252        typedef Void (*HookFxn)(Block *);
   253
   254        /*!
   255         *  ======== NUMARGS ========
   256         *  Maximum number of arguments supported by an error
   257         */
   258        const Int NUMARGS = 2;
   259
   260        /*!
   261         *  ======== Data ========
   262         *  Error args
   263         *
   264         *  The two arguments (arg1, arg2) passed to `{@link #raise}` are
   265         *  stored in one of these arrays within the associated Error_Block.
   266         *  To access these arguments use `{@link #getData}` to obtain a
   267         *  pointer to the Error_Block's Data array.
   268         *
   269         *  @see #getData
   270         */
   271        struct Data {
   272            IArg arg[NUMARGS];
   273        }
   274
   275        /*!
   276         *  ======== Block ========
   277         *  Error block
   278         *
   279         *  An opaque structure used to store information about errors once raised.
   280         *  This structure must be initialized via `{@link #init Error_init()}`
   281         *  before being used for the first time.
   282         */
   283        @Opaque struct Block {
   284            UInt16      unused;     /* for backward compatibility (was code) */
   285            Data        data;       /* arguments passed to raise() */
   286            Id          id;         /* id passed to raise() */
   287            String      msg;        /* msg associated with id */
   288            Types.Site  site;       /* info about Error_raise call site */
   289            IArg        xtra[4];    /* future expansion */
   290        };
   291
   292        /*!
   293         *  ======== E_generic ========
   294         *  Generic error
   295         *
   296         *  This error takes advantage of the $S specifier to allow for recursive
   297         *  formatting of the error message passed to error raise.
   298         *
   299         *  For example, the following is possible:
   300         *  @p(code)
   301         *  Error_raise(eb, Error_E_generic, "Error occurred, code: %d", code);
   302         *  @p
   303         *
   304         *  @see System#extendedFormats
   305         *  @see System#printf
   306         */
   307        config Id E_generic = {msg: "%$S"};
   308
   309        /*!
   310         *  ======== E_memory ========
   311         *  Out of memory error
   312         *
   313         *  The first parameter must be the heap instance handle. The second
   314         *  parameter is the size of the object for which the allocation failed.
   315         */
   316        config Id E_memory = {msg: "out of memory: heap=0x%x, size=%u"};
   317
   318        /*!
   319         *  ======== E_msgCode ========
   320         *  Generic error that displays a string and a numeric value
   321         */
   322        config Id E_msgCode = {msg: "%s 0x%x"};
   323
   324        /*!
   325         *  ======== policy ========
   326         *  System-wide error handling policy
   327         */
   328        config Policy policy = UNWIND;
   329
   330        /*!
   331         *  ======== raiseHook ========
   332         *  The function to call whenever an error is raised
   333         *
   334         *  This function is always called when an error is raised, even if the
   335         *  `Error` policy is `{@link #Policy TERMINATE}`.  In rare cases, it is
   336         *  possible that a raised error does not trigger a call to `raiseHook`;
   337         *  see `{@link #maxDepth}`.
   338         *
   339         *  By default, this function is set to `{@link #print Error_print}`
   340         *  which causes the error to be formatted and output via
   341         *  `{@link xdc.runtime.System#aprintf System_printf}`.
   342         *
   343         *  @see #maxDepth
   344         *  @see #HookFxn
   345         *  @see #print
   346         */
   347        config HookFxn raiseHook = Error.print;
   348
   349        /*!
   350         *  ======== maxDepth ========
   351         *  Maximum number of concurrent calls to `{@link #raiseHook}`
   352         *
   353         *  To prevent errors that occur in the raiseHook function from
   354         *  causing an infinite recursion, the maximum number of concurrent
   355         *  calls to `{@link #raiseHook}` is limited by `Error_maxDepth`.  If
   356         *  the number of concurrent calls exceeds `Error_maxDepth`, the
   357         *  `raiseHook` function is not called.
   358         *
   359         *  In multi-threaded systems, errors raised by separate threads may
   360         *  be detected as recursive calls to `raiseHook`.  So, setting
   361         *  `Error.maxDepth` to a small value may - in rare instances - result in
   362         *  `errorHook` not being called for some raised errors.
   363         *
   364         *  If it is important that all raised errors trigger a call to the
   365         *  `raiseHook` function, set `Error.maxDepth` to an impossibly large
   366         *  number (0xffff) and either ensure that the raise hook never calls a
   367         *  function that can raise an error or add checks in `raiseHook` to
   368         *  protect against "double faults".
   369         */
   370        config UInt16 maxDepth = 16;
   371
   372        /*!
   373         *  ======== check ========
   374         *  Return TRUE if an error was raised
   375         *
   376         *  @param(eb) pointer to an `Error_Block` or `NULL`
   377         *
   378         *  @a(returns)
   379         *  If `eb` is non-`NULL` and `{@link #policy Error.policy} == UNWIND` and
   380         *  an error was raised on `eb`, this function returns `TRUE`.  Otherwise,
   381         *  it returns `FALSE`.
   382         */
   383        Bool check(Block *eb);
   384
   385        /*!
   386         *  ======== getData ========
   387         *  Get an error's argument list
   388         *
   389         *  @param(eb)      non-`NULL` pointer to an `Error_Block`
   390         *
   391         *  @a(returns)
   392         *  `getData` returns an array of type `{@link #Data}` with
   393         *  `{@link #NUMARGS}` elements containing the arguments provided
   394         *  at the time the error was raised.
   395         *
   396         *  @see #raise
   397         */
   398        Data *getData(Block *eb);
   399
   400        /*!
   401         *  ======== getCode ========
   402         *  Get an error's code
   403         *
   404         *  @param(eb) non-`NULL` pointer to an `Error_Block`
   405         *
   406         *  @a(returns)
   407         *  `getCode` returns the error code associated with this error block.
   408         *
   409         *  @see #raise
   410         *  @see #Desc
   411         */
   412        UInt16 getCode(Block *eb);
   413
   414        /*!
   415         *  ======== getId ========
   416         *  Get an error's id
   417         *
   418         *  @param(eb) non-`NULL` pointer to an `Error_Block`
   419         *
   420         *  @a(Warning)
   421         *  `Error_Id` values may vary among different configurations
   422         *  of an application.  For example, the addition of a new module to a
   423         *  program may result in a different absolute value for
   424         *  `{@link #E_generic}`.  If you need error numbers that remain
   425         *  invariant, use the user definable `{@link #Desc Desc.code}` field.
   426         *
   427         *  @see #raise
   428         *  @see #Desc
   429         */
   430        Id getId(Block *eb);
   431
   432        /*!
   433         *  ======== getMsg ========
   434         *  Get an error's "printf" format string
   435         *
   436         *  @param(eb) non-`NULL` pointer to an `Error_Block`
   437         *
   438         *  @see #raise
   439         *  @see #Desc
   440         */
   441        String getMsg(Block *eb);
   442
   443        /*!
   444         *  ======== getSite ========
   445         *  Get an error's call site info
   446         *
   447         *  @param(eb) non-`NULL` pointer to an `Error_Block`
   448         *
   449         *  @a(returns)
   450         *  `getSite` returns a pointer to an initialized
   451         *  `{@link Types#Site Types.Site}` structure.  However, in the
   452         *  event that the call site was compiled with `xdc_FILE` defined to
   453         *  be `NULL` (to minimize string space overhead) the `file`
   454         *  field may be set to `NULL`.
   455         *
   456         *  @see #raise
   457         *  @see #Desc
   458         */
   459        Types.Site *getSite(Block *eb);
   460
   461        /*!
   462         *  ======== idToCode ========
   463         *  Extract the code associated with an `Error_Id`
   464         *
   465         *  @param(id) `Error_Id` from which to extract the user defined
   466         *             code
   467         *  @_nodoc
   468         */
   469        @Macro UInt16 idToCode(Id id);
   470
   471        /*!
   472         *  ======== init ========
   473         *  Put an error block into its initial state
   474         *
   475         *  To ensure reliable error detection, clients must call `init` for
   476         *  an `Error_Block` prior to any use.
   477         *
   478         *  If the same Error Block is used multiple times, only the last error
   479         *  raised is retained.
   480         *
   481         *  @param(eb) pointer to an `Error_Block` or `NULL`
   482         *
   483         *      If `eb` is `NULL` this function simply returns.
   484         */
   485        Void init(Block *eb);
   486
   487        /*!
   488         *  ======== print ========
   489         *  Print error using System.printf()
   490         *
   491         *  This function prints the error using `System_printf()`.  The output
   492         *  is on a single line terminated with a new line character and has the
   493         *  following form:
   494         *  @p(code)
   495         *      <site>: <file>, line <line_num>: <err_msg>
   496         *  @p
   497         *  where `<site>` is the module that raised the error, `<file>` and
   498         *  `<line_num>` are the file and line number of the containing the call
   499         *  site of the `Error_raise()`, and `<err_msg>` is the error message
   500         *  rendered with the arguments associated with the error.
   501         *
   502         *  @param(eb) pointer to an `Error_Block` or `NULL`
   503         *
   504         *      If `eb` is `NULL` this function simply returns with no output.
   505         *
   506         *  @a(Warning)
   507         *  This function is not protected by a gate and, as a result,
   508         *  if two threads call this method concurrently, the output of the two
   509         *  calls will be intermingled.  To prevent intermingled error output,
   510         *  you can either wrap all calls to this method with an appropriate
   511         *  `Gate_enter`/`Gate_leave` pair or simply ensure that only one
   512         *  thread in the system ever calls this method.
   513         */
   514        Void print(Block *eb);
   515
   516        /*!
   517         *  ======== raise ========
   518         *  Raise an error
   519         *
   520         *  This function is used to raise an `Error` by writing call site,
   521         *  error ID, and error argument information into the `Error_Block`
   522         *  pointed to by `eb`.
   523         *
   524         *  If `Error_raise` is called more than once on an `Error_Block` object,
   525         *  the previous error information is overwritten; only the last error
   526         *  is retained in the `Error_Block` object.
   527         *
   528         *  In all cases, any configured `{@link #raiseHook Error.raiseHook}`
   529         *  function is called with a non-`NULL` pointer to a fully
   530         *  initialized `Error_Block` object.
   531         *
   532         *  @param(eb) pointer to an `Error_Block` or `NULL`
   533         *
   534         *      If `eb` is `NULL` or `{@link #policy Error.policy} == TERMINATE`,
   535         *      this function does not return to the caller; after calling any
   536         *      configured `{@link #raiseHook}`, `System_abort` is called with the
   537         *      string `"xdc.runtime.Error.raise: terminating execution\n"`.
   538         *
   539         *  @param(id) the error to raise
   540         *
   541         *      This pointer identifies the class of error being raised;
   542         *      the error class indicates how to interpret any subsequent
   543         *      arguments passed to `{@link #raise}`.
   544         *
   545         *  @param(arg1) error's first argument
   546         *
   547         *      The argument interpreted by the first control character
   548         *      in the error message format string. It is ignored if not needed.
   549         *
   550         *  @param(arg2) error's second argument
   551         *
   552         *      The argument interpreted by the second control character
   553         *      in the error message format string. It is ignored if not needed.
   554         */
   555        @Macro Void raise(Block *eb, Id id, IArg arg1, IArg arg2);
   556
   557        /*! @_nodoc */
   558        Void raiseX(Block *eb, Types.ModuleId mod, String file, Int line, Id id,
   559            IArg arg1, IArg arg2);
   560
   561    internal:
   562
   563        struct Module_State {
   564            UInt16      count;
   565        };
   566
   567    }
   568    /*
   569     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   570     */
   571


module xdc.runtime.Gate

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    package xdc.runtime;
    14
    15    /*!
    16     *  ======== Gate ========
    17     *  Critical section support
    18     *
    19     *  Gates are used by clients to protect concurrent access to critical
    20     *  data structures.  Critical data structures are those that must be
    21     *  updated by at most one thread at a time.  All code that needs access
    22     *  to a critical data structure "enters" a gate (that's associated with the
    23     *  data structure) prior to accessing the data, modifies the data structure,
    24     *  then "leaves" the gate.
    25     *
    26     *  A gate is responsible for ensuring that at most one thread at a time
    27     *  can enter and execute "inside" the gate.  There are several
    28     *  implementations of gates, with different system executation times and
    29     *  latency tradoffs.  In addition, some gates must not be entered by certain
    30     *  thread types; e.g., a gate that is implemented via a "blocking" semaphore
    31     *  must not be called by an interrupt service routine (ISR).
    32     *
    33     *  A module can be declared "gated" by adding the `@Gated` attribute to the
    34     *  module's XDC spec file.  A "gated" module is assigned a module-level gate
    35     *  at the configuration time, and that gate is then used to protect critical
    36     *  sections in the module's target code. A module-level gate is an instance of
    37     *  a module implementing `{@link IGateProvider}` interface. However, gated
    38     *  modules do not access their module-level gates directly. They use this
    39     *  module to access transparently their module-level gate.
    40     *
    41     *  Application code that is not a part of any module also has a
    42     *  module-level gate, configured through the module `{@link Main}`.
    43     *
    44     *  Each gated module can optionally create gates on an adhoc basis at
    45     *  runtime using the same gate module that was used to create the module
    46     *  level gate.
    47     *
    48     *  Gates that work by disabling all preemption while inside a gate can be
    49     *  used to protect data structures accessed by ISRs and other
    50     *  threads.  But, if the time required to update the data structure is not
    51     *  a small constant, this type of gate may violate a system's real-time
    52     *  requirements.
    53     *
    54     *  Gates have two orthogonal attributes: "blocking" and "preemptible".
    55     *  In general, gates that are "blocking" can not be use by code that is
    56     *  called by ISRs and gates that are not "preemptible" should only be used to
    57     *  to protect data manipulated by code that has small constant execution
    58     *  time.
    59     *
    60     */
    61    @CustomHeader
    62    module Gate {
    63
    64        /*!
    65         *  ======== Ref ========
    66         *  Opaque reference to an allocated gate instance
    67         */
    68        @Encoded typedef xdc.runtime.IGateProvider.Handle Ref;
    69
    70        /*!
    71         *  ======== allocInstance ========
    72         *  Allocate a gate instance from the current module's gate
    73         *
    74         *  This method is used by modules to create gates at runtime using
    75         *  the same `IGateProvider` that was used to create the module
    76         *  level gate.  The parameters passed to the `IGateProvider` are
    77         *  specified at configuration time via the
    78         * `{@link Types#Common$ Types.Common$.gateParams}`
    79         *  configuration parameter.
    80         *
    81         *  @param(eb)  `Error` block pointer
    82         *
    83         *      If `NULL`, any error in creating the instance will terminate
    84         *      the application.
    85         *
    86         *  @a(returns)
    87         *  Non-`NULL` instance handle is returned if no error occurs; otherwise
    88         *  an error is raised in `eb` and `NULL` is returned.
    89         *
    90         *  @see IGateProvider
    91         *  @see Error
    92         */
    93        @Macro Ref allocInstance(Error.Block *eb);
    94
    95        /*!
    96         *  ======== freeInstance ========
    97         *  Free a gate instance to the current module's gatekeeper
    98         *
    99         *  @param(gate) non-`NULL` return value from a prior call to
   100         *               `{@link #allocInstance}`.
   101         *
   102         *  @see #allocInstance
   103         */
   104        @Macro Void freeInstance(Ref gate);
   105
   106        /*!
   107         *  ======== enterInstance ========
   108         *  Enter a critical section protected by this gate instance
   109         *
   110         *  @param(gate) non-`NULL` return value from a prior call to
   111         *               `{@link #allocInstance}`.
   112         *
   113         *  @a(returns)
   114         *  Returns a "key" value that must be used to leave `gate`
   115         *  via `{@link #leaveInstance()}`.
   116         *
   117         */
   118        @Macro IArg enterInstance(Ref gate);
   119
   120        /*!
   121         *  ======== enterModule ========
   122         *  Enter a critical section protected by the current module's gate
   123         *
   124         *  @a(returns)
   125         *  Returns a "key" value that must be used to leave the current module
   126         *  gate via `{@link #leaveModule()}`.
   127         *
   128         *  @see #leaveModule
   129         */
   130        @Macro IArg enterModule();
   131
   132        /*!
   133         *  ======== enterSystem ========
   134         *  Enter a critical section protected by the global System gate
   135         *
   136         *  @a(returns)
   137         *  Returns a "key" value that must be used to leave the `{@link System}`
   138         *  gate via `{@link #leaveSystem()}`.
   139         *
   140         *  @see #leaveSystem
   141         */
   142        IArg enterSystem();
   143
   144        /*!
   145         *  ======== leaveInstance ========
   146         *  Leave a critical section protected by a gate
   147         *
   148         *  @param(gate) non-`NULL` return value from a prior call to
   149         *               `{@link #allocInstance}`.
   150         *  @param(key) the return value of a prior call to
   151         *              `{@link #enterInstance}`
   152         *
   153         *  @see #enterInstance
   154         *  @see #allocInstance
   155         */
   156        @Macro Void leaveInstance(Ref gate, IArg key);
   157
   158        /*!
   159         *  ======== leaveModule ========
   160         *  Leave a critical section protected by the current module's gate
   161         *
   162         *  @param(key) the return value of a prior call to `{@link #enterModule}`
   163         *
   164         *  @see #enterModule
   165         */
   166        @Macro Void leaveModule(IArg key);
   167
   168        /*!
   169         *  ======== leaveSystem ========
   170         *  Leave a critical section protected by the global System gate
   171         *
   172         *  @param(key) the return value of a prior call to `{@link #enterSystem}`
   173         *
   174         *  @see #enterSystem
   175         */
   176        Void leaveSystem(IArg key);
   177
   178        /*!
   179         *  ======== canBlock ========
   180         *  Check if the module level gate can block threads
   181         *
   182         *  This type of gate should never be called by clients that must never
   183         *  call a "blocking" RTOS operation; e.g., interrupt service
   184         *  routines
   185         *
   186         *  @a(returns) Returns `TRUE` if the underlying gatekeeper's gate can
   187         *              block
   188         */
   189        @Macro Bool canBlock();
   190
   191        /*!
   192         *  ======== canBePreempted ========
   193         *  Check if the module level gate allows thread preemption
   194         *
   195         *  This type of gate should always be used by clients that protect
   196         *  a data structure whose updates require more than a small
   197         *  constant amount of time; e.g., update of a memory allocator's free
   198         *  list.
   199         *
   200         *  @a(returns) Returns `TRUE` if the underlying gate does not disable
   201         *              thread preemption.
   202         */
   203        @Macro Bool canBePreempted();
   204
   205        /*!
   206         *  ======== staticAlloc ========
   207         *  Assign a statically-allocated gate instance to a state-object field
   208         *
   209         *  This method is used to create a gate for static instance objects
   210         *  that require a gate.
   211         *
   212         *  @param(stateObj)    the state object for the instance being created
   213         *  @param(fldName)     a name of a field within the state object
   214         *
   215         *      This parameter names a field that will point to the created gate
   216         *      instance to be created. It is a caller's responsibility
   217         *      to ensure that the type of `fldName` is a handle to an
   218         *      `IGateProvider` instance.
   219         */
   220        metaonly Void staticAlloc(Any stateObj, String fldName);
   221    }
   222    /*
   223     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   224     */
   225


module xdc.runtime.GateNull

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    package xdc.runtime;
    14
    15    /*!
    16     *  ======== GateNull ========
    17     *  Empty implementation of `{@link IGateProvider}`
    18     *
    19     *  An instance of this `IGateProvider` implementation is assigned to all
    20     *  gated modules as a default module-wide gate. Instances of this gate
    21     *  implementation provide no protection for critical sections and should only
    22     *  be used for modules in which the data structures protected by module-level
    23     *  gates are never accessed by concurrent threads.
    24     */
    25    module GateNull inherits IGateProvider {
    26
    27    instance:
    28        /*!
    29         *  ======== create ========
    30         *  Create a `GateNull` gate
    31         */
    32        create();
    33    }
    34    /*
    35     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:31; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    36     */
    37


module xdc.runtime.HeapMin

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== HeapMin.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== HeapMin ========
    19     *  Growth-only based heap implementation.
    20     *
    21     *  `HeapMin` is a minimal footprint heap implementation. This module is
    22     *  is designed for applications that only create module instances and
    23     *  generally only allocate memory at runtime, but never delete created
    24     *  instances or free memory explicitly.
    25     *
    26     *  For configuration-time `HeapMin.create`, the heap is aligned to
    27     *  `{@link Memory#getMaxDefaultTypeAlignMeta()}` for those targets that support
    28     *  static alignment. For targets that do not support static alignment, the
    29     *  buffer alignment is undefined.
    30     *
    31     *  When calling `{@link #create()}` at runtime, the client
    32     *  is responsible for aligning the buffer.
    33     */
    34
    35    module HeapMin inherits xdc.runtime.IHeap {
    36
    37        /*! @_nodoc */
    38        @XmlDtd
    39        metaonly struct Instance_View {
    40            Ptr             address;
    41            String          label;
    42            Ptr             buffer;
    43            Memory.Size     remainSize;
    44            Memory.Size     startSize;
    45        }
    46
    47        /*!
    48         *  ======== A_zeroSize ========
    49         *  Assert that the `{@link #size}` is non-zero on the create
    50         */
    51        config Assert.Id A_zeroSize  =
    52            {msg: "HeapMin_create cannot have a zero size value"};
    53
    54        /*!
    55         *  ======== E_freeError ========
    56         *  Error raised if `{@link #free()}` is called.
    57         *
    58         *  This error is only raised if a `{@link #free()}`
    59         *  is called and `{@link #freeError}` is true.
    60         */
    61        config Error.Id E_freeError = {
    62            msg: "free() invalid in growth-only HeapMin"
    63        };
    64
    65        /*!
    66         *  ======== freeError ========
    67         *  Flag to control whether `{@link #E_freeError}` is enabled.
    68         *
    69         *  If true, a `{@link #E_freeError}` error occurs when trying
    70         *  to free a buffer.
    71         *
    72         *  If false, no error occurs and the `{@link #free()}` does nothing.
    73         */
    74        config Bool freeError = true;
    75
    76    instance:
    77
    78        /*!
    79         *  ======== align ========
    80         *  Alignment of the buffer being managed by this heap instance.
    81         *
    82         *  In the static HeapMin.create() call, the buffer allocated for the
    83         *  HeapMin instance will have the alignment specified by this parameter
    84         *  on targets that support static alignment.
    85         *
    86         *  In the dynamic case, the client must supply the buffer, so it is the
    87         *  client's responsibility to manage the buffer's alignment, and there is
    88         *  no 'align' parameter.
    89         *
    90         *  The specified `align` parameter must be a power of 2.
    91         *
    92         *  The default alignment of zero causes the buffer to get aligned using
    93         *  {@link Memory#getMaxDefaultTypeAlignMeta()}.
    94         */
    95        metaonly config SizeT align;
    96
    97        /*!
    98         *  ======== create ========
    99         *  Create a `HeapMin` heap
   100         *
   101         *  This heap is a growth-only heap that is intended to be used by
   102         *  systems that never delete objects or free memory.  Objects can be
   103         *  created at runtime based on values determined at runtime, but
   104         *  objects can not be deleted.
   105         *
   106         *  @see HeapMin#Params
   107         */
   108        create();
   109
   110        /*!
   111         *  ======== sectionName ========
   112         *  Section name of the heap
   113         *
   114         *  When creating heaps during configuration, this parameter specifies
   115         *  where the heap's buffer will be placed. This parameter is passed as
   116         *  the section name in the `{@link Memory#staticPlace}` function.
   117         *
   118         *  @see Memory#staticPlace
   119         */
   120        metaonly config String sectionName = null;
   121
   122        /*!
   123         *  ======== buf ========
   124         *  Buffer that will be managed by the heap instance.
   125         *
   126         *  When creating a heap at runtime, the user must supply the memory
   127         *  that the heap will manage.  It is up to the caller to align
   128         *  the buffer as needed.
   129         *
   130         *  This parameter is ignored when creating heaps during configuration.
   131         */
   132        config Ptr buf = 0;
   133
   134        /*!
   135         *  ======== size ========
   136         *  Size (in MADUs) of the heap.
   137         *
   138         *  This parameter specifies the size of the heap managed by a
   139         *  `HeapMin` instance.  In the static case, a buffer of length `size`
   140         *  will be created.  In the dynamic case, `size` specifies the size of
   141         *  the buffer (i.e. parameter `buf`) that the caller provides.
   142         *
   143         *  This is a required parameter. It must be set by the caller. Failure
   144         *  to do so, will result in a build error for the static create or an
   145         *  `{@link #A_zeroSize}` assert for the runtime create.
   146         */
   147        config Memory.Size size = 0;
   148
   149        /*!
   150         *  ======== alloc ========
   151         *  Allocate a block of memory from the heap.
   152         *
   153         *  @a(Constraints)
   154         *  The alignment must be a power of 2.
   155         *
   156         *  @see IHeap#alloc
   157         */
   158        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
   159
   160        /*!
   161         *  ======== free ========
   162         *  Free a block of memory back to the heap.
   163         *
   164         *  This is a growth only heap. Calling the `HeapMin_free` function
   165         *  will result in a `{@link #E_freeError}` error unless
   166         *  `{@link #freeError}` is set to `false`.
   167         *
   168         *  @see IHeap#free
   169         */
   170        override Void free(Ptr block, SizeT size);
   171
   172        /*!
   173         *  ======== isBlocking ========
   174         *  Can this heap block the caller
   175         *
   176         *  @a(returns)
   177         *  `HeapMin` always returns `FALSE` since it never blocks on a
   178         *  resource.
   179         */
   180        override Bool isBlocking();
   181
   182    internal:
   183
   184        struct Instance_State {
   185            Char        buf[];             /* Address of buffer being managed  */
   186            Memory.Size remainSize;        /* Size of remaining heap           */
   187            Memory.Size startSize;         /* Size of heap at the start        */
   188        };
   189    }
   190    /*
   191     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   192     */
   193


module xdc.runtime.HeapStd

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== HeapStd.xdc ========
    15     *!  Open Issues:
    16     *!  - Do not really know the largestFreeSize value in HeapStd_getStats()
    17     */
    18
    19    /*!
    20     *  ======== HeapStd ========
    21     *  Malloc/free based heap implementation.
    22     *
    23     *  This heap is based on the ANSI C Standard Library functions
    24     *  `malloc()` and `free()` and assumes that these functions are thread-safe.
    25     *  Please refer to the target specific documentation of the ANSI C Standard
    26     *  Library for details.
    27     *
    28     *  The largest free block that can be returned form `malloc()` cannot be
    29     *  determined. Therefore, the property `largestFreeSize` in
    30     *  `{@link Memory#Stats}` returned from `{@link #getStats()}` always returns
    31     *  0.
    32     *
    33     *  @a(Constraints)
    34     *  The `{@link #alloc()}` function only supports alignment requests up to
    35     *  value returned from
    36     *  `{@link Memory#getMaxDefaultTypeAlign()}`.
    37     */
    38
    39    @InstanceInitError  /* instance init can fail, call finalize if so */
    40
    41    module HeapStd inherits xdc.runtime.IHeap {
    42
    43        /*! @_nodoc */
    44        @XmlDtd
    45        metaonly struct Instance_View {
    46            Ptr             address;
    47            String          label;
    48            Memory.Size     remainSize;
    49            Memory.Size     startSize;
    50        }
    51
    52        /*!
    53         *  ======== E_noRTSMemory ========
    54         *  Error raised if all the RTS heap is used up
    55         *
    56         *  The total size of all `HeapStd` instance allocations added together
    57         *  cannot exceed the `malloc`/`free` heap size determined by
    58         *  `{@link xdc.cfg.Program#heap}`.
    59         */
    60        config Error.Id E_noRTSMemory = {
    61            msg: "The RTS heap is used up. Examine Program.heap."
    62        };
    63
    64        /*!
    65         *  ======== A_zeroSize ========
    66         *  Assert that the `{@link #size}` is non-zero on the create
    67         */
    68        config Assert.Id A_zeroSize = {
    69            msg: "HeapStd_create cannot have a zero size value"
    70        };
    71
    72        /*!
    73         *  ======== A_invalidTotalFreeSize ========
    74         *  Assert that remaining size is less than or equal to starting size.
    75         *
    76         *  If this assertion is raised, it means that either incorrect sizes
    77         *  were passed to `{@link #free}` or multiple calls to `{@link #free}`
    78         *  were made with the same buffer.
    79         */
    80        config Assert.Id A_invalidTotalFreeSize = {
    81            msg: "HeapStd instance totalFreeSize is greater than starting size"
    82        };
    83
    84        /*!
    85         *  ======== A_invalidAlignment ========
    86         *  Assert that the alignment argument in alloc is valid
    87         *
    88         *  If this assertion is raised, it means that the requested alignment is
    89         *  greater than the maximum alignment allowed on the target.
    90         */
    91        config Assert.Id A_invalidAlignment = {
    92            msg: "HeapStd_alloc - requested alignment is greater than allowed"
    93        };
    94
    95    instance:
    96
    97        /*!
    98         *  ======== create ========
    99         *  Create a `HeapStd` heap
   100         *
   101         *  This heap uses the ANSI C Standard Library functions
   102         *  `malloc()` and `free()` to manage memory and assumes that these
   103         *  functions are thread-safe.
   104         *
   105         *  @see HeapStd#Params
   106         */
   107        create();
   108
   109        /*!
   110         *  ======== size ========
   111         *  Size (in MAUs) of the heap.
   112         *
   113         *  This parameter specifies the size of the heap managed by a
   114         *  `HeapStd` instance. `HeapStd` is built upon the ANSI C Standard
   115         *  Library functions `malloc()` and `free()`.
   116         *
   117         *  The total size of all `HeapStd` instance allocations added together
   118         *  cannot exceed the `malloc`/`free` heap size determined by
   119         *  `{@link xdc.cfg.Program#heap Program.heap}`.
   120         *
   121         *  This is a required parameter. It must be set by the caller. Failure
   122         *  to do so, will result in a build error for the static create or an
   123         *  assert for the runtime create.
   124         */
   125        config Memory.Size size = 0;
   126
   127        /*!
   128         *  ======== alloc ========
   129         *  Allocates a block of memory from the heap.
   130         *
   131         *  @a(Constraints)
   132         *  The only alignment currently supported is the default
   133         *  alignment returned by the underlying `malloc()` implementation.
   134         *  The align value must be less than or equal to the value returned from
   135         *  `{@link Memory#getMaxDefaultTypeAlign()}`.
   136         *
   137         *  @see IHeap#alloc
   138         */
   139        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
   140
   141        /*!
   142         *  ======== isBlocking ========
   143         *  Returns whether the heap may block during an `HeapStd_alloc()` or
   144         *  `HeapStd_free()`.
   145         *
   146         *  @a(returns)
   147         *  Since the implementation of the underlaying ANSI C Standard Library
   148         *  is not known, this function always returns the more restrictive case
   149         *  which is `TRUE`.
   150         */
   151        override Bool isBlocking();
   152
   153    internal:
   154
   155        struct Module_State {
   156            Memory.Size remainRTSSize;      /* Remaining size of rts heap      */
   157        };
   158
   159        struct Instance_State {
   160            Memory.Size remainSize;         /* Size of the remaining heap.      */
   161            Memory.Size startSize;          /* Starting size of the heap.       */
   162        };
   163    }
   164    /*
   165     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   166     */
   167


interface xdc.runtime.IFilterLogger

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*!
    14     *  ======== IFilterLogger ========
    15     *  Interface for supporting filtering of Log events by detail level.
    16     *
    17     *  Filtering of events based on detail level is not inherently supported
    18     *  by the Log APIs as is filtering of events based on the diagnostics mask.
    19     *
    20     *  Support for this type of filtering must be done by an `ILogger`
    21     *  implementation. Not all users are interested in this filtering support,
    22     *  however, so it is not required of all `ILogger` implementations.
    23     *
    24     *  `ILoggers` that do intend to support filtering by detail level should
    25     *  implement this interface, which extends the `ILogger` interface.
    26     *
    27     *  The `{@link #setFilterLevel}` and `{@link #getFilterLevel}` functions
    28     *  support runtime specification of a different filtering level for each of
    29     *  the diagnostics categories.
    30     */
    31    interface IFilterLogger inherits ILogger {
    32
    33        /*!
    34         *  ======== filterByLevel ========
    35         *  Support filtering of events by event level
    36         *
    37         *  To improve logging performance, this feature can be disabled by setting
    38         *  `filterByLevel` to false.
    39         *
    40         *  See '{@link #setFilterLevel}' for an explanation of level filtering.
    41         */
    42        config Bool filterByLevel = false;
    43
    44    instance:
    45
    46        /*!
    47         *  ======== setFilterLevel ========
    48         *  Set the level of detail that instances will log
    49         *
    50         *  Events with the specified level or higher will be logged, events
    51         *  below the specified level will be dropped.
    52         *
    53         *  Events are filtered first by diags category, then by level. If an
    54         *  event's diags category is disabled in the module's diags mask, then it
    55         *  will be filtered out regardless of level. The event will not even be
    56         *  passed to the logger.
    57         *
    58         *  This API allows for setting the filtering level for more than one
    59         *  diags category at a time. The mask parameter can be a single category
    60         *  or multiple categories combined, and the level will be set for all of
    61         *  those categories.
    62         *
    63         *  @param(mask) The diags categories to set the level for
    64         *  @param(filterLevel) The new filtering level for the specified
    65         *                      categories
    66         */
    67        Void setFilterLevel(Diags.Mask mask, Diags.EventLevel filterLevel);
    68
    69        /*!
    70         *  ======== getFilterLevel ========
    71         *  Returns the mask of diags categories currently set to the specified
    72         *  level.
    73         *
    74         *  See '{@link #setFilterLevel}' for an explanation of level filtering.
    75         */
    76        Diags.Mask getFilterLevel(Diags.EventLevel level);
    77
    78    }
    79    /*
    80     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    81     */
    82


interface xdc.runtime.IGateProvider

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IGateProvider.xdc ========
    15     */
    16    package xdc.runtime
    17
    18    /*!
    19     *  ======== IGateProvider ========
    20     *  Interface implemented by all gate providers
    21     *
    22     *  Gates are used within the `xdc.runtime` package to serialize access
    23     *  to data structures that are used by more than one thread.
    24     *
    25     *  Gates are responsible for ensuring that only one out of multiple threads
    26     *  can access a data structure at a time.  There
    27     *  are important scheduling latency and performance considerations that
    28     *  affect the "type" of gate used to protect each data structure.  For
    29     *  example, the best way to protect a shared counter is to simply disable
    30     *  all interrupts before the update and restore the interrupt state after
    31     *  the update; disabling all interrupts prevents all thread switching, so
    32     *  the update is guaranteed to be "atomic".  Although highly efficient, this
    33     *  method of creating atomic sections causes serious system latencies when
    34     *  the time required to update the data structure can't be bounded.
    35     *
    36     *  For example, a memory manager's list of free blocks can grow indefinitely
    37     *  long during periods of high fragmentation.  Searching such a list with
    38     *  interrupts disabled would cause system latencies to also become unbounded.
    39     *  In this case, the best solution is to provide a gate that suspends the
    40     *  execution of  threads that try to enter a gate that has already been
    41     *  entered; i.e., the gate "blocks" the thread until the thread
    42     *  already in the gate leaves.  The time required to enter and leave the
    43     *  gate is greater than simply enabling and restoring interrupts, but since
    44     *  the time spent within the gate is relatively large, the overhead caused by
    45     *  entering and leaving gates will not become a significant percentage of
    46     *  overall system time.  More importantly, threads that do not need to
    47     *  access the shared data structure are completely unaffected by threads
    48     *  that do access it.
    49     *
    50     *  @a(Notes)
    51     *  Modules inheriting this interface should treat all names beginning with
    52     *  `Q_` as reserved words, i.e. the names from that namespace should not
    53     *  be used.  This will allow future version of this interface to define new
    54     *  constants ("qualities" ) similar to `{@link #Q_BLOCKING}` and
    55     *  `{@link #Q_PREEMPTING}` without breaking any existing modules.
    56     */
    57    interface IGateProvider {
    58
    59        /*!
    60         *  ======== Q_BLOCKING ========
    61         *  Blocking quality
    62         *
    63         *  Gates with this "quality" may cause the calling thread to block;
    64         *  i.e., suspend execution until another thread leaves the gate.
    65         */
    66        const Int Q_BLOCKING = 1;
    67
    68        /*!
    69         *  ======== Q_PREEMPTING ========
    70         *  Preempting quality
    71         *
    72         *  Gates with this "quality" allow other threads to preempt the thread
    73         *  that has already entered the gate.
    74         */
    75        const Int Q_PREEMPTING = 2;
    76
    77        /*!
    78         *  ======== query ========
    79         *  Configuration time test for a particular gate quality
    80         *
    81         *  @param(qual)    constant describing a quality
    82         *  @a(returns)     Returns `TRUE` if the gate has the given quality,
    83         *  and `FALSE` otherwise, which includes the case when the gate does not
    84         *  recognize the constant describing the quality.
    85         */
    86        metaonly Bool queryMeta(Int qual);
    87
    88        /*!
    89         *  ======== query ========
    90         *  Runtime test for a particular gate quality
    91         *
    92         *  @param(qual)    constant describing a quality
    93         *  @a(returns)     Returns `TRUE` if the gate has the given quality,
    94         *  and `FALSE` otherwise, which includes the case when the gate does not
    95         *  recognize the constant describing the quality.
    96         */
    97        Bool query(Int qual);
    98
    99    instance:
   100
   101        /*!
   102         *  ======== create ========
   103         *  Create a gate instance
   104         */
   105        create();
   106
   107        /*!
   108         *  ======== enter ========
   109         *  Enter this gate
   110         *
   111         *  Each gate provider can implement mutual exclusion using different
   112         *  algorithms; e.g., disabling all scheduling, disabling the scheduling
   113         *  of all threads below a specified "priority level", suspending the
   114         *  caller when the gate has been entered by another thread and
   115         *  re-enabling it when the the other thread leaves the gate.  However,
   116         *  in all cases, after this method returns that caller has exclusive
   117         *  access to the data protected by this gate.
   118         *
   119         *  A thread may reenter a gate without blocking or failing.
   120         *
   121         *  @a(returns)
   122         *  Returns a "key" that is used to `{@link #leave}` this gate; this
   123         *  value is used to restore thread preemption to the state that
   124         *  existed just prior to entering this gate.
   125         */
   126        IArg enter();
   127
   128        /*!
   129         *  ======== leave ========
   130         *  Leave this gate
   131         *
   132         *  This method is only called by threads that have previously entered
   133         *  this gate via `{@link #enter}`.  After this method returns, the
   134         *  caller must not access the data structure protected by this gate
   135         *  (unless the caller has entered the gate more than once and other
   136         *  calls to `leave` remain to balance the number of previous
   137         *  calls to `enter`).
   138         *
   139         *  @param(key) the value returned by a matching call to
   140         *              `{@link #enter}`
   141         */
   142        Void leave(IArg key);
   143    }
   144    /*
   145     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   146     */
   147


interface xdc.runtime.IHeap

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IHeap.xdc ========
    15     *! - if we ever change the name of this interface, we should change it to
    16     *!   IMemoryProvider
    17     */
    18
    19    /*!
    20     *  ======== IHeap ========
    21     *  Interface to heap functions.
    22     *
    23     *  All heap implementations inherit from this interface.
    24     *  The implementations can have additional configuration
    25     *  parmeters and functions.
    26     *
    27     */
    28    interface IHeap {
    29
    30    instance:
    31
    32        /*!
    33         *  ======== alloc ========
    34         *  Allocates a block of memory from the heap.
    35         *
    36         *  This method returns a block of memory from the heap.
    37         *  It is called by the `{@link xdc.runtime.Memory#alloc()}` function.
    38         *
    39         *  @param(size)     size (in MADUs) of the block
    40         *  @param(align)    alignment (in MADUs)  of the block
    41         *  @param(eb)       pointer to error block
    42         *
    43         *  @a(returns)      Returns the address of the allocated memory.
    44         */
    45        Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
    46
    47        /*!
    48         *  ======== create ========
    49         *  Create a heap.
    50         *
    51         *  See specific `IHeap` implementation for parameters used.
    52         */
    53        create();
    54
    55        /*!
    56         *  ======== free ========
    57         *  Free a block of memory back to the heap.
    58         *
    59         *  This method gives back a block of memory to a heap.
    60         *  It is called by the `{@link xdc.runtime.Memory#free()}` function.
    61         *
    62         *  @param(block)    non-`NULL` address of allocated block to free
    63         *  @param(size)     size (in MADUs) of the block of memory to free
    64         */
    65        Void free(Ptr block, SizeT size);
    66
    67        /*!
    68         *  ======== isBlocking ========
    69         *  Returns whether the heap may block during an `{@link #alloc()}` or
    70         *  `{@link #free()}`.
    71         *
    72         *  @a(returns)      If the heap might block, `TRUE` is returned.
    73         *                   If the heap does not block, `FALSE` is returned.
    74         */
    75        Bool isBlocking();
    76
    77        /*!
    78         *  ======== getStats ========
    79         *  Retrieve the statistics from the heap.
    80         *
    81         *  The caller passes in a pointer to a `{@link xdc.runtime.Memory#Stats}`
    82         *  structure and `getStats` fills in this structure.
    83         *
    84         *  This function is called by the `{@link xdc.runtime.Memory#getStats()}`
    85         *  function.
    86         *
    87         *  @param(stats)    non-`NULL` pointer to an output buffer
    88         */
    89        Void getStats(Memory.Stats *stats);
    90    }
    91    /*
    92     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    93     */
    94


interface xdc.runtime.IInstance

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*!
    14     *  ======== IInstance ========
    15     *  Common instance params
    16     *
    17     *  Every module's instance parameter structure contains a pointer to an
    18     *  `IInstance.Params` structure named `instance`.  So, every instance
    19     *  parameter defined in this interface may optionally be set when
    20     *  creating (or constructing) any module's instances.
    21     */
    22    interface IInstance {
    23
    24    instance:
    25
    26        /*!
    27         *  ======== name ========
    28         *  Name of the instance
    29         *
    30         *  It is possible to "bind" a name to each instance of any module
    31         *  at the time the instance is created (or constructed).
    32         *  @p(code)
    33         *      ModA_Params params;
    34         *      ModA_Params_init(&params);
    35         *      params.instance->name = "myInstance";
    36         *      ModA_create(&params, NULL);
    37         *  @p
    38         *
    39         *  The name field must be assigned a pointer to a buffer that persists
    40         *  as long as the instance that it names exists.  Only a reference to
    41         *  the name is retained in the instance, the name is not copied to a
    42         *  secondary buffer.
    43         *
    44         *  The configuration parameters that controls if instance names are
    45         *  supported is `common$.namedInstance`. The parameter is a member of the
    46         *  structure `{@link xdc.runtime.Types#Common$ common$}`, available in each
    47         *  module. By default, this parameter is set to `false`, which disables
    48         *  support for instance names.
    49         *  Therefore, to enable instance names for a given module `Mod`, configure
    50         *  the module as follows in your configuration script:
    51         *  @p(code)
    52         *      var Mod = xdc.useModule('pkg.Mod');
    53         *      ModA.common$.namedInstance = true;
    54         *  @p
    55         *
    56         *  Here is how the static instances are given names at the configuration
    57         *  time:
    58         *  @p(code)
    59         *      var inst = Mod.create();
    60         *      inst.instance.name = "myInstance";
    61         *  @p
    62         *
    63         *  At runtime, assign your instance a name:
    64         *  @p(code)
    65         *      #include <package/name/Mod.h>
    66         *      Mod_Params params;
    67         *      Mod_Params_init(&params);
    68         *      params.instance->name = "myInstance";
    69         *      Mod_create(&params, NULL);
    70         *  @p
    71         *
    72         *  If instances have been configured to not support names, it is still
    73         *  possible to assign to the `instance.name` field of the parameter
    74         *  structure (as shown above).  However, the pointer is not retained
    75         *  and methods that normally return an instance's name will return
    76         *  `NULL` instead.
    77         */
    78        config String name = null;
    79    }
    80    /*
    81     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    82     */
    83


interface xdc.runtime.ILogger

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*!
    14     *  ======== ILogger ========
    15     *  Interface to service Log events
    16     *
    17     *  A logger is responsible for recording, transmitting, or otherwise
    18     *  handling `{@link Log#EventDesc Log Events}` generated by clients of the
    19     *  `{@link Log}` module. The `Log` module uses modules that implement the
    20     *  `ILogger` interface to record the log events. Most application code will
    21     *  use the `Log` module instead of directly calling the specific `ILogger`
    22     *  module implementation.
    23     *
    24     *  All logger implementations must inherit from this interface. The
    25     *  derived implementations must implement the functions defined in this
    26     *  interface but may also add additional configuration parameters and
    27     *  functions.
    28     *
    29     *  Events may be defined with a detail level, but the Log interface does not
    30     *  inherently provide support for filtering of events based on detail level.
    31     *  Instead, this is left to the ILogger implementation. ILogger
    32     *  implementations which wish to support filtering based on detail level
    33     *  should implement the IFilterLogger interface, which extends the ILogger
    34     *  interface to include APIs for getting and setting the current filter level.
    35     */
    36    interface ILogger {
    37
    38        /*!
    39         *  ======== getMetaArgs ========
    40         *  Returns any meta data needed to support RTA.
    41         *
    42         *  This meta data should be returned in the form of a structure which
    43         *  can be converted into XML. This data is added to the RTA XML file
    44         *  during the application's configuration, and can be accessed later
    45         *  through the xdc.rta.MetaData module.
    46         *
    47         *  The MetaData is returned per instance of the ILogger module. The
    48         *  instance object is passed to the function as the first argument.
    49         *
    50         *  The second argument is the index of the instance in the list of
    51         *  the ILogger's static instances.
    52         */
    53        function getMetaArgs(inst, instNum);
    54
    55    instance:
    56
    57        /*!
    58         *  ======== enable ========
    59         *  Enable a log
    60         *
    61         *  @a(returns)
    62         *  The function returns the state of the log (`TRUE` if enabled,
    63         *  `FALSE` if disabled) before the call. This return value allows
    64         *  clients to restore the previous state.
    65         *  Note: not thread safe.
    66         */
    67        Bool enable();
    68
    69       /*!
    70         *  ======== disable ========
    71         *  Disable a log
    72         *
    73         *  Events written to a disabled log are silently discarded.
    74         *
    75         *  @a(returns)
    76         *  The function returns the state of the log (`TRUE` if enabled,
    77         *  `FALSE` if disabled) before the call. This return value allows
    78         *  clients to restore the previous state.
    79         *  Note: not thread safe.
    80         */
    81        Bool disable();
    82
    83        /*!
    84         *  ======== write0 ========
    85         *  Process a log event with 0 arguments.
    86         *
    87         *  Same as `write4` except with 0 arguments rather than 4.
    88         *
    89         *  @see ILogger#write4()
    90         */
    91        Void write0(Log.Event evt, Types.ModuleId mid);
    92
    93        /*!
    94         *  ======== write1 ========
    95         *  Process a log event with 1 arguments.
    96         *
    97         *  Same as `write4` except with 1 arguments rather than 4.
    98         *
    99         *  @see ILogger#write4()
   100         */
   101        Void write1(Log.Event evt, Types.ModuleId mid, IArg a1);
   102
   103        /*!
   104         *  ======== write2 ========
   105         *  Process a log event with 2 arguments.
   106         *
   107         *  Same as `write4` except with 2 arguments rather than 4.
   108         *
   109         *  @see ILogger#write4()
   110         */
   111        Void write2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
   112
   113        /*!
   114         *  ======== write4 ========
   115         *  Process a log event with up to 4 arguments.
   116         *
   117         *  The `evt` argument is of type Log.Event, which encodes the
   118         *  `{@link Log#EventId}`, the `{@link Diags#Mask}`, and the
   119         *  `{@link Diags#EventLevel}` of the event. The event ID can be obtained
   120         *  via `{@link Types#getEventId}(evt)`, the Diags mask can be obtained via
   121         *  `{@link Diags#getMask}(evt)`, and the event level can be obtained via
   122         *  `{@link Diags#getLevel}(evt)`.
   123         *
   124         *  The `modId` argument is the module ID of the module that logged the
   125         *  event.
   126         *
   127         *  The event information can be used by the logger to handle different
   128         *  events specially. For example, the event ID can be used to compare
   129         *  against other known `Log.Event`s.
   130         *  @p(code)
   131         *      if (Log_getEventId(MY_EVENT) == Log_getEventId(evt)) {
   132         *          :
   133         *      }
   134         *  @p
   135         *  The Diags mask and event level can be used for filtering of events
   136         *  based on event level (see {@link IFilterLogger}), or even routing
   137         *  events to separate loggers based on diags category (see, for example,
   138         *  {@link LoggerBuf#statusLogger}).
   139         *
   140         *  The Diags mask and event level are useful for handling the event, but
   141         *  are generally not recorded by the logger because they are not needed in
   142         *  decoding and displaying the event. A more suitable value to record is a
   143         *  `{@link Types#Event}`, which encodes the event ID and module ID. For
   144         *  example, the `{@link Log#EventRec}` type stores a `{@link Types#Event}`
   145         *  in its record definition. A `{@link Types#Event}` can be created using
   146         *  the `{@link Types#makeEvent}` API given the event ID and module ID.
   147         *
   148         *  The event ID value of `0` is used to indicate an event triggered by a
   149         *  call to one of the `{@link Log#print0 Log_print[0-6]}` methods. These
   150         *  methods take a format string rather than a `Log_Event` argument and,
   151         *  as a result, the event ID encoded in `evt` is `0` and the parameter
   152         *  `a1` is the format string.
   153         *
   154         *  Non-zero event IDs can also be used to access the `msg` string
   155         *  associated with the `{@link Log#EventDesc}` that originally
   156         *  defined the `Log` event.
   157         *  @p(code)
   158         *      Log_EventId id = Log_getEventId(evt));
   159         *      if (id != 0) {
   160         *          String msg = Text_ropeText(id);
   161         *          System_aprintf(msg, a1, a2, a3, a4);
   162         *      }
   163         *  @p
   164         *  This works because an event's ID is simply an offset into a table
   165         *  of characters (maintained by the `{@link Text}` module)
   166         *  containing the event's msg string.
   167         *
   168         *  The arguments a1, a2, etc. are parameters that are to be interpreted
   169         *  according to the message format string associated with `evt`.
   170         *
   171         *  @param(evt) event to be logged
   172         *  @param(mid) module ID of the module which logged the event
   173         *  @param(a1)  arbitrary argument passed by caller
   174         *
   175         *  @see Log#Event
   176         *  @see Log#EventDesc
   177         *  @see Text#ropeText
   178         *  @see Log#getEventId
   179         */
   180        Void write4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
   181                    IArg a3, IArg a4);
   182
   183        /*!
   184         *  ======== write8 ========
   185         *  Process a log event with up to 8 arguments.
   186         *
   187         *  Same as `write4` except with 8 arguments rather than 4.
   188         *
   189         *  @see ILogger#write4()
   190         */
   191        Void write8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
   192                    IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
   193    }
   194    /*
   195     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   196     */
   197


interface xdc.runtime.IModule

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IModule.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== IModule ========
    19     *  Base interface for all modules
    20     *
    21     *  All modules share a common set of configuration parameters and methods.
    22     *
    23     *  @a(internal)
    24     *  This section provides a terse summary of the methods provided by every
    25     *  module for use within the module's implementation.  Each method's
    26     *  prototype is shown along with a brief summary of its behavior.
    27     *  These methods are declared in the module's internal header which should
    28     *  always be included in any file referencing these functions.  For a
    29     *  module named `Mod` the following statement includes this header.
    30     *  @p(code)
    31     *      #include "package/internal/Mod.xdc.h"
    32     *  @p
    33     *
    34     *  In the protypes below, `Mod` refers to the module being implemented,
    35     *  `embeddedObj` is the name of field in the module's state structure that
    36     *  is either an embedded object field or an array of such objects, and
    37     *  `fld` is the name of a field declared in the module's state structure.
    38     *
    39     *  @p(code)
    40     *  // enter the module's gate
    41     *  IArg Mod_Module_enter(Gate_Handle gate);
    42     *
    43     *  // leave the module's gate
    44     *  Mod_Module_leave(Gate_Handle, IArg);
    45     *
    46     *  // return a pointer to the embeddedObj field
    47     *  Ptr Mod_Module_State_embeddedObj();
    48     *
    49     *  // the value of the fld field of the module's state structure
    50     *  Mod_module->fld;    // fld is declared in module's .xdc file
    51     *  @p
    52     *
    53     *  @a(external)
    54     *  This section provides a terse summary of the methods provided by every
    55     *  module for use by an application or other modules.  Each method's
    56     *  prototype is shown along with a brief summary of its behavior.
    57     *  These methods are declared in the module's header which should always
    58     *  be included in any file referencing these functions.  For a
    59     *  module named `Mod` in the package named `a.b.c`, the following statement
    60     *  includes this header.
    61     *  @p(code)
    62     *      #include <a/b/c/Mod.h>
    63     *  @p
    64     *
    65     *  In the protypes below, `IMod` referes to some interface, `Mod` refers to
    66     *  a module that (optionally) inherits from `IMod`, and `pkgName` is the
    67     *  name of the package containing the interface `IMod`.
    68     *  @p(code)
    69     *
    70     *  // methods to operate on modules
    71     *
    72     *      // return heap associated with this module
    73     *      IHeap_Handle Mod_Module_heap();
    74     *
    75     *      // get Mod's module ID
    76     *      Types_ModuleId Mod_Module_id();
    77     *
    78     *      // return TRUE if Mod's startup is complete
    79     *      Bool Mod_Module_startupDone();
    80     *
    81     *      // type-safe conversion from an interface to an inheriting module
    82     *      // Returns NULL if the conversion is not valid
    83     *      Mod_Handle Mod_Handle_downCast(IMod_Handle handle);
    84     *
    85     *      // type-safe conversion from a module to an interface it inherits from
    86     *      // Returns NULL if the conversion is not valid
    87     *      IMod_Handle Mod_Handle_upCast(Mod_Module_Handle handle);
    88     *
    89     *  // methods to access the instances managed by Mod
    90     *
    91     *      // return heap used to create instances
    92     *      IHeap_Handle Mod_Object_heap();
    93     *
    94     *      // return count of static instances
    95     *      Int Mod_Object_count();
    96     *
    97     *      // get the i'th instance object of an array of instance objects
    98     *      //
    99     *      // If the array reference is NULL, get the i'th statically created
   100     *      // instance object.
   101     *      Mod_Object *Mod_Object_get(Mod_Object *array, Int i);
   102     *
   103     *      // get the first "live" runtime instance
   104     *      Mod_Object *Mod_Object_first();
   105     *
   106     *      // get the next "live" runtime instance
   107     *      Mod_Object *Mod_Object_next(Mod_Object *obj);
   108     *
   109     *  // methods that operate on instance handles
   110     *
   111     *      // fill in buf structure with instance's label info, returns buf
   112     *      Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);
   113     *
   114     *      // returns name of the instance inst, if it has one (otherwise NULL)
   115     *      String Mod_Handle_name(Mod_Handle inst);
   116     *
   117     *      // type-safe conversion of module handle to interface handle
   118     *      // Returns NULL if the conversion is not valid
   119     *      IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);
   120     *
   121     *      // type-safe conversion of interface handle to module handle
   122     *      // Returns NULL if the conversion is not valid
   123     *      Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);
   124     *
   125     *      // get the module that created the handle
   126     *      Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
   127     *  @p
   128     */
   129    interface IModule {
   130
   131        /*!
   132         *  ======== common$ ========
   133         *  Common module configuration parameters
   134         *
   135         *  All modules have this configuration parameter.  Its name
   136         *  contains the '$' character to ensure it does not conflict with
   137         *  configuration parameters declared by the module.  This allows
   138         *  new configuration parameters to be added in the future without
   139         *  any chance of breaking existing modules.
   140         */
   141        metaonly config Types.Common$ common$;
   142
   143        /*!
   144         *  ======== viewNameMap$ ========
   145         *  Specifies the ROV views for the module.
   146         *  @_nodoc
   147         *
   148         *  Maps the view name to the RovView descriptor.
   149         */
   150        metaonly config Types.ViewInfo viewNameMap$[string];
   151
   152        /*!
   153         *  ======== rovShowRawTab$ ========
   154         *  @_nodoc
   155         */
   156        metaonly config Bool rovShowRawTab$ = true;
   157
   158        /*!
   159         *  ======== configNameMap$ ========
   160         *  @_nodoc
   161         */
   162        metaonly readonly config Types.ViewInfo configNameMap$[string] = [
   163            ["xdc.runtime/Memory", {viewType: "module", fields: [
   164                "common$.instanceHeap", "common$.instanceSection",
   165                "common$.memoryPolicy",
   166                "common$.namedModule", "common$.namedInstance",
   167                "common$.fxntab", "common$.romPatchTable"
   168            ]}],
   169            ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
   170                "common$.logger",
   171                "common$.diags_ASSERT", "common$.diags_ENTRY",
   172                "common$.diags_EXIT", "common$.diags_INTERNAL",
   173                "common$.diags_LIFECYCLE",
   174                "common$.diags_STATUS",
   175                "common$.diags_USER1",
   176                "common$.diags_USER2", "common$.diags_USER3",
   177                "common$.diags_USER4", "common$.diags_USER5",
   178                "common$.diags_USER6", "common$.diags_INFO",
   179                "common$.diags_ANALYSIS"
   180            ]}],
   181            ["xdc.runtime/Concurrency", {viewType: "module", fields: [
   182                "common$.gate", "common$.gateParams"
   183            ]}],
   184            ["xdc.runtime/Log Events", {viewType: "module", fields: [
   185                "Log.Event"]}],
   186            ["xdc.runtime/Log Events", {viewType: "instance", fields: [
   187                "Log.Event"]}],
   188            ["xdc.runtime/Asserts", {viewType: "module", fields: [
   189                "Assert.Id"]}],
   190            ["xdc.runtime/Asserts", {viewType: "instance", fields: [
   191                "Assert.Id"]}],
   192            ["xdc.runtime/Errors", {viewType: "module", fields: [
   193                "Error.Id"]}],
   194            ["xdc.runtime/Errors", {viewType: "instance", fields: [
   195                "Error.Id"]}],
   196        ];
   197
   198        /*! @_nodoc */
   199        @System config Bits32 Module__diagsEnabled = 0;
   200        /*! @_nodoc */
   201        @System config Bits32 Module__diagsIncluded = 0;
   202        /*! @_nodoc */
   203        @System config Bits16* Module__diagsMask = null;
   204
   205        /*! @_nodoc */
   206        @System config Ptr Module__gateObj = null;
   207        /*! @_nodoc */
   208        @System config Ptr Module__gatePrms = null;
   209
   210        /*! @_nodoc */
   211        @System config Types.ModuleId Module__id = 0;
   212
   213        /*! @_nodoc */
   214        @System config Bool Module__loggerDefined = false;
   215        /*! @_nodoc */
   216        @System config Ptr Module__loggerObj = null;
   217        /*! @_nodoc */
   218        @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
   219        /*! @_nodoc */
   220        @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
   221        /*! @_nodoc */
   222        @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
   223        /*! @_nodoc */
   224        @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
   225        /*! @_nodoc */
   226        @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
   227
   228        /*! @_nodoc
   229         *  This parameter is not used, but we keep it for forward compatibility.
   230         *  If we can ever break the forward compatibility for a release, we
   231         *  should remove this parameter.
   232         *
   233         *  Once we remove it, header files built with those tools would break
   234         *  older tools.
   235         */
   236        @System config Bool (*Module__startupDoneFxn)() = null;
   237
   238        /*! @_nodoc */
   239        @System config Int Object__count = 0;
   240        /*! @_nodoc */
   241        @System config IHeap.Handle Object__heap = null;
   242        /*! @_nodoc */
   243        @System config SizeT Object__sizeof = 0;
   244        /*! @_nodoc */
   245        @System config Ptr Object__table = null;
   246
   247        /*!
   248         *  ======== Handle__label ========
   249         *  Initialize a `Types.Label` from an instance handle
   250         *  @_nodoc
   251         *
   252         *  @param(obj) input instance handle
   253         *  @param(lab) pointer to `Label` struct to initialize from `obj`
   254         */
   255        @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
   256
   257        /*! @_nodoc */
   258        @System Bool Module__startupDone();
   259
   260        /*! @_nodoc */
   261        @System Ptr Object__create(Ptr __oa, SizeT __osz, Ptr __aa,
   262            const UChar *__pa, SizeT __psz, Error.Block *__eb);
   263        /*! @_nodoc */
   264        @System Void Object__delete(Ptr instp);
   265        /*! @_nodoc */
   266        @System Void Object__destruct(Ptr objp);
   267
   268        /*! @_nodoc */
   269        @System Ptr Object__get(Ptr oarr, Int i);
   270
   271        /*!
   272         *  ======== Object__first ========
   273         *  Return the first member of a list of dynamically created instances
   274         *  @_nodoc
   275         *
   276         *  @a(warning) The methods `first()` and `next()` are not thread-safe.
   277         *              The caller must ensure that no instances are removed or
   278         *              added while the list is being traversed.
   279         *
   280         *  @a(returns)
   281         *  Returns a handle to a first instance or `NULL` if there are no
   282         *  instances in the list.
   283         */
   284        @System Ptr Object__first();
   285
   286        /*!
   287         *  ======== Object__next ========
   288         *  Return the next instance from the list of dynamically created instances
   289         *  @_nodoc
   290         *
   291         *  @param(obj) handle to a dynamically created instance
   292         *
   293         *  @a(returns)
   294         *  Returns a handle to a first instance or `NULL` if there are no
   295         *  instances in the list
   296         */
   297        @System Ptr Object__next(Ptr obj);
   298
   299        /*! @_nodoc */
   300        @System Void Params__init(Ptr dst, Ptr src, SizeT psz, SizeT isz);
   301
   302        /*! @_nodoc */
   303        @System Bool Proxy__abstract();
   304        /*! @_nodoc */
   305        @System Ptr Proxy__delegate();
   306
   307    }
   308    /*
   309     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   310     */
   311


interface xdc.runtime.ISystemSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ISystemSupport.xdc ========
    15     */
    16    package xdc.runtime;
    17
    18    /*!
    19     *  ======== ISystemSupport ========
    20     *  Interface to core system functions.
    21     *
    22     *  Each embedded system requires implementations of these functions but
    23     *  the behavior of these functions varies depending on the context of the
    24     *  embedded system.  For example, some systems will implement `exit()` as
    25     *  an infinite loop because the executable is designed to *never* exit.
    26     */
    27    interface ISystemSupport {
    28
    29        /*!
    30         *  ======== abort ========
    31         *  Backend for `{@link System#abort()}`
    32         *
    33         *  This function is called by `{@link System#abort()}` prior to calling
    34         *  the ANSI C Standard library function `abort()`.  So, to ensure the
    35         *  abort processing of the system's ANSI C Standard library completes,
    36         *  this function should return to its caller.
    37         *
    38         *  @param(str)  message to output just prior to aborting
    39         *
    40         *      If non-`NULL`, this string should be output just prior to
    41         *      terminating.
    42         */
    43        Void abort(String str);
    44
    45        /*!
    46         *  ======== exit ========
    47         *  Backend for `{@link System#exit()}`
    48         *
    49         *  This function is called as part the normal "atexit" processing
    50         *  performed by the ANSI C Standard Library's `exit()` function;
    51         *  `{@link System#exit()}` directly calls ANSI `exit()`.
    52         *
    53         *  This function is called after all "atexit" handlers bound via
    54         *  `{@link System#atexit()}` are run and it
    55         *  is always called while "inside" the the `System` gate.
    56         *
    57         *  To ensure that all exit processing of the system's ANSI C
    58         *  Standard Library completes, this function should return to its caller.
    59         *  Exit handlers bound using the ANSI C Standard Library `atexit()`
    60         *  function may run before or after this function.
    61         *
    62         *  @param(stat)    status value passed to all "atexit" handlers
    63         *
    64         *      This value is passed to all "atexit" handles bound via
    65         *      `{@link System#atexit()}`.  If the application exits via the
    66         *      ANSI C Standard `exit()` function rather than via System_exit(),
    67         *      `stat` will be equal to `{@link System#STATUS_UNKNOWN}`.
    68         *
    69         *  @see System#atexit
    70         */
    71        Void exit(Int stat);
    72
    73        /*!
    74         *  ======== flush ========
    75         *  Backend for `{@link System#flush()}`
    76         *
    77         *  This function is simply called by `{@link System#flush System_flush}`
    78         *  to output any characters buffered by the underlying `SystemSupport`
    79         *  module to an output device.
    80         */
    81        Void flush();
    82
    83        /*!
    84         *  ======== putch ========
    85         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
    86         *
    87         *  Output a single character.  This function is called by
    88         *  `{@link System#printf System_printf()}` to write each character
    89         *  of formated output specified by its arguments.
    90
    91         *
    92         *  @param(ch)  character to output
    93         */
    94        Void putch(Char ch);
    95
    96        /*!
    97         *  ======== ready ========
    98         *  Test if character output can proceed
    99         *
   100         *  This function is called by `{@link System}` prior to performing
   101         *  any character output.  If this function returns `FALSE`, the `System`
   102         *  functions that would normally call `putch()` simply return
   103         *  (with an appropriate error status) without ever calling
   104         *  `{@link #putch}`.
   105         */
   106        Bool ready();
   107    }
   108    /*
   109     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   110     */
   111


interface xdc.runtime.ITimestampClient

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ITimestampClient.xdc ========
    15     */
    16    package xdc.runtime;
    17
    18    /*!
    19     *  ======== ITimestampClient ========
    20     *  Timestamp Client Interface
    21     *
    22     *  This interface defines the methods used by client applications to
    23     *  get timestamp values.  It is implemented by the
    24     *  `{@link xdc.runtime.Timestamp Timestamp}` module.
    25     */
    26    interface ITimestampClient {
    27
    28        /*!
    29         *  ======== get32 ========
    30         *  Return a 32-bit timestamp
    31         *
    32         *  @a(returns)
    33         *  Returns a 32-bit timestamp value.
    34         *  Use `{@link #getFreq}` to convert this value into units of real time.
    35         *
    36         *  @see #get64
    37         */
    38        Bits32 get32();
    39
    40        /*!
    41         *  ======== get64 ========
    42         *  Return a 64-bit timestamp
    43         *
    44         *  @param(result)  pointer to 64-bit result
    45         *
    46         *      This parameter is a pointer to a structure representing a 64-bit
    47         *      wide timestamp value where the current timestamp is written.
    48         *
    49         *      If the underlying hardware does not support 64-bit resolution, the
    50         *      `hi` field of `result` is always set to 0; see
    51         *      `{@link xdc.runtime.Types#Timestamp64}`.  So, it is possible for
    52         *      the `lo` field to wrap around without any change to the `hi` field.
    53         *      Use `{@link #getFreq}` to convert this value into units of real
    54         *      time.
    55         *
    56         *  @see #get32
    57         */
    58        Void get64(Types.Timestamp64 *result);
    59
    60        /*!
    61         *  ======== getFreq ========
    62         *  Get the timestamp timer's frequency (in Hz)
    63         *
    64         *  @param(freq)  pointer to a 64-bit result
    65         *
    66         *      This parameter is a pointer to a structure representing a 64-bit
    67         *      wide frequency value where the timer's frequency (in Hz)
    68         *      is written; see `{@link xdc.runtime.Types#FreqHz}`.
    69         *      This function provides a way of converting timestamp
    70         *      values into units of real time.
    71         *
    72         *  @see #get32
    73         *  @see #get64
    74         */
    75        Void getFreq(Types.FreqHz *freq);
    76    }
    77    /*
    78     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    79     */
    80


interface xdc.runtime.ITimestampProvider

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ITimestampProvider.xdc ========
    15     */
    16    package xdc.runtime;
    17
    18    /*!
    19     *  ======== ITimestampProvider ========
    20     *  Timestamp provider interface
    21     *
    22     *  This interface is implemented by platform-specific modules that
    23     *  "provide" underlying timestamp services for the
    24     *  `{@link xdc.runtime.Timestamp}` module.
    25     *
    26     *  Only the `{@link xdc.runtime.Timestamp}` module and the
    27     *  `{@link xdc.runtime.ITimestampClient}` interface should be directly
    28     *  referenced by platform-independent applications.
    29     *
    30     *  This interface is part of a design pattern that includes the
    31     *  `ITimestampClient` interface and the `Timestamp` module.  This pattern
    32     *  allows client code to:
    33     *  @p(blist)
    34     *      - use the platform-independent interfaces provided by either
    35     *        `ITimestampClient` and `Timestamp` and remain 100% portable
    36     *      - optionally leverage platform-specific capabilities
    37     *        of any module that implements `ITimestampProvider` and still always
    38     *        have access to the platform-independent methods specified by
    39     *        `ITimestampClient` (because `ITimestampProvider` inherits from
    40     *        `ITimestampClient`)
    41     *  @p
    42     *  This pattern is in contrast to other "provider" interfaces that exist only
    43     *  to specify the methods necessary to enable "higher-level" modules; client
    44     *  code *never* accesses these provider interfaces directly, clients always
    45     *  only use the higher-level modules.
    46     */
    47    interface ITimestampProvider inherits ITimestampClient {
    48    }
    49    /*
    50     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    51     */
    52


module xdc.runtime.Log

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Log.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== Log ========
    19     *  Event logging manager
    20     *
    21     *  RTSC modules and the application code generate `{@link #Event Log_Event}`
    22     *  events by calling the `Log` module's functions. The `Log` module then
    23     *  passes those events to an `{@link ILogger}` instance assigned to the event
    24     *  originating module, specified by that module's configuration parameter
    25     *  `common$.logger`. `ILogger` instances handle events, usually converting
    26     *  events to `{@link #EventRec Log_EventRec}` records prior to recording,
    27     *  transmitting, or displaying them.
    28     *
    29     *  All events generated by a target module are stored and displayed by an
    30     *  `ILogger`, examples of which are instances of
    31     *  `{@link LoggerBuf xdc.runtime.LoggerBuf}` or
    32     *  `{@link LoggerSys xdc.runtime.LoggerSys}`. At runtime, modules
    33     *  generate events through this module, rather than invoking directly their
    34     *  `ILogger`s. By doing so,  modules can be configured to use different
    35     *  `ILogger` implementations without any changes to their source code.
    36     *
    37     *  A logger instance can accept `Log` events from any module, but a module
    38     *  can put `Log` events to only one logger instance. There can be one or
    39     *  more logger instances in a system. All `Log` calls that are not in a
    40     *  module are controlled by the module `{@link Main xdc.runtime.Main}`.
    41     *  For example, top-level application code or any existing sources that
    42     *  simply call the `Log` or `Assert` methods implicitly use the logger
    43     *  associated with the `Main` module.
    44     *
    45     *  The generation of a `Log` event is controlled by a module's diagnostics
    46     *  mask, which is described in details in `{@link Diags}`. Each `Log` event
    47     *  is associated with a mask. `Log` events are generated only when a
    48     *  particular bit is set in both the `Log` event mask
    49     *  and the module's diagnostics mask. For example, a `Log` event mask with
    50     *  the `{@link Diags#USER1 USER1}` bit set is generated only when the `USER1`
    51     *  bit is also set in the module's diagnostics mask.
    52     *
    53     *  There are two ways to generate `Log` events:
    54     *
    55     *  @p(blist)
    56     *  - `{@link #write8 Log_write()}`, which is tailored for module writers
    57     *  and takes full advantage of the XDC configuration model. For example,
    58     *  the message string associated with the `Log` event need not be a part of
    59     *  the final application, significantly reducing the "footprint overhead"
    60     *  of embedding diagnostics in deployed systems. The `Log_write[0-8]()`
    61     *  functions allow up to 8 values to be passed to the logger. They expect
    62     *  the logger to handle any formatting. A `Log` event type allows you to
    63     *  specify the type of event.
    64     *  - `{@link #print6 Log_print()}`, which is designed for arbitrary C code.
    65     *  The `Log_print[0-6]()` functions allow up to 6 values to be passed along
    66     *  with a printf-like format string to the logger. They handle printf-style
    67     *  formatting.
    68     *  @p
    69     *
    70     *  Both functions are controlled by the module's diagnostics mask. Their
    71     *  storage or output is defined by the logger that is assigned to the
    72     *  module that calls the `Log` methods or to the
    73     *  `{@link Main xdc.runtime.Main}` module if the caller is not part of a
    74     *  module.
    75     *
    76     *  The `Log` function call sites are implemented in such a way that an
    77     *  optimizer can completely eliminate `Log` code from the program if the
    78     *  `Log` functions have been permanently disabled at configuration time. If
    79     *  the `Log` functions are permanently turned on at configuration time,
    80     *  then the optimizer can eliminate all runtime conditional checking and
    81     *  simply invoke the `Log` functions directly. Runtime checking is performed
    82     *  only when the `Log` functions are configured to be runtime modifiable.
    83     *
    84     *  The Log calls can also be completely removed by defining the symbol
    85     *  `xdc_runtime_Log_DISABLE_ALL`. This can be done on the compile line, e.g.
    86     *  `-Dxdc_runtime_Log_DISABLE_ALL`. This will completely remove the `Log`
    87     *  statements from any code compiled with this flag, regardless of the
    88     *  application's logging configuration or your compiler's optimization
    89     *  settings.
    90     *
    91     *  It is also possible to remove all logging except for
    92     *  `{@link #error Log_error}`, `{@link #warning Log_warning}`, or
    93     *  `{@link #info Log_info}` statements. This is done by first defining
    94     *  `xdc_runtime_Log_DISABLE_ALL`, followed by defining one or more of the
    95     *  symbols below to leave that type of logging enabled:
    96     *  @p(blist)
    97     *  - `xdc_runtime_Log_ENABLE_ERROR`
    98     *  - `xdc_runtime_Log_ENABLE_WARNING`
    99     *  - `xdc_runtime_Log_ENABLE_INFO`
   100     *  @p
   101     *  For example, to disable all `Log` statements except for `Log_error`, add
   102     *  the following to the compile line:
   103     *  @p(code)
   104     *      -Dxdc_runtime_Log_DISABLE_ALL -Dxdc_runtime_Log_ENABLE_ERROR
   105     *  @p
   106     *
   107     *  @a(Examples)
   108     *  Example 1: The following example defines a `Log` event, uses that `Log`
   109     *  event in a module, and configures the program to generate the `Log`
   110     *  event. In this example, both `USER1` and `USER2` bits are set in the
   111     *  event mask. This means that if either bit is set in the module's
   112     *  diagnostics mask, then the `Log` event will be generated.
   113     *
   114     *  This is a part of the XDC specification file for the `Mod` module
   115     *  (Mod.xdc):
   116     *
   117     *  @p(code)
   118     *  import xdc.runtime.Diags;
   119     *  import xdc.runtime.Log;
   120     *
   121     *  config Log.Event L_someEvent = {
   122     *      mask: Diags.USER1 | Diags.USER2,
   123     *      level: Diags.LEVEL1,
   124     *      msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
   125     *  };
   126     *  @p
   127     *
   128     *  This is a part of the C code implementation of the Mod module:
   129     *
   130     *  @p(code)
   131     *  #include <xdc/runtime/Log.h>
   132     *  UInt x, y;
   133     *
   134     *  Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
   135     *  @p
   136     *
   137     *  The following configuration script demonstrates how the application might
   138     *  control the `Log` statements embedded in the `Mod` module at configuration
   139     *  time. In this case, the configuration script arranges for the `Log`
   140     *  statements within the `Mod` module (shown above) to always generate events.
   141     *  Without these configuration statements, no `Log` events would be generated
   142     *  by this module.
   143     *
   144     *  This is part of the XDC configuration file for the application:
   145     *
   146     *  @p(code)
   147     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   148     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
   149     *  var Mod = xdc.useModule('my.pkg.Mod');
   150     *  Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
   151     *  Mod.common$.logger = LoggerSys.create();
   152     *  @p
   153     *
   154     *  @p(html)
   155     *  <hr />
   156     *  @p
   157     *
   158     *  Example 2: The following XDC configuration statements turn on enter
   159     *  and exit logging at configuration time for a module. Without any other
   160     *  changes in the runtime code, every time a module `Mod`'s function is
   161     *  being called or exits, an event will be logged.
   162     *
   163     *  @p(code)
   164     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   165     *  var Mod = xdc.useModule('my.pkg.Mod');
   166     *
   167     *  Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
   168     *  Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
   169     *  @p
   170     *
   171     *  @p(html)
   172     *  <hr />
   173     *  @p
   174     *
   175     *  Example 3: The following example configures a module to support enter and
   176     *  exit logging, but defers the actual activation and deactivation of the
   177     *  logging until runtime. See the `{@link Diags#setMask Diags_setMask()}`
   178     *  function for details on specifying the control string.
   179     *
   180     *  This is a part of the XDC configuration file for the application:
   181     *
   182     *  @p(code)
   183     *  var Diags = xdc.useModule('xdc.runtime.Diags');
   184     *  var Mod = xdc.useModule('my.pkg.Mod');
   185     *
   186     *  Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
   187     *  Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
   188     *  @p
   189     *
   190     *  This is a part of the C code for the application:
   191     *
   192     *  @p(code)
   193     *  // turn on enter and exit logging in the module
   194     *  Diags_setMask("my.pkg.Mod+EX");
   195     *
   196     *  // turn off enter and exit logging in the module
   197     *  Diags_setMask("my.pkg.Mod-EX");
   198     *  @p
   199     */
   200
   201    @CustomHeader
   202
   203    module Log {
   204
   205        /*!
   206         *  ======== NUMARGS ========
   207         *  Maximum number of arguments supported in `Log` events.
   208         */
   209        const Int NUMARGS = 8;
   210
   211        /*!
   212         *  ======== PRINTFID ========
   213         *  The `EventId` for `Log_print()` events
   214         */
   215        const EventId PRINTFID = 0;
   216
   217        /*!
   218         *  ======== EventDesc ========
   219         *  `Log` event descriptor
   220         *
   221         *  Each `Log` event is defined by a `Log` event descriptor.
   222         *
   223         *  The `mask` defines which bits in the module's diagnostics mask
   224         *  enable this `Log` event.  Events "posted" via `Log_write` are only
   225         *  written to the underlying logger if one of the mask's bits matches
   226         *  the caller's module diagnostics settings (see
   227         *  `{@link xdc.runtime.Types#common$}`).
   228         *
   229         *  The 'level' defines the event level of the event. While the diags
   230         *  bits selected in the 'mask' signify the "category" of the event (e.g.
   231         *  Entry/Exit, Analysis, Info), the 'level' field allows you to assign
   232         *  a "priority" or "detail level" to the event relative to other events in
   233         *  that category. There are four event levels defined by
   234         *  '{@link xdc.runtime.Diags#EventLevel}'.
   235         *
   236         *  Filtering of events by level is handled by the ILogger implementation.
   237         *  ILogger implementations which also implement the {@link IFilterLogger}
   238         *  interface support filtering of events based on priority level.
   239         *
   240         *  Specifying an event level is optional. Events that don't specify a
   241         *  level will receive Diags.LEVEL1 by default, making them the highest
   242         *  priority and ensuring that they will not inadvertently be filtered out
   243         *  by level-based filtering.
   244         *
   245         *  The `msg` defines a printf style format string that defines how to
   246         *  render the arguments passed along the event in a `Log_write` call.
   247         *  For a description of the allowable format strings see
   248         *  `{@link #print6}`.
   249         *
   250         *  @see #write8
   251         *  @see #print6
   252         */
   253        metaonly struct EventDesc {
   254            Diags.Mask          mask;   /*! event enable mask */
   255            Diags.EventLevel    level;  /*! event level relative to other events */
   256            String              msg;    /*! event "printf" message format string */
   257        };
   258
   259        /*!
   260         *  ======== EventRec ========
   261         *  The target representation of a recorded event
   262         *
   263         *  This structure defines how events are recorded on the target.
   264         */
   265        struct EventRec {
   266            Types.Timestamp64 tstamp;   /*! time event was written */
   267            Bits32 serial;              /*! serial number of event */
   268            Types.Event evt;            /*! target encoding of an Event */
   269            IArg arg[NUMARGS];          /*! arguments passed via Log_write/print */
   270        }
   271
   272        /*!
   273         *  ======== Event ========
   274         *  `Log` event type
   275         *
   276         *  An `Event` is represented on the target as a 32-bit value that can
   277         *  be decoded offline to recover the `Event` information defined in
   278         *  a corresponding metaonly `EventDesc`.  In addition, `Event`s may be
   279         *  decoded at runtime via methods provided in this module; see
   280         *  `{@link #getMask}` and `{@link #getEventId}`.
   281         *
   282         *  When an event is "raised" a `{@link Types#Event Types_Event}` is
   283         *  created which has the same event ID as the `Log_Event` but also
   284         *  encodes the module ID of the caller.  This new event is passed to
   285         *  the underlying `{@link ILogger}` module along with any arguments
   286         *  associated with the event.
   287         *
   288         *  @see #getMask
   289         *  @see #getEventId
   290         */
   291        @Encoded typedef EventDesc Event;
   292
   293        /*!
   294         *  ======== EventId ========
   295         *  Unique ID embedded in each `{@link #Event}`
   296         *
   297         *  This ID must be used to compare two `Event`s for equality.  Event
   298         *  ids are not guaranteed to remain constant between different
   299         *  configurations of an application.  For example, adding a module
   300         *  may cause the event ids of another module to change.
   301         *
   302         *  However, event ids declared by a module are guaranteed to be
   303         *  consecutive values starting from the first declared
   304         *  `{@link #Event Log_Event}` and increasing to the last declared
   305         *  event.  As a result, clients of a module can efficiently test ranges
   306         *  of events and modules can add new events, such as internal trace
   307         *  events, without breaking clients; simply be careful to add new events
   308         *  after any existing events in you module's `.xdc` specification.
   309         *
   310         *  @see #getEventId
   311         *  @see #Event
   312         */
   313        typedef Types.RopeId EventId;
   314
   315        /*!
   316         *  ======== L_construct ========
   317         *  Lifecycle event posted when an instance is constructed
   318         */
   319        config Log.Event L_construct = {
   320            mask: Diags.LIFECYCLE,
   321            msg: "<-- construct: %p('%s')"
   322        };
   323
   324        /*!
   325         *  ======== L_create ========
   326         *  Lifecycle event posted when an instance is created
   327         */
   328        config Log.Event L_create = {
   329            mask: Diags.LIFECYCLE,
   330            msg: "<-- create: %p('%s')"
   331        };
   332
   333        /*!
   334         *  ======== L_destruct ========
   335         *  Lifecycle event posted when an instance is destructed
   336         */
   337        config Log.Event L_destruct = {
   338            mask: Diags.LIFECYCLE,
   339            msg: "--> destruct: (%p)"
   340        };
   341
   342        /*!
   343         *  ======== L_delete ========
   344         *  Lifecycle event posted when an instance is deleted
   345         */
   346        config Log.Event L_delete = {
   347            mask: Diags.LIFECYCLE,
   348            msg: "--> delete: (%p)"
   349        };
   350
   351        /*!
   352         *  ======== L_error ========
   353         *  Error event posted by Log_errorX API
   354         *
   355         *  This event is marked as a STATUS event and given the priority level
   356         *  of ERROR.
   357         *
   358         *  This event prints the Log call site (%$F) and a format string (%$S)
   359         *  which is recursively formatted with any addition arguments.
   360         */
   361        config Log.Event L_error = {
   362            mask: Diags.STATUS,
   363            level: Diags.ERROR,
   364            msg: "ERROR: %$F%$S"
   365        };
   366
   367        /*!
   368         *  ======== L_warning ========
   369         *  Warning event posted by Log_warningX API
   370         *
   371         *  This event is marked as a STATUS event and given the priority level of
   372         *  WARNING.
   373         *
   374         *  This event prints the Log call site (%$F) and a format string (%$S)
   375         *  which is recursively formatted with any addition arguments.
   376         */
   377        config xdc.runtime.Log.Event L_warning = {
   378            mask: Diags.STATUS,
   379            level: Diags.WARNING,
   380            msg: "WARNING: %$F%$S"
   381        };
   382
   383        /*!
   384         *  ======== L_info ========
   385         *  Info event posted by Log_infoX API
   386         *
   387         *  This event is marked as an INFO event. The event priority is not
   388         *  specified in the event definition. Rather, it is specified as an
   389         *  argument to the Log_infoX APIs.
   390         *
   391         *  This event prints the Log call site (%$F) and a format string (%$S)
   392         *  which is recursively formatted with any addition arguments.
   393         */
   394        config xdc.runtime.Log.Event L_info = {
   395            mask: Diags.INFO,
   396            msg: "%$F%$S"
   397        };
   398
   399        /*!
   400         *  ======== getMask ========
   401         *  Get the `Diags` mask for the specified (encoded) event
   402         *
   403         *  @param(evt) the `Log` event encoding a mask and event ID
   404         *
   405         *  @a(returns) `Diags` mask for the specified event
   406         */
   407        @Macro Diags.Mask getMask(Event evt);
   408
   409        /*!
   410         *  ======== getRope ========
   411         *  Get RopeId of the Event.msg for the specified (encoded) event
   412         *  @_nodoc
   413         */
   414        @Macro Text.RopeId getRope(Event evt);
   415
   416        /*!
   417         *  ======== getEventId ========
   418         *  Get event ID of the specified (encoded) event
   419         *
   420         *  This method is used to compare "known" `Log` events with
   421         *  "raised" `{@link Types#Event Types_Event}`.
   422         *
   423         *  @param(evt) the `Log` event encoding a mask and event ID
   424         *
   425         *  @a(returns) event ID of the specified event
   426         *
   427         *  @see Types#getEventId
   428         */
   429        @Macro EventId getEventId(Event evt);
   430
   431        /*!
   432         *  ======== print0 ========
   433         *  Generate a `Log` "print event" with 0 arguments
   434         *
   435         *  @see #print6
   436         */
   437        @Macro Void print0(Diags.Mask mask, String fmt);
   438
   439        /*!
   440         *  ======== print1 ========
   441         *  Generate a `Log` "print event" with 1 argument
   442         *
   443         *  @see #print6
   444         */
   445        @Macro Void print1(Diags.Mask mask, String fmt, IArg a1);
   446
   447        /*!
   448         *  ======== print2 ========
   449         *  Generate a `Log` "print event" with 2 arguments
   450         *
   451         *  @see #print6
   452         */
   453        @Macro Void print2(Diags.Mask mask, String fmt, IArg a1, IArg a2);
   454
   455        /*!
   456         *  ======== print3 ========
   457         *  Generate a `Log` "print event" with 3 arguments
   458         *
   459         *  @see #print6
   460         */
   461        @Macro Void print3(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3);
   462
   463        /*!
   464         *  ======== print4 ========
   465         *  Generate a `Log` "print event" with 4 arguments
   466         *
   467         *  @see #print6
   468         */
   469        @Macro Void print4(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
   470            IArg a4);
   471
   472        /*!
   473         *  ======== print5 ========
   474         *  Generate a `Log` "print event" with 5 arguments
   475         *
   476         *  @see #print6
   477         */
   478        @Macro Void print5(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
   479            IArg a4, IArg a5);
   480
   481        /*!
   482         *  ======== print6 ========
   483         *  Generate a `Log` "print event" with 6 arguments
   484         *
   485         *  As a convenience to C (as well as assembly language) programmers,
   486         *  the `Log` module provides a variation of the ever-popular `printf`
   487         *  function.
   488         *  The `print[0-6]` functions generate a `Log` "print event" and route
   489         *  it to the current module's logger.
   490         *
   491         *  The arguments passed to `print[0-6]` may be characters, integers,
   492         *  strings, or pointers.  However, because the declared type of the
   493         *  arguments is `{@link xdc IArg}`, all pointer arguments must be cast
   494         *  to an `IArg` type.  `IArg` is an integral type large enough to hold
   495         *  any pointer or an `int`.  So, casting a pointer to an `IArg` does
   496         *  not cause any loss of information and C's normal integer conversions
   497         *  make the cast unnecessary for integral arguments.
   498         *
   499         *  The format string can use the following conversion characters.
   500         *  However, it is important to recall that all arguments referenced by
   501         *  these conversion characters have been converted to an `IArg`
   502         *  prior to conversion; so, the use of "length modifiers" should be
   503         *  avoided.
   504         *
   505         *  @p(code)
   506         *  Conversion Character    Description
   507         *  ------------------------------------------------
   508         *  %c                      Character
   509         *  %d                      Signed integer
   510         *  %u                      Unsigned integer
   511         *  %x                      Unsigned hexadecimal integer
   512         *  %o                      Unsigned octal integer
   513         *  %s                      Character string
   514         *  %p                      Pointer
   515         *  %f                      Single precision floating point (float)
   516         *  @p
   517         *
   518         *  Format strings, while very convenient, are a well known source of
   519         *  portability problems: each format specification must precisely match
   520         *  the types of the arguments passed. Underlying "printf" functions use
   521         *  the format string to determine how far to advance through their
   522         *  argument list. For targets where pointer types and integers are the
   523         *  same size there are no problems.  However, suppose a target's pointer
   524         *  type is larger than its integer type. In this case, because integer
   525         *  arguments are widened to be of type `IArg`, a format specification of
   526         *  "%d" causes an underlying `printf()` implementation to read the
   527         *  extended part of the integer argument as part of the next argument(!).
   528         *
   529         *  To get around this problem and still allow the use of "natural"
   530         *  format specifications (e.g., `%d` and `%x` with optional width
   531         *  specifications), `{@link System#aprintf()}` is used which assumes
   532         *  that all arguments have been widened to be of type `IArg`.
   533         *
   534         *  See `{@link System#printf}` for complete details.
   535         *
   536         *  The `%f` format specifier is used to print a single precision float
   537         *  value. Note that `%f` assumes that sizeof(Float) <= sizeof(IArg).
   538         *  Most clients that interpret float values expect that they are
   539         *  represented in IEEE 754 floating point format. Therefore, it is
   540         *  recommended that the float values be converted into that format prior
   541         *  to supplying the values to `Log` functions in cases where targets do
   542         *  not generate the float values in IEEE 754 floating point format by
   543         *  default.
   544         *
   545         *  The first argument to a `Log_print` call is the diags category to be
   546         *  associated with the event.
   547         *
   548         *  It is also possible to associate an event level with the event to
   549         *  enable filtering of events based on event level. Conceptually, it is
   550         *  best to regard the event level as completely separate from the event's
   551         *  diags category; however, the priority value actually occupies a part
   552         *  of the diags mask. For this reason, it is possible to specify an event
   553         *  level by OR'ing the level with the diags mask. For example, to print
   554         *  an `Diags_INFO` event of `Diags_LEVEL2`, you'd simply write:
   555         *  (Diags_INFO | Diags_LEVEL2)
   556         *
   557         *  Specifying an event level is optional. `Log_print` calls which do not
   558         *  specify a level will receive the highest priority by default.
   559         *
   560         *  @param(mask)    enable bits and optional detail level for this event
   561         *  @param(fmt)     a `printf` style format string
   562         *  @param(a1)      value for first format conversion character
   563         *  @param(a2)      value for second format conversion character
   564         *  @param(a3)      value for third format conversion character
   565         *  @param(a4)      value for fourth format conversion character
   566         *  @param(a5)      value for fifth format conversion character
   567         *  @param(a6)      value for sixth format conversion character
   568         *
   569         *  @a(Examples)
   570         *  The following example demonstrates a typical usage.
   571         *  @p(code)
   572         *  String  list[];
   573         *  UInt    i;
   574         *
   575         *  Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
   576         *  @p
   577         *  Note that the `IArg` cast above is only necessary for pointer
   578         *  arguments; C's normal parameter conversions implicitly convert
   579         *  integral arguments.
   580         *
   581         *  To simplify the conversion from `float` arguments to `IArg`,
   582         *  the standard header `xdc/std.h` provides a macro, named floatToArg(),
   583         *  to do this conversion in a type safe manner.  So, the following
   584         *  statement will print "`float = 2.3456`":
   585         *  @p(code)
   586         *    Log_print1(Diags_USER1, "float = %f", floatToArg(2.34567));
   587         *  @p
   588         *
   589         *  Note that, if you are formatting events on the target, you must
   590         *  also add support for floating point to ASCII conversion to
   591         *  `{@link System#printf}`; for more information, see the
   592         *  `{@link System#extendedFormats}` reference documenation.  For example:
   593         *  @p(code)
   594         *      var System = xdc.useModule('xdc.runtime.System');
   595         *      System.extendedFormats = "%f";
   596         *  @p
   597         */
   598        @Macro Void print6(Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3,
   599            IArg a4, IArg a5, IArg a6);
   600
   601        /*!
   602         *  ======== error0 ========
   603         *  Generate a `Log` "error event" with 0 arguments
   604         *
   605         *  @see #error5
   606         */
   607        @Macro Void error0(String fmt);
   608
   609        /*!
   610         *  ======== error1 ========
   611         *  Generate a `Log` "error event" with 1 argument
   612         *
   613         *  @see #error5
   614         */
   615        @Macro Void error1(String fmt, IArg a1);
   616
   617        /*!
   618         *  ======== error2 ========
   619         *  Generate a `Log` "error event" with 2 arguments
   620         *
   621         *  @see #error5
   622         */
   623        @Macro Void error2(String fmt, IArg a1, IArg a2);
   624
   625        /*!
   626         *  ======== error3 ========
   627         *  Generate a `Log` "error event" with 3 arguments
   628         *
   629         *  @see #error5
   630         */
   631        @Macro Void error3(String fmt, IArg a1, IArg a2, IArg a3);
   632
   633        /*!
   634         *  ======== error4 ========
   635         *  Generate a `Log` "error event" with 4 arguments
   636         *
   637         *  @see #error5
   638         */
   639        @Macro Void error4(String fmt, IArg a1, IArg a2, IArg a3,
   640            IArg a4);
   641
   642        /*!
   643         *  ======== error5 ========
   644         *  Generate a `Log` "error event" with 5 arguments
   645         *
   646         *  The Log_error APIs are intended to allow users to easily log error
   647         *  events in their code. Similar to the Log_print APIs, Log_error does not
   648         *  require that you define an event. You simply pass an informative error
   649         *  string which can optionally be formatted with additional arguments. The
   650         *  error is logged with the predefined event {@link #L_error}.
   651         *
   652         *  Log_error prepends a string to the message which identifies it as an
   653         *  ERROR and specifies the filename and line number of the Log_error call
   654         *  site. A simple example:
   655         *
   656         *  @p(code)
   657         *  Log_error0("Invalid argument");
   658         *  @p
   659         *  This event will be formatted as (assuming that the above call was line
   660         *  35 of "MyCode.c")
   661         *  @p(code)
   662         *  ERROR at "MyCode.c", line 35: Invalid argument
   663         *  @p
   664         *
   665         *  Users may provide additional information in the error event, such as
   666         *  a predefined error code or details of the error. These additional
   667         *  values will be used to format the string passed to Log_error.
   668         *  @see #print6 for information about format strings.
   669         *
   670         *  Log_error does not use a variable length argument list--you must call
   671         *  the appropriate Log_errorX API based on the number of arguments.
   672         *
   673         *  @param(fmt)      a reference to a constant error string / fmt string
   674         *  @param(a1)       value for an additional parameter (e.g. an error code)
   675         *  @param(a2)       value for an additional parameter
   676         *  @param(a3)       value for an additional parameter
   677         *  @param(a4)       value for an additional parameter
   678         *  @param(a5)       value for an additional parameter
   679         *
   680         *  @a(Examples)
   681         *  The following example demonstrates a typical usage.
   682         *  @p(code)
   683         *  Int myArg;
   684         *
   685         *  Log_error1("Invalid argument: %d", myArg);
   686         *  @p
   687         *  The above event is formatted as, for example:
   688         *  @p(code)
   689         *  ERROR: "MyCode.c", line 35: Invalid argument: -1
   690         *  @p
   691         */
   692        @Macro Void error5(String fmt, IArg a1, IArg a2, IArg a3,
   693            IArg a4, IArg a5);
   694
   695        /*!
   696         *  ======== warning0 ========
   697         *  Generate a `Log` "warning event" with 0 arguments
   698         *
   699         *  @see #warning5
   700         */
   701        @Macro Void warning0(String fmt);
   702
   703        /*!
   704         *  ======== warning1 ========
   705         *  Generate a `Log` "warning event" with 1 argument
   706         *
   707         *  @see #warning5
   708         */
   709        @Macro Void warning1(String fmt, IArg a1);
   710
   711        /*!
   712         *  ======== warning2 ========
   713         *  Generate a `Log` "warning event" with 2 arguments
   714         *
   715         *  @see #warning5
   716         */
   717        @Macro Void warning2(String fmt, IArg a1, IArg a2);
   718
   719        /*!
   720         *  ======== warning3 ========
   721         *  Generate a `Log` "warning event" with 3 arguments
   722         *
   723         *  @see #warning5
   724         */
   725        @Macro Void warning3(String fmt, IArg a1, IArg a2, IArg a3);
   726
   727        /*!
   728         *  ======== warning4 ========
   729         *  Generate a `Log` "warning event" with 4 arguments
   730         *
   731         *  @see #warning5
   732         */
   733        @Macro Void warning4(String fmt, IArg a1, IArg a2, IArg a3,
   734            IArg a4);
   735
   736        /*!
   737         *  ======== warning5 ========
   738         *  Generate a `Log` "warning event" with 5 arguments
   739         *
   740         *  The Log_warning APIs provide the same features as the Log_error APIs,
   741         *  but are used to specifically log "warning" events.
   742         *  @see #error5
   743         *
   744         *  The Log_warning APIs are equivalent to the Log_error APIs except that
   745         *  they use the predefined {@link #L_warning} event. Log_warning prepends
   746         *  a string to the message which identifies it as a WARNING and specifies
   747         *  the filename and line number of the Log_warning call site.
   748         *
   749         *  @param(fmt)     reference to a constant warning string / fmt string
   750         *  @param(a1)      value for an additional parameter (e.g. a warning code)
   751         *  @param(a2)      value for an additional parameter
   752         *  @param(a3)      value for an additional parameter
   753         *  @param(a4)      value for an additional parameter
   754         *  @param(a5)      value for an additional parameter
   755         *
   756         *  @a(Examples)
   757         *  The following example demonstrates a typical usage.
   758         *  @p(code)
   759         *  Int myArg;
   760         *
   761         *  Log_warning1("Value may be too high: %d", myArg);
   762         *  @p
   763         *  The above event is formatted as:
   764         *  @p(code)
   765         *  WARNING: "MyCode.c", line 50: Value may be too high: 4096
   766         *  @p
   767         */
   768        @Macro Void warning5(String fmt, IArg a1, IArg a2, IArg a3,
   769            IArg a4, IArg a5);
   770
   771        /*!
   772         *  ======== info0 ========
   773         *  Generate a `Log` "info event" with 0 arguments
   774         *
   775         *  @see #info5
   776         */
   777        @Macro Void info0(String fmt);
   778
   779        /*!
   780         *  ======== info1 ========
   781         *  Generate a `Log` "info event" with 1 argument
   782         *
   783         *  @see #info5
   784         */
   785        @Macro Void info1(String fmt, IArg a1);
   786
   787        /*!
   788         *  ======== info2 ========
   789         *  Generate a `Log` "info event" with 2 arguments
   790         *
   791         *  @see #info5
   792         */
   793        @Macro Void info2(String fmt, IArg a1, IArg a2);
   794
   795        /*!
   796         *  ======== info3 ========
   797         *  Generate a `Log` "info event" with 3 arguments
   798         *
   799         *  @see #info5
   800         */
   801        @Macro Void info3(String fmt, IArg a1, IArg a2, IArg a3);
   802
   803        /*!
   804         *  ======== info4 ========
   805         *  Generate a `Log` "info event" with 4 arguments
   806         *
   807         *  @see #info5
   808         */
   809        @Macro Void info4(String fmt, IArg a1, IArg a2, IArg a3, IArg a4);
   810
   811        /*!
   812         *  ======== info5 ========
   813         *  Generate a `Log` "info event" with 5 arguments
   814         *
   815         *  The Log_info APIs are provided for easily logging generic
   816         *  "informational" events with call site information. They are similar to
   817         *  the Log_print APIs in that they do not require you to define an event--
   818         *  you simply pass an informative printf-style string which can optionally
   819         *  be formatted with additional arguments. The info record is logged with
   820         *  the predefined event '{@link #L_info}'.
   821         *
   822         *  The Log_info APIs log the {@link #L_info} event which uses the 'INFO'
   823         *  diags category. They do not allow you to specify an event priority.
   824         *
   825         *  Log_info prepends the filename and line number of the call site to the
   826         *  message.
   827         *
   828         *  @param(fmt)     reference to a constant event string / fmt string
   829         *  @param(a1)      value for an additional parameter (e.g. an event code)
   830         *  @param(a2)      value for an additional parameter
   831         *  @param(a3)      value for an additional parameter
   832         *  @param(a4)      value for an additional parameter
   833         *  @param(a5)      value for an additional parameter
   834         *
   835         *  @a(Examples)
   836         *  The following example demonstrates a typical usage.
   837         *  @p(code)
   838         *  Int load;
   839         *
   840         *  Log_info1("Current load: %d", load);
   841         *  @p
   842         *  The above event is formatted as, for example:
   843         *  @p(code)
   844         *  "MyCode.c", line 15: Current load: 25
   845         *  @p
   846         */
   847        @Macro Void info5(String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
   848
   849         /*!
   850         *  ======== put0 ========
   851         *  Unconditionally put the specified Log event with 0 arguments
   852         *
   853         *  @see #put4
   854         */
   855        @Macro Void put0(Log.Event evt, Types.ModuleId mid);
   856
   857        /*!
   858         *  ======== put1 ========
   859         *  Unconditionally put the specified Log event and 1 argument
   860         *
   861         *  @see #put4
   862         */
   863        @Macro Void put1(Log.Event evt, Types.ModuleId mid, IArg a1);
   864
   865        /*!
   866         *  ======== put2 ========
   867         *  Unconditionally put the specified Log event and 2 arguments
   868         *
   869         *  @see #put4
   870         */
   871         @Macro Void put2(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2);
   872
   873        /*!
   874         *  ======== put4 ========
   875         *  Unconditionally put the specified Log event
   876         *
   877         *  This method unconditionally puts the specified `{@link Event}`
   878         *  `evt` into the log. The `{@link Types#ModuleId}` `mid` should be the
   879         *  module ID of the module which is putting the event.
   880         *
   881         *  @param(evt)     the Log event to put into the log
   882         *  @param(mid)     module ID of the module putting the event
   883         *  @param(a1)      value for first format conversion character
   884         *  @param(a2)      value for second format conversion character
   885         *  @param(a3)      value for third format conversion character
   886         *  @param(a4)      value for fourth format conversion character
   887         *
   888         *  @see #put8
   889         */
   890        @Macro Void put4(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
   891                         IArg a3, IArg a4);
   892
   893        /*!
   894         *  ======== put8 ========
   895         *  Unconditionally put the specified Log event and 8 arguments
   896         *
   897         *  @see #put4
   898         */
   899        @Macro Void put8(Log.Event evt, Types.ModuleId mid, IArg a1, IArg a2,
   900                         IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
   901
   902        /*!
   903         *  ======== write0 ========
   904         *  Generate a `Log` event with 0 arguments
   905         *
   906         *  @see #write8
   907         */
   908        @Macro Void write0(Event evt);
   909
   910        /*!
   911         *  ======== write1 ========
   912         *  Generate a `Log` event with 1 argument
   913         *
   914         *  @see #write8
   915         */
   916        @Macro Void write1(Event evt, IArg a1);
   917
   918        /*!
   919         *  ======== write2 ========
   920         *  Generate a `Log` event with 2 arguments
   921         *
   922         *  @see #write8
   923         */
   924        @Macro Void write2(Event evt, IArg a1, IArg a2);
   925
   926        /*!
   927         *  ======== write3 ========
   928         *  Generate a `Log` event with 3 arguments
   929         *
   930         *  @see #write8
   931         */
   932        @Macro Void write3(Event evt, IArg a1, IArg a2, IArg a3);
   933
   934        /*!
   935         *  ======== write4 ========
   936         *  Generate a `Log` event with 4 arguments
   937         *
   938         *  @see #write8
   939         */
   940        @Macro Void write4(Event evt, IArg a1, IArg a2, IArg a3, IArg a4);
   941
   942        /*!
   943         *  ======== write5 ========
   944         *  Generate a `Log` event with 5 arguments
   945         *
   946         *  @see #write8
   947         */
   948        @Macro Void write5(Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
   949
   950        /*!
   951         *  ======== write6 ========
   952         *  Generate a `Log` event with 6 arguments
   953         *
   954         *  @see #write8
   955         */
   956        @Macro Void write6(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
   957                            IArg a5, IArg a6);
   958
   959        /*!
   960         *  ======== write7 ========
   961         *  Generate a `Log` event with 7 arguments
   962         *
   963         *  @see #write8
   964         */
   965        @Macro Void write7(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
   966                            IArg a5, IArg a6, IArg a7);
   967
   968        /*!
   969         *  ======== write8 ========
   970         *  Generate a `Log` event with 8 arguments
   971         *
   972         *  If the mask in the specified `Log` event has any bit set which is
   973         *  also set in the current module's diagnostics mask, then this call to
   974         *  write will "raise" the given `Log` event.
   975         *
   976         *  @param(evt)     the `Log` event to write
   977         *  @param(a1)      value for first format conversion character
   978         *  @param(a2)      value for second format conversion character
   979         *  @param(a3)      value for third format conversion character
   980         *  @param(a4)      value for fourth format conversion character
   981         *  @param(a5)      value for fifth format conversion character
   982         *  @param(a6)      value for sixth format conversion character
   983         *  @param(a7)      value for seventh format conversion character
   984         *  @param(a8)      value for eighth format conversion character
   985         */
   986        @Macro Void write8(Event evt, IArg a1, IArg a2, IArg a3, IArg a4,
   987                            IArg a5, IArg a6, IArg a7, IArg a8);
   988
   989        /*!
   990         *  ======== doPrint ========
   991         *  Render an event as text via `{@link System#printf System_printf}`
   992         *
   993         *  This method is not gated and may make more than one call to
   994         *  `System_printf`.  This utility method is typically used within the
   995         *  implementation of a logger which initializes
   996         *  `{@link #EventRec Log_EventRec}` structures based on `Log` events
   997         *  produced by the application.
   998         *
   999         *  @param(evRec)   a non`NULL` pointer to an initialized `Log_EventRec`
  1000         *                  structure to be formated via
  1001         *                  `{@link System#printf System_printf}`.
  1002         */
  1003        Void doPrint(EventRec *evRec);
  1004
  1005        /*!
  1006         *  @_nodoc
  1007         *  ======== lookupEventMessage ========
  1008         *  Returns the format string for the event with the given id.
  1009         */
  1010        function lookupEventMessage(eventId);
  1011
  1012        /*!
  1013         *  @_nodoc
  1014         *  ======== getTargetArgSize ========
  1015         *  Returns the target size of a record argument in bytes (not MAUs).
  1016         */
  1017        function getTargetArgSize();
  1018
  1019        /*!
  1020         *  @_nodoc
  1021         *  ======== lookupEventName ========
  1022         */
  1023        function lookupEventName(eventId);
  1024
  1025        /*!
  1026         *  @_nodoc
  1027         *  ======== lookupModuleName ========
  1028         */
  1029        function lookupModuleName(modId);
  1030
  1031        /*!
  1032         *  @_nodoc
  1033         *  ======== getTargetEventRecSize ========
  1034         *  Returns the record size in bytes (not MAUs).
  1035         */
  1036        function getTargetEventRecSize();
  1037
  1038    internal:
  1039
  1040        /*
  1041         *  ======== idToInfo ========
  1042         *  Map event ID strings into a string of the form <eventName>::<eventMsg>
  1043         */
  1044        metaonly config String idToInfo[string] = [];
  1045
  1046    }
  1047    /*
  1048     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
  1049     */
  1050


module xdc.runtime.LoggerBuf

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== LoggerBuf.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== LoggerBuf ========
    19     *  A logger which stores `Log` events in a buffer.
    20     *
    21     *  This module provides a logger which captures `{@link Log}` events to a
    22     *  buffer in realtime. The `Log` events stored in the buffer are
    23     *  unformatted; `Log` event formatting is deferred until some client reads
    24     *  the raw event data from the buffer. You can use
    25     *  `{@link #flush LoggerBuf_flush()}` to process the `Log` events stored
    26     *  in the buffer and stream the formatted output to stdout
    27     *  (via `{@link System#printf}`).  Alternatively, you can read a raw event
    28     *  (via `{@link #getNextEntry}`) and send it to another client that
    29     *  has the resources to format the event for display.
    30     *
    31     *  The implementation of this logger is fast with minimal stack usage
    32     *  making it appropriate for a realtime application.
    33     *  This logger writes all `Log` events to a circular buffer.  As a
    34     *  result, the execution time of all `Log` methods bound to this type
    35     *  of logger are deterministic (and quite short) because there are no
    36     *  additional memory allocation calls after the circular buffer was
    37     *  allocated.
    38     *
    39     *  If this logger is used in a preemptive environment, then an appropriate
    40     *  gate must be assigned to the module. For example, if events are generated
    41     *  from an interrupt context, then a gate that disables interrupts
    42     *  must be used.
    43     *
    44     *  @p(code)
    45     *  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
    46     *  LoggerBuf.common$.gate = ...some gate instance...
    47     *  @p
    48     *
    49     *  If the buffer type is circular, the log buffer of size
    50     *  `{@link #numEntries}` contains the last `numEntries` of `Log` events. If
    51     *  the buffer type is fixed, the log buffer contains the first
    52     *  `numEntries` events.
    53     *
    54     *  LoggerBuf supports routing of 'STATUS' events (errors and warnings) to a
    55     *  separate ILogger instance. This is helpful in preserving these critical
    56     *  events, which may otherwise be overwritten by lower priority events. This
    57     *  feature is disabled by default. See {@link #statusLogger}.
    58     *
    59     *  LoggerBuf implements the {@link IFilterLogger} interface and
    60     *  optionally supports filtering of events based on their detail level. This
    61     *  feature is disabled by default. See {@link IFilterLogger}.
    62     *
    63     *  @a(Examples)
    64     *  Configuration example: The following XDC configuration statements
    65     *  create a logger instance, assign it as the default logger for all
    66     *  modules, and enable `USER1` logging in all modules of the package
    67     *  `my.pkg`. See the `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function
    68     *  for details on specifying the module names.
    69     *
    70     *  @p(code)
    71     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    72     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    73     *  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
    74     *
    75     *  LoggerBuf.enableFlush = true;
    76     *  var LoggerBufParams = new LoggerBuf.Params();
    77     *  LoggerBufParams.exitFlush = true;
    78     *  Defaults.common$.logger = LoggerBuf.create(LoggerBufParams);
    79     *  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
    80     *  @p
    81     */
    82
    83    @ModuleStartup      /* Initialize static instances */
    84    @InstanceFinalize   /* this mod has cleanup fxn when instances are deleted */
    85    @InstanceInitError  /* instance create can fail */
    86    @Gated
    87
    88    module LoggerBuf inherits IFilterLogger {
    89
    90        /*!
    91         *  ======== BufType ========
    92         *  Type of log buffer
    93         */
    94        enum BufType {
    95            BufType_CIRCULAR,  /*! The log buffer wraps, overwriting old entries */
    96            BufType_FIXED      /*! The log buffer halts collection when full */
    97        };
    98
    99        metaonly struct BasicView {
   100            String label;
   101            Int lastSerial;
   102            Int numEntries;
   103            String type;
   104            Bool enabledFlag;
   105        };
   106
   107        metaonly struct RecordView {
   108            Int     serial;
   109            Long    timestampRaw;
   110            String  modName;
   111            String  text;
   112            Int     eventId;
   113            String  eventName;
   114            IArg    arg0;
   115            IArg    arg1;
   116            IArg    arg2;
   117            IArg    arg3;
   118            IArg    arg4;
   119            IArg    arg5;
   120            IArg    arg6;
   121            IArg    arg7;
   122        }
   123
   124        /*!
   125         *  ======== rovViewInfo ========
   126         *  @_nodoc
   127         */
   128        @Facet
   129        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   130            xdc.rov.ViewInfo.create({
   131                viewMap: [
   132                    ['Basic',
   133                        {
   134                            type: xdc.rov.ViewInfo.INSTANCE,
   135                            viewInitFxn: 'viewInitBasic',
   136                            structName: 'BasicView'
   137                        }
   138                    ],
   139                    ['Records',
   140                        {
   141                            type: xdc.rov.ViewInfo.INSTANCE_DATA,
   142                            viewInitFxn: 'viewInitRecords',
   143                            structName: 'RecordView'
   144                        }
   145                    ]
   146                ]
   147            });
   148
   149        /*!
   150         *  ======== StopModeData ========
   151         *  Data added to the RTA MetaData file to support stop mode RTA
   152         */
   153        @XmlDtd metaonly struct StopModeData {
   154            String bufferSymbol;
   155            Int bufferSize;
   156        }
   157
   158        /*!
   159         *  ======== E_badLevel ========
   160         *  Error raised if get or setFilterLevel receives a bad level value
   161         */
   162        config Error.Id E_badLevel =
   163            {msg: "E_badLevel: Bad filter level value: %d"};
   164
   165        /*!
   166         *  ======== TimestampProxy ========
   167         *  User supplied time-stamp proxy
   168         *
   169         *  This proxy allows `LoggerBuf` to use a timestamp server different
   170         *  from the server used by `{@link xdc.runtime.Timestamp}`. However, if
   171         *  not supplied by a user, this proxy defaults to whichever timestamp
   172         *  server is used by `Timestamp`.
   173         */
   174        proxy TimestampProxy inherits ITimestampClient;
   175
   176        /*!
   177         *  ======== enableFlush ========
   178         *  Flush all logs at system exit
   179         */
   180        config Bool enableFlush = false;
   181
   182        /*!
   183         *  ======== statusLogger ========
   184         *  Route all 'STATUS' (error and warning) events to this logger.
   185         *
   186         *  If a statusLogger is specified, all LoggerBuf instances will check to
   187         *  determine if any of the events they receive are errors or warnings (if
   188         *  their diags mask includes the STATUS category), and will log these
   189         *  events to the statusLogger.
   190         *
   191         *  Error events are infrequent, but it's generally critical that they be
   192         *  seen. In a typical system, non-error events easily outnumber any error
   193         *  events, and the logger is likely to wrap, overwriting any error events.
   194         *  To protect these events from being overwritten and lost, they can be
   195         *  sent to their own separate logger to preserve them.
   196         *
   197         *  The default value is null, indicating that the STATUS events will just
   198         *  be logged by the logger they were sent to.
   199         */
   200        config ILogger.Handle statusLogger = null;
   201
   202        /*!
   203         *  ======== level1Mask ========
   204         *  Mask of diags categories whose initial filtering level is Diags.LEVEL1
   205         *
   206         *  See '{@link #level4Mask}' for details.
   207         */
   208        config Diags.Mask level1Mask = 0;
   209
   210        /*!
   211         *  ======== level2Mask ========
   212         *  Mask of diags categories whose initial filtering level is Diags.LEVEL2
   213         *
   214         *  See '{@link #level4Mask}' for details.
   215         */
   216        config Diags.Mask level2Mask = 0;
   217
   218        /*!
   219         *  ======== level3Mask ========
   220         *  Mask of diags categories whose initial filtering level is Diags.LEVEL3
   221         *
   222         *  See '{@link #level4Mask}' for details.
   223         */
   224        config Diags.Mask level3Mask = 0;
   225
   226        /*!
   227         *  ======== level4Mask ========
   228         *  Mask of diags categories whose initial filtering level is Diags.LEVEL4
   229         *
   230         *  If `{@link IFilterLogger.filterByLevel}` is `true`, then all
   231         *  `LoggerBuf` instances will filter incoming events based on their
   232         *  event level.
   233         *
   234         *  The `LoggerBuf` module allows for specifying a different filter level
   235         *  for every `Diags` bit. These filtering levels are module wide;
   236         *  `LoggerBuf` does not support specifying the levels on a per-instance
   237         *  basis.
   238         *
   239         *  The `{@link IFilterLogger.setFilterLevel}` function can be used to
   240         *  change the filtering levels at runtime.
   241         *
   242         *  The default filtering levels are assigned using the `level1Mask` -
   243         *  `level4Mask` config parameters. These are used to specify, for each of
   244         *  the four event levels, the set of bits which should filter at that
   245         *  level by default.
   246         *
   247         *  The default filtering configuration sets the filter level to
   248         *  `Diags.LEVEL4` for all logging-related diags bits so that all events
   249         *  are logged by default.
   250         */
   251        config Diags.Mask level4Mask = Diags.ALL_LOGGING;
   252
   253        /*!
   254         *  ======== flushAll ========
   255         *  Flush logs of all instances that set `exitFlush` to true
   256         *
   257         *  The user is responsible for making sure that no `LoggerBuf` instances
   258         *  are created or deleted during the execution of this function.
   259         */
   260        Void flushAll();
   261
   262        /*!
   263         *  ======== flushAllInternal ========
   264         *  @_nodoc
   265         */
   266        Void flushAllInternal(Int stat);
   267
   268        /*!
   269         *  ======== initDecoder ========
   270         * @_nodoc
   271         *  Initialize the LoggerBufDecoder for use in the LoggerBuf 'Records' ROV
   272         *  view.
   273         */
   274        function initDecoder();
   275
   276    instance:
   277        /*!
   278         *  ======== create ========
   279         *  Create a `LoggerBuf` logger
   280         *
   281         *  @see LoggerBuf#Params
   282         */
   283        create();
   284
   285        /*!
   286         *  ======== numEntries ========
   287         *  Number of entries in buffer
   288         *
   289         *  Each entry is large enough to store one `Log` event containing up to
   290         *  4 optional arguments.  Events containing more than 4 arguments (such
   291         *  as those from `{@link Log#write5}`) use 2 entries.
   292         *
   293         *  `numEntries` must be a power of 2.
   294         */
   295        config Int numEntries = 64;
   296
   297        /*!
   298         *  ======== bufType ========
   299         *  Log buffer type
   300         */
   301        config BufType bufType = BufType_CIRCULAR;
   302
   303        /*!
   304         *  ======== exitFlush ========
   305         *  Flush log at system exit
   306         *
   307         *  Only used when module parameter `{@link #enableFlush}` is `true`.
   308         */
   309        config Bool exitFlush = false;
   310
   311        /*!
   312         *  ======== bufSection ========
   313         *  Section name for the buffer managed by the static instance.
   314         *
   315         *  The default section is the 'dataSection' in the platform.
   316         */
   317        metaonly config String bufSection = null;
   318
   319        /*!
   320         *  ======== bufHeap ========
   321         *  The heap that contains the `Log` buffer for dynamic instances.
   322         *
   323         *  The default value `null` means the buffer will be allocated from
   324         *  the `{@link Memory#defaultHeapInstance}` heap.
   325         */
   326        config IHeap.Handle bufHeap = null;
   327
   328        /*!
   329         *  ======== reset ========
   330         *  Reset a log to empty state and enable it
   331         *
   332         *  @a(WARNING)  This method is not synchronized with other instance
   333         *  methods and, as a result, it must never be called when there is a
   334         *  chance that another instance method is currently in operation or
   335         *  when another method on this instance may preempt this call.
   336         */
   337        Void reset();
   338
   339        /*!
   340         *  ======== flush ========
   341         *  Read, clear, and output the contents of the log
   342         *
   343         *  This method reads, clears, and "prints" each `Log` event (via
   344         *  `{@link System#printf}`) in the log.
   345         */
   346        Void flush();
   347
   348        /*!
   349         *  ======== getNextEntry ========
   350         *  Fills the passed `{@link Log#EventRec}` with the next entry in the log.
   351         *
   352         *  This function is used to read and clear `Log` events from the
   353         *  buffer maintained by the `LoggerBuf` instance. The `Log` event can
   354         *  then be transmitted and displayed on a host.
   355         *
   356         *  A read pointer is maintained in the `LoggerBuf` instance and
   357         *  points to the next record to read.  Entries are not necessarily
   358         *  returned in chronological order, since buffers of type
   359         *  `{@link #BufType_CIRCULAR}` can wrap.
   360         *
   361         *  @param(evtRec) pointer to a supplied `EventRec` object where the next
   362         *                 entry in the log is copied to
   363         *
   364         *  @a(returns)
   365         *  This function reports the number of entries actually read. The only
   366         *  values that can be returned are:
   367         *  @p(blist)
   368         *      - 0   no more entries to read
   369         *      - 1 or 2 read a complete entry written by `write4` or `write8`
   370         *      - -1  cleared an incomplete/overwritten entry, more entries to read
   371         */
   372        Int getNextEntry(Log.EventRec *evtRec);
   373
   374    internal:
   375
   376        Bool filterOutEvent(Diags.Mask mask);
   377
   378        const Int8 FULL = -1;
   379        const Int8 WRAP = 0;
   380
   381        const Int8 NEXT = 1;
   382
   383        struct Entry {
   384            Types.Timestamp64 tstamp;
   385            Bits32 serial;
   386            Types.Event evt;
   387            IArg arg1;
   388            IArg arg2;
   389            IArg arg3;
   390            IArg arg4;
   391        };
   392
   393        struct Module_State {
   394            Diags.Mask level1;
   395            Diags.Mask level2;
   396            Diags.Mask level3;
   397        };
   398
   399        struct Instance_State {
   400            IHeap.Handle bufHeap;
   401            Entry entryArr[];
   402            Entry *curEntry;
   403            Entry *endEntry;
   404            Entry *readEntry;
   405            Bits32 serial;
   406            Int16 numEntries;
   407            Int8 advance;
   408            Bool enabled;
   409            Bool flush;
   410        };
   411
   412    }
   413    /*
   414     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   415     */
   416


module xdc.runtime.LoggerSys

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== LoggerSys.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== LoggerSys ========
    19     *  A logger which routes events to the `System_printf` function.
    20     *
    21     *  This logger processes log events as they are generated and routes
    22     *  them through the `{@link System#printf System_printf()}` function.
    23     *  The final disposition of the log event is dependent on which system
    24     *  provider has been assigned to the
    25     *  `{@link System#SupportProxy System.SupportProxy}` configuration parameter.
    26     *
    27     *  Note that the log events are processed within the runtime context
    28     *  of the `{@link Log Log_write()}` or `{@link Log Log_print()}` function
    29     *  that generated the event. It is important to account for the processing
    30     *  overhead and stack usage imposed on the runtime context. The cost of
    31     *  this processing is defined by the implementation of the system provider.
    32     *
    33     *  @a(Examples)
    34     *  Configuration example: The following XDC configuration statements
    35     *  create a logger instance, assign it as the default logger for all
    36     *  modules, and enable `USER1` logging in all modules of the package
    37     *  `my.pkg`. See the `{@link Diags#setMaskMeta Diags.setMaskMeta()}` function
    38     *  for details on specifying the module names.
    39     *
    40     *  @p(code)
    41     *  var Defaults = xdc.useModule('xdc.runtime.Defaults');
    42     *  var Diags = xdc.useModule('xdc.runtime.Diags');
    43     *  var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
    44     *
    45     *  var LoggerSysParams = new LoggerSys.Params();
    46     *  Defaults.common$.logger = LoggerSys.create(LoggerSysParams);
    47     *  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);
    48     *  @p
    49     */
    50
    51    module LoggerSys inherits ILogger {
    52
    53        /*!
    54         *  ======== ITimestampProxy ========
    55         *  User supplied time-stamp proxy
    56         *
    57         *  This proxy allows `LoggerSys` to use a timestamp server different
    58         *  from the server used by `{@link xdc.runtime.Timestamp}`. However, if
    59         *  not supplied by a user, this proxy defaults to whichever timestamp
    60         *  server is used by `Timestamp`.
    61         */
    62        proxy TimestampProxy inherits ITimestampClient;
    63
    64    instance:
    65
    66        /*!
    67         *  ======== create ========
    68         *  Create a `LoggerSys` logger
    69         *
    70         *  The logger instance will route all log events it receives to
    71         *  the {@link System#printf} function.
    72         */
    73        create();
    74
    75    internal:
    76
    77        struct Instance_State {
    78            Bool enabled;
    79        };
    80    }
    81    /*
    82     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    83     */
    84


module xdc.runtime.Main

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Main.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Main ========
    21     *  Configuration "stand-in" for application code.
    22     *
    23     *  This module is used to enable "module" configuration of application code
    24     *  that is not part of a module.  Configuration of this `Main` module is
    25     *  used for all code not in a module.
    26     *
    27     *  For example, an `ILogger` "service provider" for all code that is not in
    28     *  a RTSC module can be configured by setting this module's `logger`;  when
    29     *  code that is not in a module calls `Log_print()`, for example, this
    30     *  module's `ILogger` handles the event.
    31     *
    32     *  Since this module is "gated", the user can also assign a gate to this
    33     *  module for use by any code that is not in a module.  This gate can be used
    34     *  to serialize access to global data by multiple threads in the system.
    35     *  @p(code)
    36     *      #include <xdc/runtime/Main.h>
    37     *      #include <xdc/runtime/Gate.h>
    38     *          :
    39     *      int global = 0;
    40     *      int main() {
    41     *          :       // create a bunch of threads
    42     *      }
    43     *
    44     *      void thread() {
    45     *          IArg key = Gate_enterModule();  // enter critical section
    46     *          global++;                       // safely update global data
    47     *          Gate_leaveModule(key);          // leave critical section
    48     *      }
    49     *  @p
    50     */
    51    @Gated module Main {
    52
    53    };
    54
    55    /*
    56     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    57     */
    58


module xdc.runtime.Memory

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Memory.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== Memory ========
    19     *  Static and run-time memory manager
    20     *
    21     *  All memory allocations are executed via `staticPlace()` at the
    22     *  config time or through `Memory_alloc()` (or `Memory_calloc()` or
    23     *  `Memory_valloc()`) at run-time.
    24     *
    25     *  The actual memory management is performed by modules that
    26     *  implement `{@link xdc.runtime.IHeap}`.  Heap instances are created
    27     *  statically or dynamically via the heap specific create functions and
    28     *  these instances are then passed as input parameters to the `Memory`
    29     *  calls with `{@link xdc.runtime.IHeap#Handle}` parameters.
    30     */
    31    module Memory {
    32
    33        /*!
    34         *  ======== Q_BLOCKING ========
    35         *  Blocking quality
    36         *
    37         *  `{@link xdc.runtime.IHeap}`s with this "quality" may cause the
    38         *  calling thread to block; i.e., suspend execution until another thread
    39         *  leaves the gate.
    40         */
    41        const Int Q_BLOCKING = 1;
    42
    43        /*!
    44         *  ======== Size ========
    45         *  Type to be used to specify heap buffer sizes
    46         */
    47        typedef UArg Size;
    48
    49        /*!
    50         *  ======== Stats ========
    51         *  Memory heap statistics
    52         *
    53         *  This structure defines generic statistics that must be supplied
    54         *  by each module that implements the `{@link xdc.runtime.IHeap}`
    55         *  interface.
    56         *
    57         *  @field(totalSize)         total size (in MADUs) of heap.
    58         *  @field(totalFreeSize)     current size (in MADUs) of free memory in
    59         *                            the heap
    60         *  @field(largestFreeSize)   current largest contiguous free block
    61         *                            (in MADUs)
    62         */
    63        struct Stats {
    64            Size totalSize;
    65            Size totalFreeSize;
    66            Size largestFreeSize;
    67         }
    68
    69        /*! @_nodoc */
    70        @XmlDtd
    71        metaonly struct Module_View {
    72            SizeT maxDefaultTypeAlignment;
    73        };
    74
    75        /*!
    76         *  ======== defaultHeapInstance ========
    77         *  The default heap.
    78         *
    79         *  If no heap is specified in the `Memory` module's methods (i.e.
    80         *  heap == `NULL`) `defaultHeapInstance` is used. If
    81         *  `defaultHeapInstance` is not set (or set to `null`), a
    82         *  `{@link xdc.runtime.HeapStd}` heap instance is created and assigned
    83         *  to this configuration parameter. The size of the heap is determined
    84         *  by the `{@link #defaultHeapSize}` parameter.
    85         *
    86         *  By default, all modules are configured with a `null` instance heap.
    87         *  Instances created by modules with a `null` instance heap are
    88         *  allocated from the `defaultHeapInstance` heap.
    89         */
    90        config IHeap.Handle defaultHeapInstance;
    91
    92        /*!
    93         *  ======== defaultHeapSize ========
    94         *  The size (in target MADUs) of the `defaultHeapInstance`.
    95         *
    96         *  This parameters is used when the `{@link #defaultHeapInstance}`
    97         *  is not configured.
    98         */
    99        metaonly config int defaultHeapSize = 0x1000;
   100
   101        /*!
   102         *  ======== alloc ========
   103         *  Allocate a block of memory from a heap.
   104         *
   105         *  @param(heap)    heap from which the memory is allocated
   106         *
   107         *                  The `heap` is created by a module that implements
   108         *                  the `{@link xdc.runtime.IHeap}` interface.
   109         *                  If `heap` is `NULL`, the
   110         *                  `{@link #defaultHeapInstance}` is used.
   111         *
   112         *  @param(size)    requested memory block size (in MADUs)
   113         *  @param(align)   alignment (in MADUs) of the block of memory
   114         *
   115         *                  A value of 0 denotes maximum default type alignment.
   116         *
   117         *  @param(eb)      pointer to error block
   118         *
   119         *  @a(returns)
   120         *  If the allocation was successful, `Memory_alloc()` returns non-`NULL`
   121         *  pointer to the allocated and uninitialized block; otherwise it returns
   122         *  `NULL` and the error block will indicate the cause of the error.
   123         */
   124        Ptr alloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb);
   125
   126        /*!
   127         *  ======== calloc ========
   128         *  Allocate a block of memory from a heap and zero out the contents.
   129         *
   130         *  @param(heap)    heap from which the memory is allocated
   131         *
   132         *                  The `heap` is created by a module that implements
   133         *                  the `{@link xdc.runtime.IHeap}` interface.
   134         *                  If `heap` is `NULL`, the
   135         *                  `{@link #defaultHeapInstance}` is used.
   136         *
   137         *  @param(size)    requested memory block size (in MADUs)
   138         *  @param(align)   alignment (in MADUs) of the block of memory
   139         *
   140         *                  A value of 0 denotes maximum default type alignment.
   141         *
   142         *  @param(eb)      pointer to error block
   143         *
   144         *  @a(returns)
   145         *  If the allocation was successful, `Memory_calloc()` returns non-`NULL`
   146         *  pointer to the allocated and initialized block; otherwise it returns
   147         *  `NULL` and the error block will indicate the cause of the error.
   148         */
   149        Ptr calloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb);
   150
   151        /*!
   152         *  ======== free ========
   153         *  Frees the space if the heap manager offers such functionality.
   154         *
   155         *  @param(heap)   heap that the block of memory will be freed back to.
   156         *
   157         *                 The `heap` is created by a module that implements
   158         *                 the `{@link xdc.runtime.IHeap}` interface.
   159         *                 If `heap` is `NULL`, the
   160         *                 `{@link #defaultHeapInstance}` is used.
   161         *
   162         *  @param(block)  block of memory to free back to the heap
   163         *  @param(size)   size (in MADUs) of the block of memory to free.
   164         *
   165         */
   166        Void free(IHeap.Handle heap, Ptr block, SizeT size);
   167
   168        /*!
   169         *  ======== getStats ========
   170         *  Obtain statistics from a heap.
   171         *
   172         *  @param(heap)    the heap to get the statistics from
   173         *
   174         *                  The `heap` is created by a module that implements
   175         *                  the `{@link xdc.runtime.IHeap}` interface.
   176         *                  If `heap` is `NULL`, the
   177         *                  `{@link #defaultHeapInstance}` is used.
   178         *
   179         *  @param(stats)   the output buffer for the returned statistics
   180         */
   181        Void getStats(IHeap.Handle heap, Stats *stats);
   182
   183        /*!
   184         *  ======== query ========
   185         *  Test for a particular `{@link xdc.runtime.IHeap}` quality.
   186         *
   187         *  There currently is only one quality, namely `{@link #Q_BLOCKING}`.
   188         *
   189         *  @param(heap)    the heap to query
   190         *
   191         *                  The `heap` is created by a module that implements
   192         *                  the `{@link xdc.runtime.IHeap}` interface.  If `heap`
   193         *                  is `NULL`, the `{@link #defaultHeapInstance}`
   194         *                  is queried
   195         *
   196         *  @param(qual)    quality to test
   197         *
   198         *                   For example: `{@link #Q_BLOCKING}`.
   199         *
   200         *  @a(returns)
   201         *  If `heap` has the `qual` quality, this method returns `TRUE`,
   202         *  otherwise it returns `FALSE`.
   203         */
   204        Bool query(IHeap.Handle heap, Int qual);
   205
   206        /*!
   207         *  ======== getMaxDefaultTypeAlignMeta ========
   208         *  Return the largest alignment required by the target
   209         *
   210         *  This method scans the standard base types supported by the current
   211         *  configuration's target
   212         *  (`{@link xdc.cfg.Program#build Program.build.target}`) and returns
   213         *  the largest alignment required for these types.
   214         *
   215         *  @a(returns)     Returns target-specific alignment in MADUs.
   216         *
   217         *  @see xdc.bld.ITarget#stdTypes
   218         */
   219        metaonly SizeT getMaxDefaultTypeAlignMeta();
   220
   221        /*!
   222         *  ======== getMaxDefaultTypeAlign ========
   223         *  Return the largest alignment required by the target
   224         *
   225         *  `getMaxDefaultTypeAlign` returns the largest alignment
   226         *   required for all the standard base types supported by the current
   227         *  configuration's target
   228         *  (`{@link xdc.cfg.Program#build Program.build.target}`)
   229         *
   230         *  This is the runtime version of the
   231         *  `{@link #getMaxDefaultTypeAlignMeta}` function.
   232         *
   233         *  @a(returns)     Returns target-specific alignment in MADUs.
   234         *
   235         *  @see #getMaxDefaultTypeAlignMeta
   236         */
   237        SizeT getMaxDefaultTypeAlign();
   238
   239        /*!
   240         *  ======== staticPlace ========
   241         *  Statically places buffers.
   242         *
   243         *  This function places the object specified by `obj` into the specified
   244         *  memory section. The section string is a target-specific name that is
   245         *  interpreted by the underlying target tool-chain.  In the case of TI
   246         *  tool-chains, this section can be a subsection (e.g.
   247         *  ".data:someSection").
   248         *
   249         *  The amount of memory that is created for `obj` is dependent on its
   250         *  size and the value of the property `length`. The length (number
   251         *  of elements in an array) is set before the `staticPlace()` is called.
   252         *  For example, setting `obj.length = 5;` before calling `staticPlace()`,
   253         *  will create `5 * sizeof (obj)` MADUs of memory.
   254         *
   255         *  If 0 is specified for the alignment, the allocated buffer is aligned
   256         *  as determined by the target toolchain. For instance, if `obj` is an
   257         *  array of structs that have only 16-bit integers, the alignment would
   258         *  be on a 16-bit boundary.
   259         *
   260         *  All non-zero alignments must be a power of 2. Not all targets support
   261         *  directives that allow one to specify alignment. The readonly config
   262         *  parameter
   263         *  `{@link xdc.cfg.Program#build Program.build.target.alignDirectiveSupported}`
   264         *  can be used to determine if the target supports alignment directives.
   265         *
   266         *  @param(obj)     object to place
   267         *
   268         *      This object always has the `length` property; `obj.length`
   269         *      determines the size of the allocated buffer for `obj`
   270         *
   271         *  @param(align)   the alignment required by `obj`
   272         *
   273         *  @param(section) section name to contain `obj`
   274         *
   275         *      This parameter names the section where `obj` will be placed.  If
   276         *      this parameter is `null`, no explicit placement is done.
   277         *
   278         *  @a(returns)
   279         *  Returns `false` if the alignment request cannot be honored. The `obj`
   280         *  is still placed regardless of the return code.
   281         */
   282        metaonly Bool staticPlace(any obj, SizeT align, String section);
   283
   284        /*!
   285         *  ======== valloc ========
   286         *  Allocate a block of memory from a heap and initialize the contents
   287         *  to the value specified.
   288         *
   289         *  @param(heap)    heap from which the memory is allocated
   290         *
   291         *                  The `heap` is created by a module that implements
   292         *                  the `{@link xdc.runtime.IHeap}` interface.
   293         *                  If `heap` is `NULL`, the
   294         *                  `{@link #defaultHeapInstance}` is used.
   295         *
   296         *  @param(size)    requested memory block size (in MADUs)
   297         *  @param(align)   alignment (in MADUs) of the block of memory
   298         *
   299         *                  A value of 0 denotes maximum default type alignment.
   300         *
   301         *  @param(value)   value to initialize the contents of the block
   302         *  @param(eb)      pointer to error block
   303         *
   304         *  @a(returns)
   305         *  If the allocation was successful, `Memory_valloc()` returns non-`NULL`
   306         *  pointer to the allocated and initialized block; otherwise it returns
   307         *  `NULL` and the error block will indicate the cause of the error.
   308         */
   309        Ptr valloc(IHeap.Handle heap, SizeT size, SizeT align, Char value,
   310                   Error.Block *eb);
   311
   312    internal:
   313
   314        proxy HeapProxy inherits IHeap;
   315
   316        struct Module_State {
   317            SizeT maxDefaultTypeAlign;
   318        }
   319    }
   320    /*
   321     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   322     */
   323


package xdc.runtime

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*!
    14     *  ======== xdc.runtime ========
    15     *  Basic runtime support for RTSC programs
    16     *
    17     *  The modules and interfaces in the `xdc.runtime` package form the "core"
    18     *  RTSC target runtime support library which provides basic system services
    19     *  required by virtually all applications.
    20     *
    21     *  Since this package's services are intended to be available to any
    22     *  C/C++ client, this package does not contain any pre-compiled libraries.
    23     *  Instead, this package provides complete sources which are built and
    24     *  supplied by a target-specific package named by the
    25     *  `{@link xdc.bld.ITarget#rts rts}` parameter of the target used to build
    26     *  the client sources.  This "indirection" make it possible for new targets
    27     *  to be added by interested parties whithout ever having to update this
    28     *  package.
    29     *
    30     *  The functionality provided by this package can be roughly partitioned
    31     *  into four categories:
    32     *  @p(nlist)
    33     *      - Diagnostics and Logs
    34     *      - Memory Management
    35     *      - Concurrency Support
    36     *      - Startup and Shutdown
    37     *  @p
    38     *  @a(Diagnostics and Logs)
    39     *  This package provides for diagnostics with a set of modules that operate
    40     *  together to configure and implement diagnostics.
    41     *
    42     *  The modules can be partitioned into three groups: modules that
    43     *  generate events, a module that allows precise control over when
    44     *  (or if) various events are generated, and modules that manage the
    45     *  output or display of the events.
    46     *
    47     *  `{@link Assert}`, `{@link Error}`, and `{@link Log}` provide methods that
    48     *  are added to source code and generate events. The `{@link Diags}` module
    49     *  provides both configuration and runtime methods to selectively enable or
    50     *  disable different types of events on a per module basis. Finally,
    51     *  `{@link LoggerBuf}` and `{@link LoggerSys}` are simple alternative
    52     *  implementations of the `{@link ILogger}` event "handler" interface. You
    53     *  can provide more sophisticated or platform-specific
    54     *  implementations of `ILogger` without making any changes to code that
    55     *  uses `Assert`, `Log`, `Error`, or `Diags`.
    56     *
    57     *  The diagnostics and logger modules include the following:
    58     *  @p(blist)
    59     *  - `{@link Assert}` - Add integrity checks to the code.
    60     *  - `{@link Diags}` - Manage a module's diagnostics mask.
    61     *  - `{@link Error}` - Raise error events.
    62     *  - `{@link Log}` - Generate log events in realtime.
    63     *  - `{@link LoggerBuf}` - A logger using a buffer for log events.
    64     *  - `{@link LoggerSys}` - A logger using printf for log events.
    65     *  - `{@link Types}` - Define diagnostics configuration parameters.
    66     *  - `{@link Timestamp}` - Simple timestamp service
    67     *  @p
    68     *
    69     *  @a(Memory Management)
    70     *  The memory management modules include the following:
    71     *  @p(blist)
    72     *  - `{@link Memory}` -  module used by clients to allocate and free memory
    73     *  - `{@link HeapMin}` - Deterministic implementation that minimizes code
    74     *                        size footprint by not supporting reuse of allocated
    75     *                        memory.
    76      *  - `{@link HeapStd}` - Implementation that builds atop ANSI C `malloc()`
    77     *                        and `free()`
    78     *  @p
    79     *
    80     *  @a(Concurrency Support)
    81     *  The concurency support modules include the following:
    82     *  @p(blist)
    83     *  - `{@link Gate}` -  module used by clients to serialize access to
    84     *                      shared data structures
    85     *  - `{@link GateNull}` - "null" implementation for applications that
    86     *                      don't need serialization; e.g., single threaded
    87     *                      applications
    88     *  @p
    89     *
    90     *  @a(Startup and Shutdown)
    91     *  The system startup and shutdown support modules include:
    92     *  @p(blist)
    93     *  - `{@link Reset}`   - Manages platform-specific startup initialization
    94     *                        before `main()` is called
    95     *  - `{@link Startup}` - Manages "portable" startup initialization before
    96     *                        `main()` is called
    97     *  - `{@link System}`  - In addition to other basic services (such as
    98     *                        `printf`), this module provides an `atexit`
    99     *                        capability that allows modules to cleanly exit
   100     *                        during normal application terminiation.
   101     *  - `{@link SysMin}`  - Minimal implementation of `{@link ISystemSupport}`,
   102     *                        required by the `System` module, suitable for
   103     *                        deeply embedded applications.
   104     *  - `{@link SysStd}`  - Implementation of `{@link ISystemSupport}`
   105     *                        that relies on ANSI C Standard I/O Library
   106     *                        functions.
   107     *  @p
   108     */
   109    package xdc.runtime [2,1,0] {
   110        interface IModule, IInstance;
   111        interface IHeap, ILogger, IFilterLogger;
   112        interface ISystemSupport;
   113        interface IGateProvider;
   114        interface ITimestampClient, ITimestampProvider;
   115        module Assert;
   116        module Core;
   117        module Defaults;
   118        module Diags;
   119        module Error;
   120        module Gate, GateNull;
   121        module Log, LoggerBuf, LoggerSys;
   122        module Main;
   123        module Memory, HeapMin, HeapStd;
   124        module Registry;
   125        module Rta;
   126        module Startup, Reset;
   127        module System, SysStd, SysMin;
   128        module Text;
   129        module Timestamp, TimestampNull, TimestampStd;
   130        module Types;
   131    }
   132    /*
   133     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   134     */
   135


module xdc.runtime.Registry

     1    /*!
     2     *  ======== Registry ========
     3     *  Register modules that are not statically configured
     4     *
     5     *  This module provides a mechanism by which legacy C code can have its own
     6     *  module logging support, including having a name and its own diags mask.
     7     *
     8     *  Without the `Registry`, all logging done by legacy C code is handled by the
     9     *  `xdc.runtime.Main` module. This means that all `{@link Log}` events will
    10     *  be marked as coming from "`xdc.runtime.Main`", and there is only a single
    11     *  diagnostics mask for the runtime control of logging across all legacy C
    12     *  code. The `Registry` module allows legacy C code to have the same granular
    13     *  control over logging as statically defined RTSC modules.
    14     *
    15     *  To use the `Registry` module, legacy code must define the symbol
    16     *  `Registry_CURDESC` to be the name of an externally declared
    17     *  `Registery_Desc` structure.  This symbol must be defined before the
    18     *  inclusion of any `xdc/runtime` header files. If any `xdc/runtime` header
    19     *  files are included before the definition of this symbol, the `Registry`
    20     *  module may not function properly.
    21     *
    22     *  Note: by defining this symbol on the compile line, rather than in the
    23     *  file, one can easily compile code to be used in one of two environments:
    24     *  @p(nlist)
    25     *    - a fixed configuration environment where modules are registered
    26     *      via `{@link #addModule Registry_addModule()}`, or
    27     *
    28     *    - a "normal" configurable environment in which this code is
    29     *      assumed to be part of the `{@link Main}` module.
    30     *  @p
    31     *  The `Registry_Desc` structure must then be registered by calling
    32     *  `{@link #addModule Registry_addModule()}`. The structure is typically
    33     *  registered and initialized within `main()`.
    34     *
    35     *  For example:
    36     *
    37     *  @p(code)
    38     *  //Define the required symbol, Registry_CURDESC, to this file's
    39     *  //Registry_Desc object
    40     *  #define Registry_CURDESC    mainDesc
    41     *  #include <xdc/runtime/Registry.h>
    42     *
    43     *  //Declare the Registry_Desc object, the name is unimportant
    44     *  Registry_Desc mainDesc;
    45     *
    46     *  Int main(Int argc, String argv[]) {
    47     *
    48     *  //Register this file as a module "main"
    49     *  Registry_addModule(&mainDesc, "main");
    50     *  @p
    51     *
    52     *  Once registered, the legacy code may call `{@link Log}` APIs without any
    53     *  other change and the formatted `Log` events will show as coming from the
    54     *  registered modules. Also, the logging by the legacy code is now filtered
    55     *  by its own diagnostic mask. The bits of this mask can be set using
    56     *  `{@link Diags#setMask Diags_setMask}`.
    57     *
    58     *  Continuing the previous example:
    59     *  @p(code)
    60     *  //Initialize the legacy code's diags mask to enable USER1.
    61     *  Diags_setMask("main=1");
    62     *  @p
    63     *
    64     *  All events logged registered modules will be sent to the logger configured
    65     *  for the `Registry` module. For example, to configure the logger for use by
    66     *  all modules managed by `Registry`:
    67     *  @p(code)
    68     *  Registry.common$.logger = LoggerBuf.create();
    69     *  @p
    70     *
    71     *  Since the registered modules are not known until runtime, it is not
    72     *  possible to statically configure the diagnostics masks for individual
    73     *  registered modules. However, it is possible to configure diagnostics
    74     *  categories to be permanently off or on for ALL registered modules. This
    75     *  is done by configuring the diagnostic mask for the `Registry` module.
    76     *  Diagnostic categories set to `{@link Diags#ALWAYS_OFF Diags.ALWAYS_OFF}`
    77     *  will be permanently off for all `Registry` modules. Categories set to
    78     *  `{@link Diags#ALWAYS_ON Diags.ALWAYS_ON}` will be
    79     *  permanently on for all modules managed by `Registry`.
    80     *
    81     *  In order to enable runtime configuration of individual `Registry` module
    82     *  masks, all relevant diagnostic categories must be set to
    83     *  `{@link Diags#RUNTIME_OFF Diags.RUNTIME_OFF}` or
    84     *  `{@link Diags#RUNTIME_ON Diags.RUNTIME_ON}` in the `Registry` module's
    85     *  mask.
    86     */
    87    @CustomHeader
    88    module Registry
    89    {
    90        /*!
    91         *  ======== RegisteredModuleView ========
    92         *  @_nodoc
    93         *  View element for the 'Registered Modules' ROV view.
    94         */
    95        metaonly struct RegisteredModuleView {
    96            String modName;
    97            Int id;
    98            String mask;
    99            Ptr descAddr;
   100        }
   101
   102        /*!
   103         *  ======== rovViewInfo ========
   104         *  @_nodoc
   105         */
   106        @Facet
   107        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   108            xdc.rov.ViewInfo.create({
   109                viewMap: [
   110                    ['Registered Modules',
   111                        {
   112                            type: xdc.rov.ViewInfo.MODULE_DATA,
   113                            viewInitFxn: 'viewInitRegisteredModules',
   114                            structName: 'RegisteredModuleView'
   115                        }
   116                    ]
   117                ]
   118            });
   119
   120        /*!
   121         *  ======== Result ========
   122         *  Status codes
   123         */
   124        enum Result {
   125            SUCCESS,        /*! The module was added successfully */
   126            ALLOC_FAILED,   /*! reserved */
   127            ALREADY_ADDED,  /*! The module has already been added  or another
   128                             *  module with the same name is present
   129                             */
   130            ALL_IDS_USED    /*! No more module ids available for new modules */
   131        };
   132
   133        /*!
   134         *  ======== RegDesc ========
   135         *  Registry module descriptor
   136         */
   137        typedef Types.RegDesc Desc;
   138
   139        /*!
   140         *  ======== addModule ========
   141         *  Add a runtime module to the registry with the specified name
   142         *
   143         *  The `desc` parameter and the `modName` string provided must both be
   144         *  permanent since the `Registry` will maintain references to both of
   145         *  these.
   146         *
   147         *  @param(desc)    non-`NULL` pointer to a `{#Desc Registry_Desc}`
   148         *                  structure.
   149         *  @param(modName) non-`NULL` string name of the module being registered.
   150         *
   151         *  @a(returns)
   152         *  `Registry_addModule` returns one of the following
   153         *  `{@link #Result Result}` status values indicating success or the
   154         *  cause of failure:
   155         *  @p(blist)
   156         *  - `{@link #SUCCESS SUCCESS}`
   157         *  - `{@link #ALREADY_ADDED ALREADY_ADDED}`
   158         *  - `{@link #ALL_IDS_USED ALL_IDS_USED}`  There are a total of 16,384 - 1
   159         *    module ids available for use by `Registry`.
   160         *  @p
   161         */
   162        Result addModule(Desc *desc, String modName);
   163
   164        /*!
   165         *  ======== findByName ========
   166         *  Find the registered module with the given name
   167         *
   168         *  @param(modName) non-`NULL` string name of a registered module
   169         *
   170         *  @a(returns)
   171         *  If the name `modName` is registered via
   172         *  `{@link #addModule Registry_addModule()}`, this function
   173         *  returns the pointer to the registered `Registry_Desc` structure;
   174         *  otherwise it returns `NULL`.
   175         */
   176        Desc *findByName(String modName);
   177
   178        /*!
   179         *  ======== findByNamePattern ========
   180         *  @_nodoc
   181         *  Find all registered modules matching the specified pattern.
   182         *
   183         *  This API is intended for use by Diags_setMask.
   184         *
   185         *  The name pattern can be an exact module name or it can contain '%'
   186         *  as a wildcard. The `len` parameter is the string length of the pattern.
   187         *
   188         *  This function returns one module at a time, but can be called
   189         *  repeatedly to find all modules matching the pattern. On the first
   190         *  call, pass `NULL` as the `prev` parameter. In all following calls,
   191         *  pass the last returned descriptor. This function returns `NULL` when
   192         *  it can't find any more modules matching the name pattern.
   193         */
   194        Desc *findByNamePattern(String namePat, Int len, Desc *prev);
   195
   196        /*!
   197         *  ======== findById ========
   198         *  Find registered module's descriptor from it's module ID
   199         *
   200         *  @param(mid) any module id
   201         *
   202         *  @a(returns)
   203         *  If the ID `mid` is registered via
   204         *  `{@link #addModule Registry_addModule()}`, this function
   205         *  returns the pointer to the registered `Registry_Desc` structure;
   206         *  otherwise it returns `NULL`.
   207         */
   208        Desc *findById(Types.ModuleId mid);
   209
   210        /*!
   211         *  ======== getMask ========
   212         *  Get the specified module's diagnostic mask
   213         *
   214         *  @param(modName) non-`NULL` string name of a registered module
   215         *  @param(mask)    non-`NULL` pointer to a mask to be initialized
   216         *                  to the the current state of the diagnostics mask
   217         *                  associated with `modName`
   218         *
   219         *  @a(returns)
   220         *  The function returns `TRUE` if `name` identifies a registered module;
   221         *  otherwise, it return `FALSE`.
   222         */
   223        Bool getMask(String name, Types.DiagsMask *mask);
   224
   225        /*!
   226         *  ======== isMember ========
   227         *  Determines if the specified module ID belongs to a registered module
   228         *
   229         *  @param(mid) any module id
   230         *
   231         *  @a(returns)
   232         *  This function returns `TRUE` if and only if the specified module id
   233         *  is a valid `Registry` module id. It does not search registered
   234         *  module ids, but simply checks if the id is within the range of valid
   235         *  `Registry` module ids.
   236         */
   237        Bool isMember(Types.ModuleId mid);
   238
   239        /*!
   240         *  ======== getNextModule ========
   241         *  Scan the current list of registered modules
   242         *
   243         *  This function used to scan the list of all `Registry_Desc` structures
   244         *  currently being managed by the `Registry` module.
   245         *
   246         *  @param(desc)    optionally `NULL` pointer to a `Registry_Desc`
   247         *                  structure.  If `desc` is `NULL`, a pointer to the
   248         *                  first structure is returned.  If `desc` is non-`NULL`
   249         *                  and equal to a previous return value of this function,
   250         *                  a pointer to the "next" `Registry_Desc` structure
   251         *                  is returned.
   252         *
   253         *  @a(returns)
   254         *  This function returns a non-`NULL` pointer to one of the
   255         *  `Registry_Desc` structures added via `Registry_Desc` structures or
   256         *  `NULL` in the case that
   257         *  @p(blist)
   258         *      - there are no more module's in the list after `desc`, or
   259         *      - there are no modules registered
   260         *  @p
   261         */
   262        Desc *getNextModule(Desc *desc);
   263
   264        /*!
   265         *  ======== getModuleName ========
   266         *  Get the module name associated with a specified module descriptor
   267         *
   268         *  @param(desc)    non-`NULL` pointer to a `{#Desc Registry_Desc}`
   269         *                  structure.
   270         *
   271         *  @a(returns)
   272         *  If the specified module descriptor has been initialized via a
   273         *  successful call to `{@link #addModule Registry_addModule()}`, this
   274         *  function returns the module name passed `Registry_addModule()`;
   275         *  otherwise, its return value is indeterminate.
   276         */
   277        String getModuleName(Desc *desc);
   278
   279        /*!
   280         *  ======== getModuleId ========
   281         *  Get the module id associated with a specified module descriptor
   282         *
   283         *  @param(desc)    non-`NULL` pointer to a `{#Desc Registry_Desc}`
   284         *                  structure.
   285         *
   286         *  @a(returns)
   287         *  If the specified module descriptor has been initialized via a
   288         *  successful call to `{@link #addModule Registry_addModule()}`, this
   289         *  function returns the module id assigned by `Registry_addModule()`;
   290         *  otherwise, its return value is indeterminate.
   291         */
   292        Types.ModuleId getModuleId(Desc *desc);
   293
   294    internal:
   295
   296        Desc *findByNameInList(String name, Desc *listHead);
   297        Void newModule(Desc *desc, String modName);
   298        Bool matchPattern(String pattern, Int len, String modName);
   299
   300        /* Functions for accessing the Registry at ROV-time. */
   301        function isMemberRov(modId);
   302        function lookupModIdRov(modId);
   303
   304        /*
   305         *  ======== Module_State ========
   306         */
   307        struct Module_State {
   308            Desc            *listHead;
   309            Types.ModuleId  curId;
   310        }
   311    }
   312    /*
   313     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   314     */
   315


module xdc.runtime.Reset

     1    /*!
     2     *  ======== Reset ========
     3     *  Startup reset function manager
     4     *
     5     *  This module defines an initial reset function and can be used without
     6     *  requiring any other `xdc.runtime` module.  The reset function is called
     7     *  as early as possible in the application startup and is intended for
     8     *  platform-specific hardware initialization.
     9     *
    10     *  The reset function sequentially calls each of the functions added to the
    11     *  `{@link #fxns}` array starting from index 0.  If
    12     *  `{@link Startup#resetFxn Startup.resetFxn}` is defined, it is called
    13     *  before any of the functions defined by the `fxns` array.
    14     *
    15     *  By providing an array of startup functions, rather than a single function
    16     *  as `{@ilnk Startup}` does, modules that need very early initialization
    17     *  can simply add their initialization to the list of functions to be called
    18     *  without having to implement a "chaining" mechanism or requiring the user
    19     *  to implement and maintain an application reset function.
    20     *
    21     *  @a(Warning)
    22     *  The reset function is _not_ supported on all platforms and, as a result,
    23     *  you should never place any "portable" code that is required for your
    24     *  application in this function.  Use the `@{link Startup}` module to
    25     *  define required application startup functions.
    26     *
    27     *  @see Startup
    28     */
    29    @Template("xdc/runtime/Reset.xdt")
    30    metaonly module Reset
    31    {
    32        /*!
    33         *  ======== fxns ========
    34         *  List of functions to call at reset
    35         *
    36         *  This array defines the functions that will be executed by the reset
    37         *  initialization function (`xdc_runtime_Startup_reset__I`) _in addition
    38         *  to_ the function specified by `@{link Startup#resetFxn}`.
    39         *
    40         *  The following code fragment shows how to add the externally defined
    41         *  function `myReset()` to this array.
    42         *  @p(code)
    43         *      var Reset = xdc.useModule("xdc.runtime.Reset");
    44         *      Reset.fxns[Reset.fxns.length++] = "&myReset";
    45         *  @p
    46         *
    47         *  @a(Warning)
    48         *  Although the functions specified in `fxns[]` are ordinary C functions,
    49         *  they are often called _before_ the C runtime is fully initialized;
    50         *  e.g., they may be called _before_ static variables are initialized.
    51         *  Reset functions should only assume that a minimal execution stack has
    52         *  initialized.
    53         *
    54         *  @see Startup#resetFxn
    55         */
    56        metaonly config xdc.runtime.Startup.InitFxn fxns[] = [];
    57    }
    58    /*
    59     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    60     */
    61


module xdc.runtime.Rta

     1    /*
     2     *  ======== Rta.xdc ========
     3     */
     4
     5    package xdc.runtime;
     6
     7    /*!
     8     *  ======== Rta ========
     9     *  The Rta module contains target and configuration code for providing RTA
    10     *  support.
    11     *
    12     *  The 'Command' enum defines the available control commands, and the
    13     *  'CommandPacket' structure defines the format of commands received from
    14     *  the host.
    15     *
    16     *  All commands should send back a response, even if only to acknowledge
    17     *  receipt and completion of the command. The format of the response
    18     *  is defined by the 'ResponsePacket' structure.
    19     *
    20     *  The Rta_processCommand can be used to process commands received from a
    21     *  host to call the appropriate API. Alternatively, the individual APIs can
    22     *  be called if not all of the defined commands are used.
    23     */
    24    module Rta {
    25
    26        /*! Logged when the Agent receives a command */
    27        config Log.Event LD_cmdRcvd = {
    28            mask: Diags.USER2,
    29            msg: "LD_cmdRcvd: Received command: %d, arg0: 0x%x, arg1: 0x%x"
    30        };
    31
    32        /*! Logged when a diags mask is changed */
    33        config Log.Event LD_writeMask = {
    34            mask: Diags.USER2,
    35            msg: "LD_writeMask: Mask addres: 0x%x, New mask value: 0x%x"
    36        };
    37
    38        /*! Assert if logger id in control command is invalid. */
    39        config Assert.Id A_invalidLogger = {
    40            msg: "A_invalidLogger: The logger id %d is invalid."
    41        };
    42
    43        /*! Error raised if Agent receives an invalid command. */
    44        config Error.Id E_badCommand  = {
    45            msg: "E_badCommand: Received invalid command, id: %d."
    46        };
    47
    48        /*! Command ids */
    49        enum Command : Int {
    50            Command_READ_MASK = 0,
    51            Command_WRITE_MASK = 1,
    52            Command_LOGGER_OFF = 2,
    53            Command_LOGGER_ON = 3,
    54            Command_GET_CPU_SPEED = 4,
    55            Command_RESET_LOGGER = 5,
    56            Command_CHANGE_PERIOD = 6,
    57            Command_START_TX = 7,
    58            Command_STOP_TX = 8
    59        };
    60
    61        /*!
    62         * Structure of command received from host
    63         * TODO - Either the types should be changed to 32-bits, or the packet
    64         * size information should be added to the RTA XML file.
    65         */
    66        struct CommandPacket {
    67            Command  cmdId;
    68            UArg     arg0;
    69            UArg     arg1;
    70        }
    71
    72        /*! Structure of response packet sent back to host */
    73        struct ResponsePacket {
    74            Command  cmdId;
    75            UArg     resp0;
    76            UArg     resp1;
    77        }
    78
    79        /*!
    80         *  ======== dataTransportClassName =========
    81         *  The name of the xdc.rta.IDataTransport class to use.
    82         *
    83         *  The class specified here can be used on the host for reading RTA data
    84         *  from this target application.
    85         */
    86        config String dataTransportClassName = "";
    87
    88        /*!
    89         *  ======== controlTransportClassName ========
    90         *  The name of the xdc.rta.IControlTransport class to use.
    91         *
    92         *  The class specified here can be used on the host for communicating with
    93         *  this target application to send control commands and receive responses.
    94         */
    95        config String controlTransportClassName = "";
    96
    97        /*!
    98         *  ======== processCommand ========
    99         *  Executes a command packet and prepares the response packet.
   100         *
   101         *  This API will execute the command specified by the command packet
   102         *  argument, and will store the response information in the response
   103         *  packet argument.
   104         *
   105         *  @param(cmd)    The CommandPacket to execute.
   106         *  @param(resp)   The ResponsePacket to populate with the response.
   107         */
   108        Void processCommand(CommandPacket *cmd, ResponsePacket *resp);
   109
   110        /*!
   111         *  ======== acknowledgeCmd ========
   112         */
   113        Void acknowledgeCmd(ResponsePacket *resp);
   114
   115        /*!
   116         *  ======== readMask ========
   117         */
   118        Void readMask(ResponsePacket *resp, UArg addr);
   119
   120        /*!
   121         *  ======== writeMask ========
   122         */
   123        Void writeMask(ResponsePacket *resp, UArg addr, UArg val);
   124
   125        /*!
   126         *  ======== enableLog ========
   127         */
   128        Void enableLog(ResponsePacket *resp, UArg log);
   129
   130        /*!
   131         *  ======== disableLog ========
   132         */
   133        Void disableLog(ResponsePacket *resp, UArg log);
   134
   135        /*!
   136         *  ======== getCpuSpeed ========
   137         */
   138        Void getCpuSpeed(ResponsePacket *resp);
   139
   140        /*!
   141         *  ======== resetLog ========
   142         */
   143        Void resetLog(ResponsePacket *resp, UArg log);
   144
   145        /*!
   146         *  ======== changePeriod ========
   147         */
   148        Void changePeriod(ResponsePacket *resp, UArg period);
   149
   150        /*!
   151         *  @_nodoc
   152         *  ======== genRta ========
   153         *  Generates the Rta XML file.
   154         */
   155        function genRta(outputFileName);
   156
   157    }
   158    /*
   159     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   160     */
   161


module xdc.runtime.Startup

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Startup.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Startup ========
    21     *  The `xdc.runtime` startup bootstrap
    22     *
    23     *  Every module can optionally define a startup function which is called
    24     *  before `main()`.  Modules declare that they want to participate in this
    25     *  startup sequence via the `@ModuleStartup` attribute in the module's spec
    26     *  file.  Modules that use this attribute must also implement the following
    27     *  startup function:
    28     *  @p(code)
    29     *      Int Mod_Module_startup(Int state);
    30     *  @p
    31     *  where "Mod" is the name of the module requesting startup support.
    32     *
    33     *  The parameter to the startup function serves as "state variable" whose
    34     *  initial value will be `Startup_NOTDONE`. If `startup()` returns a value
    35     *  other than `Startup_DONE`, it will be called in a subsequent pass with this
    36     *  return value passed in as `state`.  To ensure this process terminates,
    37     *  no startup function is ever called more than `{@link #maxPasses}`
    38     *  times.
    39     *
    40     *  For situations in which the startup of one module depends upon another
    41     *  having completed its startup processing, the following function is
    42     *  automatically defined for all modules and proxies:
    43     *  @p(code)
    44     *      Bool Mod_Module_startupDone();
    45     *  @p
    46     *  where "Mod" is the name of some module or proxy.  These predicates can
    47     *  be used as guards inside of a startup function to probe whether a
    48     *  particular module has completed its own startup processing.  As a
    49     *  convenience, the function `Startup_rtsDone()` probes the necessary set of
    50     *  `xdc.runtime` modules required to support instance `create()` functions, and
    51     *  should be called before any startup-time instance creation and/or
    52     *  memory allocation is performed.
    53     *  @p(code)
    54     *      Int Mod_Module_startup(Int state)
    55     *      {
    56     *          if (!Startup_rtsDone()) {
    57     *              return (Startup_NOTDONE);
    58     *          }
    59     *              .
    60     *              .
    61     *              .
    62     *          return (Startup_DONE);
    63     *      }
    64     *  @p
    65     *
    66     *  @a(Startup Sequence)
    67     *  The following list defines when in the startup sequence the user provided
    68     *  startup functions are being invoked:
    69     *  @p(nlist)
    70     *   - CPU is initialized and C stack setup is performed.
    71     *   - Function specified by `Startup.resetFxn` is called.
    72     *     `Startup.resetFxn` is called only on platforms where reset is performed
    73     *     before running a program. For example, boot code for all TI targets
    74     *     invokes `Startup.resetFxn`, while that function is not invoked on
    75     *     Microsoft targets.
    76     *   - C runtime initialization is performed.
    77     *   - Functions from the array `Startup.firstFxns` are called.
    78     *   - All `Mod_Module_startup` functions are called in a loop until all such
    79     *     functions return `Startup_DONE` or `maxPasses` threshold is reached.
    80     *   - Functions from the array `Startup.lastFxns` are called.
    81     *   - The function `main` is called.
    82     *  @p
    83     *     The steps 4 - 6 occur during C++ static object initialization. Since
    84     *     the ANSI C++ Language Standard does not provide a means to control
    85     *     the order of C++ constructors, if a C++ constructor uses an XDC module,
    86     *     there is no guarantee that the module's startup function already ran.
    87     *     Therefore, any C++ constructor that needs XDC modules' services should
    88     *     call `Startup_exec` first to force all startup related functions from
    89     *     steps 4 - 6 to run, before the constructor uses any XDC module.
    90     *  @p
    91     *     Also, if a target does not support C++, the steps 4 - 6 will not run
    92     *     automatically. It is then up to a user's code to invoke `Startup_exec`,
    93     *     possibly as the first step in `main`.
    94     *  @p
    95     */
    96    @Template("./Startup.xdt")
    97
    98    module Startup {
    99
   100        /*!
   101         *  ======== DONE ========
   102         *  Returned from module startup functions no further calls are required
   103         */
   104        const Int DONE = -1;
   105
   106        /*!
   107         *  ======== NOTDONE ========
   108         *  Initial value of state argument passed to module startup functions
   109         */
   110        const Int NOTDONE = 0;
   111
   112        /*!
   113         *  ======== ModuleView ========
   114         *  @_nodoc
   115         */
   116        metaonly struct ModuleView {
   117            Bool    rtsStartupDone;
   118            Bool    startupBegun;
   119            String  resetFxn;
   120            String  firstFxns[];
   121            String  lastFxns[];
   122        }
   123
   124        /*!
   125         *  ======== StartupStateView ========
   126         *  @_nodoc
   127         */
   128        metaonly struct StartupStateView {
   129            Int     order;
   130            String  moduleName;
   131            String  done;
   132        }
   133
   134        /*!
   135         *  ======== rovViewInfo ========
   136         *  @_nodoc
   137         */
   138        @Facet
   139        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   140            xdc.rov.ViewInfo.create({
   141                viewMap: [
   142                    ['Module',
   143                        {
   144                            type: xdc.rov.ViewInfo.MODULE,
   145                            viewInitFxn: 'viewInitModule',
   146                            structName: 'ModuleView'
   147                        }
   148                    ],
   149                    ['Startup State',
   150                        {
   151                            type: xdc.rov.ViewInfo.MODULE_DATA,
   152                            viewInitFxn: 'viewInitStartupState',
   153                            structName: 'StartupStateView'
   154                        }
   155                    ]
   156                ]
   157            });
   158
   159        /*!
   160         *  ======== maxPasses ========
   161         *  Max number of iterations over the set of startup functions
   162         */
   163        config Int maxPasses = 32;
   164
   165        /*!
   166         *  ======== InitFxn ========
   167         *  Type of function assignable to `firstFxns`, `lastFxns`, or `resetFxn`
   168         */
   169        typedef Void (*InitFxn)();
   170
   171        /*!
   172         *  ======== firstFxns ========
   173         *  List of functions called before module startup
   174         *
   175         */
   176        config InitFxn firstFxns[length] = [];
   177
   178        /*!
   179         *  ======== lastFxns ========
   180         *  List of functions called after module startup
   181         *
   182         */
   183        config InitFxn lastFxns[length] = [];
   184
   185        /*!
   186         *  ======== resetFxn ========
   187         *  Function to be called by during initialization
   188         *
   189         *  This function is called only on platforms where reset is performed
   190         *  before running the program. The purpose of this function is to set up
   191         *  the hardware registers (cache, external memory interface, etc.) before
   192         *  any other code executes.
   193         *
   194         */
   195        metaonly config InitFxn resetFxn = null;
   196
   197        /*!
   198         *  ======== exec ========
   199         *  Execute the startup functions of all resident modules
   200         *
   201         *  Note that this function is idempotent, and can be called at any point
   202         *  in the platform/target startup sequence in which "ordinary" C functions
   203         *  can execute.  By default, this function is called as part of the
   204         *  standard C++ static initialization sequence.
   205         *
   206         *  If your target compiler does not support C++, this function must be
   207         *  called at least once prior to using any `xdc.runtime` modules.
   208         *  Simply call this function at the very beginning of `main()`.
   209         */
   210        Void exec();
   211
   212        /*!
   213         *  ======== rtsDone ========
   214         *  Query the state of the `xdc.runtime` package
   215         *
   216         *  This function is used by module startup functions to determine
   217         *  when it is possible to use the `xdc.runtime` modules; e.g. to
   218         *  allocate memory, create instances managed by some module (even
   219         *  those outside the `xdc.runtime` package), call a `Log` function,
   220         *  etc.
   221         *
   222         *  @a(returns)
   223         *  Returns `TRUE` when all `xdc.runtime` modules have completed
   224         *  initialization.
   225         */
   226        Bool rtsDone();
   227
   228    internal:
   229
   230        /*!
   231         *  ======== reset ========
   232         *  Application-specific reset function
   233         *
   234         *  This function is defined in `Startup.xdt`
   235         *  (`xdc_runtime_Startup_reset__I`) and is called as early as
   236         *  possible in the program initialization process; for many platforms,
   237         *  it is called prior the the initialization of the C runtime
   238         *  environment.
   239         */
   240        Void reset();
   241
   242        Void startMods(Int state[], Int len);
   243        readonly config Void (*startModsFxn)(Int[], Int) = startMods;
   244
   245        extern Void execImplFxn() = xdc_runtime_Startup_exec__I;
   246
   247        readonly config Void (*execImpl)() = execImplFxn;
   248
   249        typedef Int (*SFxn)(Int);
   250        config SFxn sfxnTab[];
   251
   252        /*!
   253         *  ======== sfxnRts ========
   254         *  Array of runtime modules' startup functions
   255         *
   256         *  This array also contains startup functions of the modules that inherit
   257         *  from interfaces in `xdc.runtime`. Functions added to this array are
   258         *  called only once before the startup procedure for all modules begins.
   259         */
   260        config Bool sfxnRts[];
   261
   262        struct Module_State {
   263            Int *stateTab;      /* initially null */
   264            Bool execFlag;      /* if true, startup code processing started */
   265            Bool rtsDoneFlag;
   266        };
   267
   268    }
   269    /*
   270     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   271     */
   272


module xdc.runtime.SysMin

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SysMin.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== SysMin ========
    19     *
    20     *  Minimal implementation of `{@link ISystemSupport}`.
    21     *
    22     *  This implementation provides a fully functional implementation of
    23     *  all methods specified by `ISystemSupport`.
    24     *
    25     *  The module maintains an internal buffer (with a configurable size)
    26     *  that stores on the "output". When full, the data is over-written.  When
    27     *  `System_flush()` is called the characters in the internal buffer are
    28     *  "output" using the user configuratble `{@link #outputFxn}`.
    29     *
    30     *  As with all `ISystemSupport` modules, this module is the back-end for the
    31     *  `{@link System}` module; application code does not directly call these
    32     *  functions.
    33     */
    34
    35    @Template("./SysMin.xdt")
    36    @ModuleStartup
    37    module SysMin inherits xdc.runtime.ISystemSupport {
    38
    39        metaonly struct ModuleView {
    40            Ptr outBuf;
    41            UInt outBufIndex;
    42            Bool wrapped;    /* has the buffer wrapped */
    43        };
    44
    45        metaonly struct BufferEntryView {
    46            String entry;
    47        }
    48
    49        /*!
    50         *  ======== rovViewInfo ========
    51         *  @_nodoc
    52         */
    53        @Facet
    54        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
    55            xdc.rov.ViewInfo.create({
    56                viewMap: [
    57                    ['Module',
    58                        {
    59                            type: xdc.rov.ViewInfo.MODULE,
    60                            viewInitFxn: 'viewInitModule',
    61                            structName: 'ModuleView'
    62                        }
    63                    ],
    64                    ['OutputBuffer',
    65                        {
    66                            type: xdc.rov.ViewInfo.MODULE_DATA,
    67                            viewInitFxn: 'viewInitOutputBuffer',
    68                            structName: 'BufferEntryView'
    69                        }
    70                    ]
    71                ]
    72            });
    73
    74        /*!
    75         *  ======== bufSize ========
    76         *  Size (in MAUs) of the output.
    77         *
    78         *  An internal buffer of this size is allocated. All output is stored
    79         *  in this internal buffer.
    80         *
    81         *  If 0 is specified for the size, no buffer is created.
    82         */
    83        config SizeT bufSize = 1024;
    84
    85        /*!
    86         *  ======== flushAtExit ========
    87         *  Flush the internal buffer during `{@link #exit}` or `{@link #abort}`.
    88         *
    89         *  If the application's target is a TI target, the internal buffer is
    90         *  flushed via the `HOSTwrite` function in the TI C Run Time Support
    91         *  (RTS) library.
    92         *
    93         *  If the application's target is not a TI target, the internal buffer
    94         *  is flushed to `stdout` via `fwrite(..., stdout)`.
    95         *
    96         *  Setting this parameter to `false` reduces the footprint of the
    97         *  application at the expense of not getting output when the application
    98         *  ends via a `System_exit()`, `System_abort()`, `exit()` or `abort()`.
    99         */
   100        config Bool flushAtExit = true;
   101
   102        /*!
   103         *  ======== sectionName ========
   104         *  Section where the internal character output buffer is placed
   105         *
   106         *  The default is to have no explicit placement; i.e., the linker is
   107         *  free to place it anywhere in the memory map.
   108         */
   109        metaonly config String sectionName = null;
   110
   111        /*!
   112         *  ======== OutputFxn ========
   113         *  Output characters in the specified buffer
   114         *
   115         *  The first parameter is a pointer to a buffer of characters to be
   116         *  output.  The second parameter is the number of characters in the
   117         *  buffer to output.
   118         *
   119         *  This function may be called with 0 as the second parameter.  In this
   120         *  case, the function should simply return.
   121         *
   122         */
   123        typedef Void (*OutputFxn)(Char *, UInt);
   124
   125        /*!
   126         *  ======== outputFxn ========
   127         *  User suplied character output function
   128         *
   129         *  If this parameter is set to a non-`null` value, the specified
   130         *  function will be called by to output characters buffered within
   131         *  `SysMin`.
   132         *
   133         *  For example, if you define a function named `myOutputFxn`, the
   134         *  following configuration fragment will cause `SysMin` to call
   135         *  `myOutputFxn` whenever the character buffer is flushed.
   136         *  @p(code)
   137         *      var SysMin = xdc.useModule("xdc.runtime.SysMin");
   138         *      SysMin.outputFxn = "&myOutputFxn";
   139         *  @p
   140         *
   141         *  If this parameter is not set, a default function will be used which
   142         *  uses the ANSI C Standard Library function `fwrite()` (or `HOSTwrite`
   143         *  in the TI C Run Time Support library) to output
   144         *  accumulated output characters.
   145         *
   146         *  @see #OutputFxn
   147         */
   148        config OutputFxn outputFxn = null;
   149
   150        /*!
   151         *  ======== abort ========
   152         *  Backend for `{@link System#abort()}`
   153         *
   154         *  This abort function writes the string to the internal
   155         *  output buffer and then gives all internal output to the
   156         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}`
   157         *  configuration parameter is true.
   158         *
   159         *  @param(str)  message to output just prior to aborting
   160         *
   161         *      If non-`NULL`, this string should be output just prior to
   162         *      terminating.
   163         *
   164         *  @see ISystemSupport#abort
   165         */
   166        override Void abort(String str);
   167
   168        /*!
   169         *  ======== exit ========
   170         *  Backend for `{@link System#exit()}`
   171         *
   172         *  This exit function gives all internal output to the
   173         *  `{@link #outputFxn}` function if the `{@link #flushAtExit}`
   174         *  configuration parameter is true.
   175         *
   176         *  @see ISystemSupport#exit
   177         */
   178        override Void exit(Int stat);
   179
   180        /*!
   181         *  ======== flush ========
   182         *  Backend for `{@link System#flush()}`
   183         *
   184         *  The `flush` writes the contents of the internal character buffer
   185         *  via the `{@link #outputFxn}` function.
   186         *
   187         *  @a(Warning)
   188         *  The `{@link System}` gate is used for thread safety during the
   189         *  entire flush operation, so care must be taken when flushing with
   190         *  this `ISystemSupport` module.  Depending on the nature of the
   191         *  `System` gate, your application's interrupt latency
   192         *  may become a function of the `bufSize` parameter!
   193         *
   194         *  @see ISystemSupport#flush
   195         */
   196        override Void flush();
   197
   198        /*!
   199         *  ======== putch ========
   200         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
   201         *
   202         *  Places the character into an internal buffer. The `{@link #flush}`
   203         *  sends the internal buffer to the `{@link #outputFxn}` function.
   204         *  The internal buffer is also sent to the `SysMin_outputFxn`
   205         *  function by `{@link #exit}` and `{@link #abort}` if the
   206         *  `{@link #flushAtExit}` configuration parameter is true.
   207         *
   208         *  @see ISystemSupport#putch
   209         */
   210        override Void putch(Char ch);
   211
   212        /*!
   213         *  ======== ready ========
   214         *  Test if character output can proceed
   215         *
   216         *  This function returns true if the internal buffer is non-zero.
   217         *
   218         *  @see ISystemSupport#ready
   219         */
   220        override Bool ready();
   221
   222    internal:
   223
   224        /*
   225         * ======== output ========
   226         *  SysMin_output__I is generated based on bufSize.
   227         *
   228         *  This function is generated so that the code does not contain a call to
   229         *  HOSTwrite if bufSize is 0. Otherwise, if bufSize is 0, the compiler
   230         *  would optimize out the HOSTwrite function, leaving a 0-length symbol.
   231         *  If the a client later tried to pull in HOSTwrite, there would be a
   232         *  symbol error.
   233         *
   234         *  This generated function is accessed through an internal config so
   235         *  that it is an indirect call in the ROM case, but optimized to a direct
   236         *  call in the RAM case.
   237         */
   238        Void output(Char *buf, UInt size);
   239        readonly config OutputFxn outputFunc = '&xdc_runtime_SysMin_output__I';
   240
   241        struct Module_State {
   242            Char outbuf[];  /* the output buffer */
   243            UInt outidx;    /* index within outbuf to next Char to write */
   244            Bool wrapped;   /* has the index (outidx) wrapped */
   245        }
   246    }
   247    /*
   248     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   249     */
   250


module xdc.runtime.SysStd

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SysStd.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== SysStd ========
    21     *  Implementation of `{@link ISystemSupport}` using ANSI C Standard Library
    22     *
    23     *  This implementation provides a fully functional implementation of
    24     *  all methods specified by `ISystemSupport`. As with all
    25     *  `ISystemSupport` modules, this module is the back-end for the
    26     *  `{@link System}` module.
    27     *
    28     *  This implementation relies on the target's runtime support libraries
    29     *  (i.e. `fflush()` and `putchar()`). Therefore the  functions are re-entrant
    30     *  (thread-safe) if the underlying rts library is re-entrant.
    31     */
    32    module SysStd inherits xdc.runtime.ISystemSupport {
    33        /*!
    34         *  ======== abort ========
    35         *  Backend for `{@link System#abort()}`
    36         *
    37         *  This abort function writes the string via `putchar()`
    38         *  and flushes via `fflush()` to `stdout`.
    39         *
    40         *  @see ISystemSupport#abort
    41         */
    42        override Void abort(String str);
    43
    44        /*!
    45         *  ======== exit ========
    46         *  Backend for `{@link System#exit()}`
    47         *
    48         *  This exit function flushes via `fflush()` to `stdout`.
    49         *
    50         *  @see ISystemSupport#exit
    51         */
    52        override Void exit(Int stat);
    53
    54        /*!
    55         *  ======== flush ========
    56         *  Backend for `{@link System#flush()}`
    57         *
    58         *  This flush function flushes via `fflush()` to `stdout`.
    59         *
    60         *  @see ISystemSupport#flush
    61         */
    62        override Void flush();
    63
    64        /*!
    65         *  ======== putch ========
    66         *  Backend for `{@link System#printf()}` and `{@link System#putch()}`
    67         *
    68         *  This function outputs the character via `putchar()`.
    69         *
    70         *  @see ISystemSupport#putch
    71         */
    72        override Void putch(Char ch);
    73
    74        /*!
    75         *  ======== ready ========
    76         *  Test if character output can proceed
    77         *
    78         *  This always returns TRUE.
    79         *
    80         *  @see ISystemSupport#ready
    81         */
    82        override Bool ready();
    83    }
    84    /*
    85     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    86     */
    87


module xdc.runtime.System

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== System.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== System ========
    21     *  Basic system services
    22     *
    23     *  This module provides basic low-level "system" services; e.g.,
    24     *  character output, `printf`-like output, and exit handling.
    25     *
    26     *  This module is gated and other modules use its gate via the
    27     *  `{@link Gate#enterSystem}` and `{@link Gate#leaveSystem}`. The
    28     *  `System` gate must be enterable by any thread in a multi-threaded
    29     *  environments.  For example, in many real-time multi-threaded environments
    30     *  some types of threads, such as Interrupt Service Routines (ISRs), are not
    31     *  allowed to call operations that block the caller.  In such an environment,
    32     *  either the `System` gate must disable all interrupts or ISRs must never
    33     *  call a function in the `xdc.runtime` package.
    34     */
    35
    36    @Template("./System.xdt")
    37    @Gated
    38    @ModuleStartup
    39    module System {
    40
    41        /*!
    42         *  ======== AtexitHandler ========
    43         *  `System`'s atexit function prototype.
    44         *
    45         *  Fuctions of this type can be added to the list of functions that
    46         *  are executed during application termination.
    47         *
    48         *  @see #atexit
    49         */
    50        typedef Void (*AtexitHandler)(Int);
    51
    52        /*!
    53         *  ======== STATUS_UNKNOWN ========
    54         *  Unknown exit status value
    55         *
    56         *  When the program exits by calling {@link #exit System_exit()} the
    57         *  `System`'s `atexit` functions are passed the status value passed to
    58         *  `System_exit()`.  However, if the program exits using
    59         *  the ANSI C Standard Library `exit()` function, the `System`'s `atexit`
    60         *  functions are passed `System_STATUS_UNKNOWN`; ANSI C `atexit`
    61         *  functions are not passed the exit status.
    62         */
    63        const Int STATUS_UNKNOWN = 0xCAFE;
    64
    65        /*! @_nodoc */
    66        @XmlDtd
    67        metaonly struct Module_View {
    68            String  atexitHandlers[];
    69            Int     numAtexitHandlers;
    70        };
    71
    72        /*! @_nodoc */
    73        metaonly struct PathEntryView {
    74            String entry;
    75        }
    76
    77        /*!
    78         *  ======== rovViewInfo ========
    79         *  @_nodoc
    80         */
    81        @Facet
    82        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
    83            xdc.rov.ViewInfo.create({
    84                viewMap: [
    85                    ['XDCROOT',
    86                        {
    87                            type: xdc.rov.ViewInfo.MODULE_DATA,
    88                            viewInitFxn: 'viewInitXdcRoot',
    89                            structName: 'PathEntryView'
    90                        }
    91                    ],
    92                    ['XDCPATH',
    93                        {
    94                            type: xdc.rov.ViewInfo.MODULE_DATA,
    95                            viewInitFxn: 'viewInitXdcPath',
    96                            structName: 'PathEntryView'
    97                        }
    98                    ],
    99                ]
   100            });
   101
   102        /*!
   103         *  ======== A_cannotFitIntoArg ========
   104         *  Assert that the target's `Float` type fits in an `IArg`
   105         *
   106         *  This assertion is triggered when the `%f` format specifier is used,
   107         *  the argument treated as an `IArg`, but for the current target
   108         *  `sizeof(Float)` > `sizeof(IArg)`.
   109         */
   110        config Assert.Id A_cannotFitIntoArg = {
   111            msg: "A_cannotFitIntoArg: sizeof(Float) > sizeof(Arg)"
   112        };
   113
   114        /*!
   115         *  ======== extendedFormats ========
   116         *  Optional conversions supported by `{@link #printf System_printf}`
   117         *
   118         *  This string specifies the set of optional argument conversion
   119         *  specifiers required by the application.  By reducing the number of
   120         *  optional conversions understood by the `System {@link #printf}`
   121         *  methods, it is possible to significantly reduce the code size
   122         *  footprint of the `System` module.  This configuration parameter
   123         *  enables one to balance `printf` functionality against code size
   124         *  footprint.
   125         *
   126         *  The format of this string is simply a concatenated list of the desired
   127         *  conversion specifiers (with the leading `%` character).  For example,
   128         *  to support both `%f` and `%$L` set `extendedFormats` to `"%$L%f"`.
   129         *
   130         *  To disable all optional converstions, set `extendedFormats` to `null`
   131         *  or the empty string ("").
   132         *
   133         *  For a complete list of supported extensions, see the
   134         *  `{@link #printf System_printf}` "Extended_Format_Specifiers" section.
   135         *
   136         *  @a(Note)
   137         *  If an optional conversion is used by some part of the application and
   138         *  it is not specified in `extendedFormats`, the conversion character(s)
   139         *  and leading `%` are treated as ordinary characters to be output.  As
   140         *  a result, all subsequent arguments will almost certainly be converted
   141         *  using the wrong conversion specifier!
   142         *
   143         *  @see #printf
   144         */
   145        metaonly config String extendedFormats = "%$L%$S%$F";
   146
   147        /*!
   148         *  ======== SupportProxy ========
   149         *  The implementation module of the low-level system functions.
   150         *
   151         *  This configuration parameter allows one to "bind" a different
   152         *  implementation of the low-level services required to implement
   153         *  `System`.
   154         *  @p(code)
   155         *      var System = xdc.useModule("xdc.runtime.System");
   156         *      var SysStd = xdc.useModule("xdc.runtime.SysStd");
   157         *      System.SupportProxy = SysStd;
   158         *  @p
   159         *
   160         *  If this parameter is not set, it defaults to `{@link SysMin}`.
   161         */
   162        proxy SupportProxy inherits ISystemSupport;
   163
   164        /*!
   165         *  ======== maxAtexitHandlers ========
   166         *  Maximum number of dynamic atexit handlers allowed in the system.
   167         *
   168         *  Maximum number of `System` `atexit` handlers set during runtime via
   169         *  the `{@link System#atexit}` function.
   170         *
   171         */
   172        config Int maxAtexitHandlers = 8;
   173
   174        /*!
   175         *  ======== abort ========
   176         *  Print a message and abort currently running executable.
   177         *
   178         *  This is called when an executable abnormally terminates.
   179         *  The `System` gate is entered, the
   180         *  `{@link #SupportProxy}`'s `abort` function is called
   181         *  and `abort` is called.
   182         *  No exit functions bound via `System_atexit()` or the ANSI C Standard
   183         *  Library `atexit()` functions are executed.
   184         *
   185         *  @param(str) abort message (not a format string)
   186         */
   187        Void abort(String str);
   188
   189        /*!
   190         *  ======== atexit ========
   191         *  Add an exit handler
   192         *
   193         *  `System_atexit` pushes `handler` onto an internal stack of functions
   194         *  to be executed when system is exiting (e.g. `System_exit` or `exit` is
   195         *  called). Up to `{@link #maxAtexitHandlers}` functions can be specified
   196         *  in this manner.  During the exit processing, the functions are popped
   197         *  off the internal stack and called until the stack is empty.
   198         *
   199         *  The `System` gate is entered before the `System_atexit` functions
   200         *  are called.
   201         *
   202         *  The `SupportProxy`'s `{@link ISystemSupport#exit}` function is called
   203         *  after all the atexit functions are called.
   204         *
   205         *  @param(handler) the `AtexitHandler` to invoke during system
   206         *                  exit processing.
   207         *
   208         *  @a(returns)
   209         *  If `FALSE` is returned, the exit handler was not added and it will
   210         *  not be called during an exit.
   211         */
   212        Bool atexit(AtexitHandler handler);
   213
   214        /*!
   215         *  ======== atexitMeta ========
   216         *  Add an exit handler during configuration
   217         *
   218         *  This is the static counterpart to `System_atexit()`. This method can
   219         *  be used to add `atexit` handlers at configuration time.  These
   220         *  handlers do not count against the `maxAtexitHandlers`.
   221         *
   222         *  @param(handler) the `AtexitHandler` to invoke during system
   223         *                  exit processing.
   224         */
   225        metaonly Void atexitMeta(AtexitHandler handler);
   226
   227        /*!
   228         *  ======== exit ========
   229         *  Exit currently running executable.
   230         *
   231         *  This function is called when an executable needs to terminate
   232         *  normally.  This function sets the exit code and simply calls `exit`.
   233         *  All functions bound via `System_atexit` or the ANSI C Standar Library
   234         *  `atexit` function are then executed. The `{@link #SupportProxy}`'s
   235         *  `exit` function is called during this time.
   236         *
   237         *  @param(stat)    exit status to return to calling environment.
   238         */
   239        Void exit(Int stat);
   240
   241        /*!
   242         *  ======== putch ========
   243         *  Output a single character
   244         *
   245         *  The `{@link #SupportProxy}`'s `putch` function is called
   246         *  by this function.
   247         *
   248         *  @param(ch) character to be output.
   249         */
   250        Void putch(Char ch);
   251
   252        /*!
   253         *  ======== flush ========
   254         *  Flush standard System I/O
   255         *
   256         *  This function causes any buffered output characters are "written"
   257         *  to the output device.
   258         *
   259         *  The `{@link #SupportProxy}`'s `flush` function is called
   260         *  by this function.
   261         */
   262        Void flush();
   263
   264        /*!
   265         *  ======== printf ========
   266         *  A smaller faster printf
   267         *
   268         *  This function behaves much like the ANSI C Standard `printf`
   269         *  but does not support the full range of format strings specified by
   270         *  the C Standard.  In addition, several non-standard format specifiers
   271         *  are recognized.
   272         *
   273         *  @a(Format Strings)
   274         *  The format string is a character string composed of zero or
   275         *  more directives: ordinary characters (not %), which are copied
   276         *  unchanged to the output stream; and conversion specifications, each of
   277         *  which results in fetching zero or more subsequent arguments.  Each
   278         *  conversion specification is introduced by the character %, and ends
   279         *  with a conversion specifier.  In between there may be (in this order)
   280         *  zero or more flags, an optional minimum field width, an optional
   281         *  precision and an optional length modifier.
   282         *
   283         *  @a(Flags)
   284         *  The following flags are supported:
   285         *  @p(dlist)
   286         *      - `-`
   287         *          The converted value is to be left adjusted on the field
   288         *          boundary (the default is right justification.)
   289         *      - `0`
   290         *          The value should be zero padded. For d, i, o, u, and x
   291         *          conversions, the converted value is padded on the left
   292         *          with zeros rather than blanks.
   293         *  @p
   294         *
   295         *  @a(Field Width)
   296         *  The optional field width specifier is a decimal digit string (with
   297         *  nonzero first digit) specifying a minimum field width. If the
   298         *  converted value has fewer characters than the field width, it will
   299         *  be padded with spaces on the left (or right, if the left-adjustment
   300         *  flag has been given).  Instead of a decimal digit string one may
   301         *  write `*` to specify that the field width is given in the next
   302         *  argument.  A negative field width is taken as a '-' flag followed
   303         *  by a positive field width.
   304         *
   305         *  @a(Precision)
   306         *  The optional precision specifier is a period ('.') followed by an
   307         *  optional decimal digit string.  Instead of a decimal digit string
   308         *  one may write `*` to specify that the precision is given in the
   309         *  next argument which must be of type int.
   310         *
   311         *  If the precision is given as just '.', or the precision is
   312         *  negative, the precision is taken to be zero.  This gives the
   313         *  minimum number of digits to appear for d, i, o, u, and x
   314         *  conversions, or the maximum number of characters to be printed from
   315         *  a string for s conversions.
   316         *
   317         *  @a(Length Modifiers)
   318         *  The optional length modifier is a single character from the following
   319         *  list.
   320         *  @p(dlist)
   321         *      - `l`
   322         *          A  following integer conversion corresponds to a long int
   323         *          or unsigned long int argument
   324         *
   325         *  @p
   326         *
   327         *  @a(Conversion Specifiers)
   328         *  The following conversion specifiers are supported.
   329         *  @p(dlist)
   330         *      - `d`, `i`
   331         *          signed integer
   332         *      - `u`
   333         *          unsigned decimal
   334         *      - `x`
   335         *          unsigned hex
   336         *      - `o`
   337         *          unsigned octal
   338         *      - `p`
   339         *          pointer (@ + hex num)
   340         *      - `c`
   341         *          character
   342         *      - `s`
   343         *          string
   344         *  @p
   345         *  @a(Extended Conversion Specifiers)
   346         *  The following conversion specifiers are optionally supported.  See
   347         *  the `{@link #extendedFormats}` configuration parameter for more
   348         *  information about how to enable these conversion specifiers.
   349         *
   350         *  @p(dlist)
   351         *      - `f`
   352         *          decimal floating point.
   353         *      - `$`
   354         *          non-ANSI conversion prefix.  This prefix indicates that the
   355         *          next character identifies a non-ANSI standard conversion. See
   356         *          the next section for details.
   357         *  @p
   358         *
   359         *  @a(Non ANSI Conversion Specifiers)
   360         *  Among the extended conversion specifiers are unique specifiers which
   361         *  are not part of ANSI printf. These are specified using a $, for
   362         *  example %$L.
   363         *
   364         *  These unique specifiers do not support the minimum field width
   365         *  attribute. Certain specifiers have additional restrictions; see below.
   366         *
   367         *  @p(dlist)
   368         *      - '$L'
   369         *          The argument is treated as a pointer to a `{@link Types#Label}`
   370         *          and is converted to an appropriate string.
   371         *      - '$F'
   372         *          Displays a file and line number; used for displaying the call
   373         *          site. This specifier consumes two arguments, the file and line
   374         *          number, in that order. See an example below.
   375         *      - '$S'
   376         *          The argument is treated as a format string, and is recursively
   377         *          formatted using any following arguments. This specifier does
   378         *          not support the use of the "precision" field for specifying
   379         *          maximum string length.
   380         *  @p
   381         *
   382         *  The following are example uses of the %$F and %$S format specifiers.
   383         *
   384         *  In this call using %$F, the compiler recognizes these symbols and
   385         *  fills in the file and line number.
   386         *  @p(code)
   387         *  System_printf("%$F", __FILE__, __LINE__);
   388         *  @p
   389         *  This call outputs, for example,
   390         *  @p(code)
   391         *  "MyCode.c", line 35:
   392         *  @p
   393         *  Here is an example using %$S, passing a recursive format string.
   394         *  @p(code)
   395         *  System_printf("Msg: %$S", "My msg, code: %d", 5);
   396         *  @p
   397         *  This outputs:
   398         *  @p(code)
   399         *  Msg: My msg, code: 5
   400         *  @p
   401         *
   402         *  @param(fmt) a 'printf-style' format string
   403         *
   404         *  @a(returns)
   405         *  `printf` returns the number of characters printed.
   406         */
   407        Int printf(String fmt, ...);
   408
   409        /*!
   410         *  ======== aprintf ========
   411         *  `{@link #printf}` where all optional arguments are `IArg`s
   412         *
   413         *  This function will treat each argument as though it was widened to be
   414         *  of type `IArg` prior to being passed to the `{@link #printf}` function
   415         *
   416         *  @see #printf
   417         */
   418        Int aprintf(String fmt, ...);
   419
   420        /*!
   421         *  ======== sprintf ========
   422         *  Write formated output to a character buffer
   423         *
   424         *  This function is identical to `{@link #printf}` except that the
   425         *  output is copied to the specified character buffer `buf` followed
   426         *  by a terminating '\0' character.
   427         *
   428         *  @param(buf) a character output buffer
   429         *  @param(fmt) a 'printf-style' format string
   430         *
   431         *  @a(returns)
   432         *  `sprintf` returns the number of characters output not including the
   433         *  '\0' termination character.
   434         */
   435        Int sprintf(Char buf[], String fmt, ...);
   436
   437        /*!
   438         *  ======== asprintf ========
   439         *  `{@link #sprintf}` where all optional arguments are `IArg`s
   440         *
   441         *  This function will treat each argument as though it was widened to be
   442         *  of type `IArg` prior to being passed to the `{@link #sprintf}`
   443         *  function.
   444         *
   445         *  @see #sprintf
   446         */
   447        Int asprintf(Char buf[], String fmt, ...);
   448
   449        /*!
   450         *  ======== vprintf ========
   451         *  A VaList printf
   452         *
   453         *  This function is identical to `{@link #printf}` except that its
   454         *  arguments are passed via a VaList (a "varargs list").
   455         *
   456         *  @param(fmt) a standard 'printf-style' format string.
   457         *  @param(va)  an args list that points to the arguments referenced
   458         *              by the fmt string
   459         *
   460         *  @a(returns)
   461         *  `vprintf` returns the number of characters output.
   462         */
   463        Int vprintf(String fmt, VaList va);
   464
   465        /*!
   466         *  ======== avprintf ========
   467         *  `{@link #vprintf}` where all optional arguments are `IArg`s
   468         *
   469         *  This function will treat each argument as though it was widened to be
   470         *  of type `IArg` prior to being passed to the `{@link #vprintf}`
   471         *  function.
   472         *
   473         *  @see #vprintf
   474         */
   475        Int avprintf(String fmt, VaList va);
   476
   477        /*!
   478         *  ======== vsprintf ========
   479         *  A `VaList` sprintf
   480         *
   481         *  This function is identical to `{@link #sprintf}` except that
   482         *  its arguments are passed via a `VaList` (a "varargs list").
   483         *
   484         *  @param(buf) a character output buffer
   485         *  @param(fmt) a standard '`printf`-style' format string.
   486         *  @param(va)  an arguments list that points to the arguments referenced
   487         *              by the `fmt` string
   488         *
   489         *  @a(returns)
   490         *  `vsprintf` returns the number of characters output.
   491         */
   492        Int vsprintf(Char buf[], String fmt, VaList va);
   493
   494        /*!
   495         *  ======== avsprintf ========
   496         *  `{@link #vsprintf}` where all optional arguments are `IArg`s
   497         *
   498         *  This function is identical to `{@link #sprintf}` except that
   499         *  its arguments are passed via a `VaList` (a "varargs list").
   500         *
   501         *  This function will treat each argument as though it was widened to be
   502         *  of type `IArg` prior to being passed to the `vsprintf` function
   503         *
   504         *  @see #vsprintf
   505         */
   506        Int avsprintf(Char buf[], String fmt, VaList va);
   507
   508    internal:
   509
   510        /*! struct used to keep track of state during doPrint */
   511        struct ParseData {
   512            Int     width;      /* width in format specifier */
   513            Bool    lFlag;      /* length modifier flag */
   514            Bool    lJust;      /* left justify flag */
   515            Int     precis;     /* precision in format specifier */
   516            Int     len;        /* length of formatted number */
   517            Int     zpad;       /* leading zero pad flag */
   518            Char    *end;       /* pointer to end of local buf to hold num */
   519            Bool    aFlag;      /* deal with vars on stack as IArgs */
   520            Char    *ptr;       /* ptr to local buf after filling in num */
   521        };
   522
   523        /*! typedef for generated functions to process extended formats */
   524        typedef Int (*ExtendFxn)(Char **, Char **, VaList *, ParseData *);
   525
   526        /*! config parameter used to call generated function  */
   527        readonly config ExtendFxn extendFxn = '&xdc_runtime_System_printfExtend__I';
   528
   529        /*
   530         * ======== printfExtend ========
   531         *  System_printfExtend is generated based on extendedFormats string
   532         *
   533         *  This generated function is accessed through an internal config so
   534         *  that it is an indirect call in the ROM case, but optimized to a direct
   535         *  call in the RAM case.
   536         *
   537         * @_nodoc
   538         */
   539        Int printfExtend (Char **bufp, Char **fmt, VaList *va, ParseData *parse);
   540
   541        /*!
   542         *  ======== exitFxns ========
   543         *  @_nodoc
   544         *  List of functions statically plugged to be called at exit
   545         *
   546         */
   547        metaonly config AtexitHandler exitFxns[];
   548
   549        /*!
   550         *  ======== mprintf ========
   551         *  @_nodoc
   552         */
   553        function mprintf(fmt, args);
   554
   555        /*!
   556         *  ======== doPrint ========
   557         *  @_nodoc
   558         */
   559        Int doPrint(Char buf[], String fmt, VaList *pva, Bool aFlag);
   560
   561        /*!
   562         *  ======== formatNum ========
   563         *  @_nodoc
   564         *
   565         */
   566        Char *formatNum(Char *ptr, UInt32 n, Int zpad, Int base);
   567
   568        /*!
   569         *  ======== putchar ========
   570         *  @_nodoc
   571         *
   572         *  Write character ch to the buffer and, if the buffer pointer is
   573         *  non-`NULL`, update the buffer pointer.
   574         */
   575        Void putchar(Char **bufp, Char ch);
   576
   577        /*!
   578         *  ======== rtsExit ========
   579         *  @_nodoc
   580         */
   581        Void rtsExit();
   582
   583        /*!
   584         *  ======== Module_State ========
   585         *  @_nodoc
   586         */
   587        struct Module_State {
   588            AtexitHandler  atexitHandlers[];   /* array of atexit handlers       */
   589            Int            numAtexitHandlers;  /* Current num of atexit handlers */
   590            Int            exitStatus;         /* status for exit handlers       */
   591        };
   592    }
   593    /*
   594     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   595     */
   596


module xdc.runtime.Text

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ========= Text.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Text ========
    21     *  Runtime text handling services
    22     *
    23     *  This module efficiently manages a collection of strings that have
    24     *  common substrings.  Collections with a high degree of commonality
    25     *  are stored in much less space than as ordinary table of independent
    26     *  C strings.
    27     *
    28     *  To further save space, the "compressed" representation need not even
    29     *  be loaded in the target's memory; see `{@link #isLoaded}`.
    30     *
    31     *  The total space available for the compressed representation of text
    32     *  strings is limited to 64K characters; each string is represented by
    33     *  a 16-bit "rope id".
    34     */
    35    @Template("./Text.xdt")
    36    module Text {
    37
    38        /*!
    39         *  ======== CordAddr ========
    40         *  @_nodoc
    41         */
    42        typedef Types.CordAddr CordAddr;
    43
    44        /*!
    45         *  ======== Label ========
    46         */
    47        typedef Types.Label Label;
    48
    49        /*!
    50         *  ======== RopeId ========
    51         *  @_nodoc
    52         *
    53         *  A rope id is a 16-bit value whose most-significant bit indicates
    54         *  whether the lower 15-bits are an offset into the string table
    55         *  `charTab` or an offset into the "node" table `nodeTab`.
    56         *
    57         *  The node id 0 represents the empty string "".
    58         */
    59        typedef Types.RopeId RopeId;
    60
    61        /*!
    62         *  ======== Module_View ========
    63         *  @_nodoc
    64         */
    65        @XmlDtd
    66        metaonly struct Module_View {
    67            Ptr charBase;
    68            Ptr nodeBase;
    69        };
    70
    71        /*!
    72         *  ======== nameUnknown ========
    73         *  Default unknowable instance name
    74         *
    75         *  The name of an instance if the module's instances are configured to
    76         *  not have names.
    77         */
    78        config String nameUnknown = "{unknown-instance-name}";
    79
    80        /*!
    81         *  ======== nameEmpty ========
    82         *  Default `NULL` instance name
    83         *
    84         *  The name used if the instance's name has been set to `NULL`.
    85         */
    86        config String nameEmpty = "{empty-instance-name}";
    87
    88        /*!
    89         *  ======== nameStatic ========
    90         *  Default static instance name
    91         *
    92         *  The name of an instance if the name exists but it's not loaded
    93         *  on the target.
    94         */
    95        config String nameStatic = "{static-instance-name}";
    96
    97        /*!
    98         *  ======== isLoaded ========
    99         *  Ensure character-strings are loaded in target memory
   100         *
   101         *  Character strings managed by this module are allocated together
   102         *  with other character strings, and loaded to the target, when this
   103         *  parameter is set to its default value `true`. If this parameter is
   104         *  set to `false`, the character strings managed by Text are separated
   105         *  in their own section `xdc.noload`, which is not loaded to the target.
   106         *
   107         *  @a(Note)
   108         *  For TI and GNU targets, the section `xdc.noload` is not loaded to
   109         *  the target, but it can overlay other output sections. If the linker
   110         *  allocates `xdc.noload` so that it overlaps the section that contains
   111         *  character strings when `isLoaded` is `false`, ROV/RTA functionality
   112         *  can be affected. In such a case, an error message is displayed that
   113         *  indicates the overlap between `xdc.noload` and another section, whose
   114         *  name depends on the target (.`const` on TI targets, `.rodata` on
   115         *  GNU targets).
   116         *  The user can solve that problem by specifying an address for
   117         *  `xdc.noload` to unconfigured memory, and ensure that `.const` and
   118         *  `xdc.noload` do not overlap.
   119         *  @p(code)
   120         *      Program.sectMap["xdc.noload"] = new prog.SectionSpec();
   121         *      Program.sectMap["xdc.noload"].loadAddress = 0x50000000;
   122         *  @p
   123         */
   124        config Bool isLoaded = true;
   125
   126        /*!
   127         *  ======== cordText ========
   128         *  Return `NULL` if cord is in `charTab` and `isLoaded` is `FALSE`
   129         *  @_nodoc
   130         */
   131        String cordText(CordAddr cord);
   132
   133        /*!
   134         *  ======== ropeText ========
   135         *  Convert rope to an ordinary C string
   136         *
   137         *  Convert rope to an ordinary C string or to NULL if rope refers
   138         *  to a node in nodeTab
   139         *
   140         *  @_nodoc
   141         */
   142        String ropeText(RopeId rope);
   143
   144        /*!
   145         *  ======== matchRope ========
   146         *  Compare pattern string `pat` to String identified by `rope`.
   147         *  @_nodoc
   148         *
   149         *  @a(pre-conditions)
   150         *  @p(blist)
   151         *      - lenp must be less than or equal to the length of pat
   152         *  @p
   153
   154         *  @a(post-conditions)
   155         *  @p(blist)
   156         *      - lenp is decreased by the length of any matching prefix
   157         *  @p
   158         *
   159         *  Returns:
   160         *  @p(blist)
   161         *      - -1  `pat` does not match string
   162         *      - 0   string is a prefix of pattern
   163         *      - 1   wildcard match
   164         *  @p
   165         */
   166        Int matchRope(RopeId rope, String pat, Int *lenp);
   167
   168        /*!
   169         *  ======== putLab ========
   170         *  Convert label to an ASCII character sequence
   171         *
   172         *  This function converts a `{@link Types#Label}` to a sequence of
   173         *  ASCII characters, writes the characters to the supplied buffer,
   174         *  updates the buffer pointer to point to the location after the last
   175         *  output character, and returns the number of characters output.
   176         *
   177         *  No more than `len` characters will be output.  If the label would
   178         *  otherwise be longer, the output is truncated at the point where a
   179         *  potential overflow is detected. The return value always reflects the
   180         *  number of characters output, but it may be less than `len`.
   181         *
   182         *  Label structures can be initialized from any module's instance handle
   183         *  using the module's `Mod_Handle_label()` method.  See
   184         *  `{@link Types#Label}` for more information.
   185         *
   186         *  @param(lab)    address of the label to interpret
   187         *  @param(bufp)   address of the output buffer pointer or `NULL`
   188         *
   189         *                 If `bufp` is `NULL`, the label's characters are
   190         *                 output via `{@link System#putch()}`.
   191         *
   192         *  @param(len)    maximum number of characters to generate
   193         *
   194         *                 If `len` is negative, the number of characters to be
   195         *                 generated is not limited.
   196         *
   197         *  @a(returns)
   198         *  The return value always reflects the number of characters output,
   199         *  but it may be less than `len`.
   200         *
   201         *  @see Types#Label
   202         */
   203        Int putLab(Types.Label *lab, Char **bufp, Int len);
   204
   205        /*!
   206         *  ======== putMod ========
   207         *  Convert module ID to its ASCII name
   208         *
   209         *  This function converts a `{@link Types#ModuleId}` to a sequence of
   210         *  ASCII characters, writes the characters to the supplied buffer,
   211         *  updates the buffer pointer to point to the location after the last
   212         *  output character, and returns the number of characters output.
   213         *
   214         *  No more than `len` characters will be output.  If the module name would
   215         *  otherwise be longer, the output is truncated at the point where a
   216         *  potential overflow is detected. The return value always reflects the
   217         *  number of characters output, but it may be less than `len`.
   218         *
   219         *  @param(mid)    ID of the module
   220         *  @param(bufp)   address of the output buffer pointer or `NULL`
   221         *
   222         *                 If `bufp` is `NULL`, the module's name characters are
   223         *                 output via `{@link System#putch()}`.
   224         *
   225         *  @param(len)    maximum number of characters to generate
   226         *
   227         *                 If `len` is negative, the number of characters to be
   228         *                 generated is not limited.
   229         *
   230         *  @a(returns)
   231         *  The return value always reflects the number of characters output,
   232         *  but it may be less than `len`.
   233         */
   234        Int putMod(Types.ModuleId mid, Char **bufp, Int len);
   235
   236        /*!
   237         *  ======== putSite ========
   238         *  Convert call site structure to an ASCII character sequence
   239         *
   240         *  This function converts a `{@link Types#Site}` to a sequence of
   241         *  ASCII characters, writes the characters to the supplied buffer,
   242         *  updates the buffer pointer to point to the location after the last
   243         *  output character, and returns the number of characters output.
   244         *
   245         *  No more than `len` characters will be output.  If the sequence would
   246         *  otherwise be longer, the output is truncated at the point where a
   247         *  potential overflow is detected.
   248         *
   249         *  @param(site)   address of the call site structure to interpret
   250         *  @param(bufp)   address of the output buffer pointer or `NULL`
   251         *
   252         *                 If `bufp` is `NULL`, the site's name characters are
   253         *                 output via `{@link System#putch()}`.
   254         *
   255         *  @param(len)    maximum number of characters to generate
   256         *
   257         *                 If `len` is negative, the number of characters to be
   258         *                 generated is not limited.
   259         *
   260         *  @a(returns)
   261         *  The return value always reflects the number of characters output,
   262         *  but it may be less than `len`.
   263         */
   264        Int putSite(Types.Site *site, Char **bufp, Int len);
   265
   266    internal:
   267
   268        struct Node {
   269            Types.RopeId left;
   270            Types.RopeId right;
   271        };
   272
   273        typedef Bool (*RopeVisitor)(Ptr, String);
   274
   275        struct MatchVisState {
   276            String pat;
   277            Int *lenp;
   278            Int res;
   279        };
   280
   281        struct PrintVisState {
   282            Char **bufp;
   283            Int len;
   284            Int res;
   285        };
   286
   287        /* charTab[] and nodeTab[] are the "compressed" representation of
   288         * target strings used to name instances, modules, packages, ...
   289         *
   290         * The predefined node id 0 represents the empty string.
   291         */
   292        config Char charTab[] = [0];
   293        config Node nodeTab[] = [{left: 0, right: 0}];
   294
   295        config Int16 charCnt = 1;
   296        config Int16 nodeCnt = 1;
   297
   298        /*
   299         * The module ids are allocated as follows:
   300         * 0x1 - 0x4000     unnamed modules
   301         * 0x4001 - 0x7FFF  registry modules
   302         * 0x8000 - 0xFFFF  named modules
   303         *
   304         * See 'genModNames' in Text.xs
   305         *
   306         * TODO - We may be able to set unnamedModsLastId based on the config
   307         *        to give the Registry more room, but then the Registry id range
   308         *        would not be a constant.
   309         */
   310        config UInt16 unnamedModsLastId = 0x4000;
   311        config UInt16 registryModsLastId = 0x7FFF;
   312
   313    /* unnamedModCnt can be used to define a constant that allows external
   314     * modules to define their own module IDs that don't conflict with the
   315     * statically configured modules; e.g., the dlog example could use this
   316     */
   317    //    config Int16 unnamedModCnt = 0;
   318
   319        function defineRopeCord(text);
   320        function defineRopeNode(left, right);
   321
   322        function fetchAddr(raddr);
   323        function fetchCord(cid);
   324        function fetchId(rid);
   325        function fetchNode(nid);
   326
   327        function genModNames();
   328        function genPkgName();
   329
   330        Bool matchVisFxn(Ptr p, String s);
   331        Bool printVisFxn(Ptr p, String s);
   332
   333        Void visitRope(RopeId rope, Fxn visFxn, Ptr visState);
   334        Void visitRope2(RopeId rope, Fxn visFxn, Ptr visState, String stack[]);
   335
   336        typedef Void (*VisitRopeFxn)(RopeId, Fxn, Ptr);
   337        typedef Void (*VisitRopeFxn2)(RopeId, Fxn, Ptr, String[]);
   338
   339        config VisitRopeFxn visitRopeFxn = visitRope;
   340
   341        config VisitRopeFxn2 visitRopeFxn2 = visitRope2;
   342
   343        Int xprintf(Char **bufp, String fmt, ...);
   344
   345        struct Module_State {
   346            Ptr charBase;
   347            Ptr nodeBase;
   348        };
   349    }
   350    /*
   351     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   352     */
   353


module xdc.runtime.Timestamp

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Timestamp.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Timestamp ========
    21     *  Timestamp services
    22     *
    23     *  This module provides `{@link xdc.runtime.ITimestampClient}` APIs for
    24     *  the xdc Runtime Support Library. Calls to these APIs are forwarded
    25     *  to a platform specific `{@link xdc.runtime.ITimestampProvider}`
    26     *  implementation.
    27     *
    28     *  A user can attach their own ITimestampProvider module
    29     *  using the following config file command:
    30     *  @p(code)
    31     *
    32     *  xdc.runtime.Timestamp.SupportProxy = xdc.useModule("usersTimestampProvider");
    33     *  @p
    34     *  If no such `{@link #SupportProxy SupportProxy}` initialization is done,
    35     *  the `{@link xdc.runtime.TimestampNull}` ITimestampProvider implementation,
    36     *  which provides null stubs for the APIs, will be attached by default.
    37     *
    38     *  If the user is developing code using CCS, the
    39     *  `{@link xdc.runtime.TimestampStd}`
    40     *  ITimestampProvider implementation, which uses the ANSI C clock()
    41     *  function, may provide a satisfactory timestamp source (remember to
    42     *  enable the profile clock in CCS).
    43     *
    44     *  To use the TimestampStd implementation, add the following to
    45     *  your config script:
    46     *  @p(code)
    47     *
    48     *  xdc.runtime.Timestamp.SupportProxy = xdc.useModule("xdc.runtime.TimestampStd");
    49     *  @p
    50     */
    51    module Timestamp inherits ITimestampClient {
    52
    53        /*!
    54         *  ======== SupportProxy ========
    55         *  User supplied time stamp provider module.
    56         *
    57         *  The SupportProxy module provides application/platform
    58         *  specific implementations of the
    59         *  `{@link xdc.runtime.ITimestampProvider}` APIs.
    60         *
    61         *  If not explicitly supplied by the user, this proxy defaults to
    62         *  `{@link xdc.runtime.TimestampNull}`,
    63         *  which provides null stubs for all of the ITimestampProvider APIs.
    64         */
    65        proxy SupportProxy inherits ITimestampProvider;
    66    }
    67    /*
    68     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    69     */
    70


module xdc.runtime.TimestampNull

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    package xdc.runtime;
    14
    15    /*!
    16     *  ======== TimestampNull ========
    17     *  Empty implementation of `{@link ITimestampProvider}`
    18     */
    19    module TimestampNull inherits ITimestampProvider {}
    20    /*
    21     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    22     */
    23


module xdc.runtime.TimestampStd

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    package xdc.runtime;
    14
    15    /*!
    16     *  ======== TimestampStd ========
    17     *  Implementation of `{@link ITimestampProvider}` using ANSI C `clock()`
    18     */
    19    module TimestampStd inherits ITimestampProvider {}
    20    /*
    21     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    22     */
    23


module xdc.runtime.Types

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Types.xdc ========
    15     */
    16
    17    package xdc.runtime;
    18
    19    /*!
    20     *  ======== Types ========
    21     *  Basic constants and types
    22     *
    23     *  This module defines basic constants and types used throughout the
    24     *  `xdc.runtime` package and, in some cases, in every module.
    25     *
    26     *  The `{@link #Common$ Common$}` structure defined by the `Types` module
    27     *  is available for (or common to) all modules. Every field of the
    28     *  `Common$` structure is a configuration parameter that may be set within
    29     *  a configuration script for any module (not just the
    30     *  `xdc.runtime` modules). The fields of this structure are typically read
    31     *  by the modules in the `xdc.runtime` package at configuration time to
    32     *  control the generation of data structures that are embedded in the
    33     *  application and referenced by these modules at runtime.
    34     *
    35     *  Every module has a configuration parameter named
    36     *  `{@link #common$ common$}` that is of type `Common$`. This allows the user
    37     *  of any module to control the module's diagnostics, where its instances
    38     *  are allocated, how they are allocated, and (for gated modules) what
    39     *  gate it should use to protect critical sections.
    40     *
    41     *  @a(Examples)
    42     *  Configuration example: The following configuration script specifies
    43     *  that the instance objects managed by the `Memory` module in the
    44     *  `xdc.runtime` package should be placed in the ".fast" memory section
    45     *  and that `ENTRY` diagnostics should be available at runtime.
    46     *
    47     *  @p(code)
    48     *      var Memory = xdc.useModule('xdc.runtime.Memory");
    49     *      Memory.common$.instanceSection = ".fast";
    50     *      Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF
    51     *  @p
    52     *
    53     *  Note that by setting `Memory.common$.diags_ENTRY` to `Diags.RUNTIME_OFF`
    54     *  we are both enabling `ENTRY` events and specifying that they are initially
    55     *  disabled; they must be explicitly enabled at runtime. See the
    56     *  `{@link Diags}` modules for additional information.
    57     */
    58
    59    @CustomHeader
    60
    61    module Types {
    62
    63        /*!
    64         *  ======== ModuleId ========
    65         *  Unique module identifier
    66         *
    67         *  Module IDs are assigned at configuration time based in the set
    68         *  of modules that are "used" in the application.  So, although each
    69         *  module has a unique 16-bit ID at runtime this ID may vary between
    70         *  configurations of the application.
    71         *
    72         *  To save precious data space, module names are managed by the
    73         *  `{@link Text}` module and it is this table that is used to assign
    74         *  module IDs.  If the table is maintained on the target, the module ID
    75         *  is an "index" into this table; otherwise, the module ID is simply
    76         *  a unique integer less than the total number of modules in the
    77         *  application.
    78         *
    79         *  Although module IDs are not independent of an application's
    80         *  configuration, a module's ID may be compared to a runtime value
    81         *  symbolically.  Every module has a (generated) method that returns
    82         *  the module's ID; e.g., a module named `Task` has a method named
    83         *  `Task_Module_id()` which returns `Task`'s module ID.
    84         *
    85         *  @p(code)
    86         *      #include <xdc/runtime/Types.h>
    87         *      #include <ti/sysbios/knl/Task.h>
    88         *         :
    89         *      void checkId(Types_ModuleId modId) {
    90         *          if (Task_Module_id() == modId) {
    91         *              System_printf("Task module");
    92         *          }
    93         *      }
    94         *  @p
    95         */
    96        typedef Bits16 ModuleId;
    97
    98        typedef Bits16 DiagsMask;
    99
   100        /*!
   101         *  ======== Event ========
   102         *  `{@link ILogger}` event encoding
   103         *
   104         *  Whereas a `{@link Log#Event}` encodes an event ID and a mask, a
   105         *  `Types_Event` encodes the same event ID and the module ID of the
   106         *  module containing the call site that generated the `Types_Event`.
   107         */
   108        typedef Bits32 Event;
   109
   110        /*!
   111         *  ======== getEventId ========
   112         *  Get event ID of the specified event
   113         *
   114         *  This method is used to get an ID that can be compared to other
   115         *  "known" IDs.  For example, after a `{@link #Event Types_Event}` is
   116         *  generated, the following code determines if the event
   117         *  corresponds to a `{@link Log#L_create}` event:
   118         *  @p(code)
   119         *      Bool isCreateEvent(Types_Event evt) {
   120         *          return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
   121         *      }
   122         *  @p
   123         *
   124         *  @param(evt) an event created via `{@link #makeEvent}`
   125         *
   126         *  @a(returns) This function returns the event ID of a specified event.
   127         */
   128        @Macro RopeId getEventId(Event evt);
   129
   130        /*!
   131         *  ======== getModuleId ========
   132         *  Get the module ID for the specified event
   133         *
   134         *  @param(evt) an event created via `{@link #makeEvent}`
   135         *
   136         *  @a(returns) This function returns the module ID of a specified event.
   137         */
   138        @Macro ModuleId getModuleId(Event evt);
   139
   140        /*!
   141         *  ======== makeEvent ========
   142         *  Make an Event from an Event ID and a module ID
   143         *
   144         *  @param(id)          ID of the event itself
   145         *  @param(callSite)    the module from which this event originated
   146         *
   147         *  @a(returns) This function returns an event.
   148         */
   149        @Macro Event makeEvent(RopeId id, ModuleId callSite);
   150
   151        /*!
   152         *  ======== EventId ========
   153         *  @_nodoc
   154         *
   155         *  Deprecated name for `Types.Event`; ids are often encoded as a field
   156         *  in the event itself.
   157         */
   158        typedef Event EventId;
   159
   160        /*! @_nodoc */
   161        struct CordAddr__;
   162
   163        /*! @_nodoc */
   164        typedef CordAddr__ *CordAddr;
   165
   166        /*! @_nodoc */
   167        struct GateRef__;
   168
   169        /*! @_nodoc */
   170        typedef GateRef__ *GateRef;
   171
   172        /*! @_nodoc */
   173        typedef Bits16 RopeId;
   174
   175        /*!
   176         *  ======== CreatePolicy ========
   177         *  Instance creation policy
   178         */
   179        enum CreatePolicy {
   180            STATIC_POLICY,  /*! static creation only; no runtime create/delete */
   181            CREATE_POLICY,  /*! dynamic creation, but no deletion */
   182            DELETE_POLICY   /*! dynamic creation and deletion */
   183        };
   184
   185        /*!
   186         *  ======== Label ========
   187         *  Instance label struct
   188         *
   189         *  Label structures are used to provide human readable names for
   190         *  instance handles.
   191         *
   192         *  It is possible to initialize a `Label` from any instance handle.  All
   193         *  modules that support instances provide a method named
   194         *  `Mod_Handle_label()` which, given an instance handle and a pointer to
   195         *  a `Label` structure, initializes the structure with all available
   196         *  information.  For example, the following code fragment initializes a
   197         *  `Label` from an instance of the `HeapMin` module.
   198         *  @p(code)
   199         *      HeapMin_Handle heap;
   200         *      Types_Label label;
   201         *      HeapMin_Handle_label(heap, &label);
   202         *  @p
   203         *
   204         *  Unless you explicitly disable it, `{@link System#printf System_printf}`
   205         *  can be used to convert a pointer to a `Label` into an human readable
   206         *  "instance name".  Continuing with the example above, the following
   207         *  line can be used to print the an instance's label.
   208         *  @p(code)
   209         *      System_printf("heap instance name: %$L\n", &label);
   210         *  @p
   211         *
   212         *  @see System#printf, System#extendedFormats
   213         *  @see Text#putLabel
   214         */
   215        struct Label {
   216            Ptr handle;         /*! instance object address */
   217            ModuleId modId;     /*! corresponding module id */
   218            String iname;       /*! name supplied during instance creation */
   219            Bool named;         /*! true, if `iname` is available */
   220        };
   221
   222        /*!
   223         *  ======== Site ========
   224         *  Error site description struct
   225         *
   226         *  This structure describes the location of the line that raised
   227         *  an error.
   228         *
   229         *  @field(mod) the module id of the module containing the call site
   230         *  @field(file) the name of the file containing the call site or `NULL`;
   231         *               some call sites omit the file name to save data space.
   232         *  @field(line) the line number within the file named
   233         */
   234        struct Site {
   235            ModuleId mod;   /*! module id of this site */
   236            String file;    /*! filename of this site */
   237            Int line;       /*! line number of this site */
   238        };
   239
   240        /*!
   241         *  ======== Timestamp64 ========
   242         *  64-bit timestamp struct
   243         *
   244         *  Some platforms only support 32-bit timestamps.  In this case,
   245         *  the most significant 32-bits are always set to 0.
   246         */
   247        struct Timestamp64 {
   248            Bits32 hi;      /*! most significant 32-bits of timestamp */
   249            Bits32 lo;      /*! least significant 32-bits of timestamp */
   250        };
   251
   252        /*!
   253         *  ======== FreqHz ========
   254         *  Frequency-in-hertz struct
   255         */
   256        struct FreqHz {
   257            Bits32 hi;      /*! most significant 32-bits of frequency */
   258            Bits32 lo;      /*! least significant 32-bits of frequency */
   259        };
   260
   261        /*!
   262         *  ======== RegDesc ========
   263         *  Registry module descriptor
   264         */
   265        struct RegDesc {
   266            RegDesc         *next;
   267            String          modName;
   268            Types.ModuleId  id;
   269            DiagsMask      mask;
   270        };
   271
   272        /*!
   273         *  ======== Common$ ========
   274         *  Common module config struct
   275         *
   276         *  Every module contains this structure during the configuration
   277         *  phase. The fields of this structure are set in configuration scripts
   278         *  and referenced by the modules in the `xdc.runtime` package. For default
   279         *  values of these fields, see `{@link Defaults}`.
   280         *
   281         *  @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's
   282         *  diagnostics mask.
   283         *
   284         *  @field(diags_ENTRY) The `{@link Diags#ENTRY}` category of a module's
   285         *  diagnostics mask.
   286         *
   287         *  @field(diags_EXIT) The `{@link Diags#EXIT}` category of a module's
   288         *  diagnostics mask.
   289         *
   290         *  @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's
   291         *  diagnostics mask.
   292         *
   293         *  @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` category of a
   294         *  module's diagnostics mask.
   295         *
   296         *  @field(diags_STATUS) The `{@link Diags#STATUS}` category of a module's
   297         *  diagnostics mask.
   298         *
   299         *  @field(diags_USER1) The `{@link Diags#USER1}` category of a module's
   300         *  diagnostics mask.
   301         *
   302         *  @field(diags_USER2) The `{@link Diags#USER2}` category of a module's
   303         *  diagnostics mask.
   304         *
   305         *  @field(diags_USER3) The `{@link Diags#USER3}` category of a module's
   306         *  diagnostics mask.
   307         *
   308         *  @field(diags_USER4) The `{@link Diags#USER4}` category of a module's
   309         *  diagnostics mask.
   310         *
   311         *  @field(diags_USER5) The `{@link Diags#USER5}` category of a module's
   312         *  diagnostics mask.
   313         *
   314         *  @field(diags_USER6) The `{@link Diags#USER6}` category of a module's
   315         *  diagnostics mask.
   316         *
   317         *  @field(diags_USER7) The `{@link Diags#USER7}` category of a module's
   318         *  diagnostics mask. The bit for this category has been repurposed for the
   319         *  `{@link Diags#INFO}` category, so the use of USER7 has been deprecated.
   320         *
   321         *  @field(diags_INFO) The `{@link Diags#INFO}` category of a module's
   322         *  diagnostics mask.
   323         *
   324         *  @field(diags_USER8) The `{@link Diags#USER8}` category of a module's
   325         *  diagnostics mask. The bit for this category has been repurposed for the
   326         *  `{@link Diags#ANALYSIS}` category, so the use of USER8 has been
   327         *  deprecated.
   328         *
   329         *  @field(diags_ANALYSIS) The `{@link Diags#ANALYSIS}` category of a
   330         *  module's diagnostics mask.
   331         *
   332         *  @field(fxntab)
   333         *  This configurtation parameter is only applicable to modules that
   334         *  inherit an interface and have instance objects.  Setting `fxntab`
   335         *  to `false` can save some data space but also prevents the
   336         *  application from using instance objects through abstract interfaces.
   337         *
   338         *  Function tables are used whenever it's necessary to call a module's
   339         *  methods via an abstract interface; e.g., the `{@link Memory}` module
   340         *  calls methods defined by the `{@link IHeap}` interface but there may
   341         *  be several distinct modules that implement this interface.  In order
   342         *  for this type of call to be possible, instance objects contain a
   343         *  reference to a function table containing the instance module's
   344         *  functions; the caller gets the module's function from the instance
   345         *  object and calls through a function pointer.  Every module that
   346         *  inherits an interface has such a table and modules that do not
   347         *  inherit an interface do not have a function table.
   348         *
   349         *  If this configuration parameter is set to `false`, the module's
   350         *  instance objects will NOT be initialized with a reference to their
   351         *  module's function table and, since the function table will not
   352         *  be referenced by the application, the resulting executable will be
   353         *  smaller.  However, if this parameter is `false` you must never
   354         *  attempt to use this module's instance objects via reference this
   355         *  module through an abstract interface.  Since this is often hard to
   356         *  determine, especially as an application evolves over time, you should
   357         *  only set this parameter to `false` when you are absolutely sure that
   358         *  the module's functions are always only being directly called and you
   359         *  need to absolutely minimize the data footprint of your application.
   360         *
   361         *  The default for this parameter is `true`.
   362         *
   363         *  @field(gate) A handle to the module-level `{@link IGateProvider}`
   364         *  instance to be used when this module calls functions from
   365         *  `{@link Gate}`
   366         *
   367         *  @field(gateParams) `Gate` parameters used by this module to create
   368         *  the gates used when this module calls
   369         *  `{@link Gate#allocInstance() Gate_allocInstance}`
   370         *
   371         *  @field(instanceHeap) Identifies the heap from which this module
   372         *  should allocate memory.
   373         *
   374         *  @field(instanceSection) Identifies the section in which instances
   375         *  created by this module should be placed.
   376         *
   377         *  @field(logger) The handle of the logger instance used by the module.
   378         *  All log events generated by the module are routed to this logger
   379         *  instance. See `{@link ILogger}` for details on the logger interface.
   380         *  See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of
   381         *  logger modules provided by the `{@link xdc.runtime}` package.
   382         *
   383         *  @field(memoryPolicy) Specifies whether this module should allow
   384         *  static object creation only (`{@link #CreatePolicy STATIC_POLICY}`),
   385         *  dynamic object creation but not deletion
   386         *  (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object
   387         *  creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`).
   388         *
   389         *  @field(namedInstance) If set to `true`, each instance object is
   390         *  given an additional field to hold a string name that is used
   391         *  when displaying information about an instance. Setting this to
   392         *  true increases the size of the module's instance objects by a
   393         *  single word but improves the usability of tools that display
   394         *  instance objects.  If set to 'false', assignments of instance
   395         *  names are silently ignored.  This allows one to remove instance
   396         *  name support to save space without having to change any source code.
   397         *  See `{@link xdc.runtime.IInstance#name IInstance.name}` for details.
   398         *
   399         *  @field(namedModule) If set to `true`, this module's string name
   400         *  is retained on the target so that it can be displayed as part
   401         *  of `{@link Log}` and `{@link Error}` events. Setting this to `false`
   402         *  saves data space in the application at the expense of readability
   403         *  of log and error messages associated with this module.
   404         *
   405         *  Note: setting this to `false` also prevents one from controlling the
   406         *  module's diagnostics at runtime via `{@link Diags#setMask()}`.
   407         *  This method uses the module's name to lookup the module's
   408         *  diagnostics mask.  It is still possible to control the module's
   409         *  diagnostics at design-time from a configuration script.
   410         *
   411         *  @see Diags, Defaults
   412         */
   413        metaonly struct Common$ {
   414            Diags.Mode diags_ASSERT;    /*! module's Diags assert mode */
   415            Diags.Mode diags_ENTRY;     /*! module's function entry Diags mode */
   416            Diags.Mode diags_EXIT;      /*! module's function exit Diags mode */
   417            Diags.Mode diags_INTERNAL;  /*! module's internal assert mode */
   418            Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */
   419            Diags.Mode diags_STATUS;    /*! module's errors and warnings */
   420            Diags.Mode diags_USER1;     /*! module's user1 Diags mode */
   421            Diags.Mode diags_USER2;     /*! module's user2 Diags mode */
   422            Diags.Mode diags_USER3;     /*! module's user3 Diags mode */
   423            Diags.Mode diags_USER4;     /*! module's user4 Diags mode */
   424            Diags.Mode diags_USER5;     /*! module's user5 Diags mode */
   425            Diags.Mode diags_USER6;     /*! module's user6 Diags mode */
   426            Diags.Mode diags_USER7;     /*! module's user7 Diags mode */
   427            Diags.Mode diags_INFO;      /*! module's informational event mode */
   428            Diags.Mode diags_USER8;     /*! module's user8 Diags mode */
   429            Diags.Mode diags_ANALYSIS;  /*! module's Diags analysis mode */
   430            Bool fxntab;                /*! @_nodoc enable function tables */
   431            IGateProvider.Handle gate;  /*! module's gate */
   432            Ptr gateParams;             /*! gate params for module created gates */
   433            IHeap.Handle instanceHeap;  /*! module's instance heap */
   434            String instanceSection;     /*! memory section for module's instances*/
   435            ILogger.Handle logger;      /*! module's logger */
   436            CreatePolicy memoryPolicy;  /*! module's memory policy */
   437            Bool namedInstance;         /*! true => instances have string names */
   438            Bool namedModule;           /*! true => module's name is on target */
   439            Bool romPatchTable;         /*! @_nodoc */
   440        }
   441
   442        /*!
   443         *  ======== RtaDecoderData ========
   444         *  @_nodoc
   445         *
   446         *  loggers
   447         *    name - Used to identify the logger in GUI
   448         *    bufferSym - For stop-mode; symbol at which the logger's entry
   449         *                buffer can be found
   450         *    bufferLen - For stop-mode; length of the logger's entry buffer in
   451         *                MAUs
   452         */
   453        @XmlDtd metaonly struct RtaDecoderData {
   454            String targetName;
   455            String binaryParser;
   456            String endian;
   457            Int bitsPerChar;
   458            Int argSize;
   459            Int eventSize;
   460            String dataTransportClassName;
   461            String controlTransportClassName;
   462            struct {
   463                String name;
   464                String type;
   465                Any metaArgs;
   466            } loggers[ ];
   467            struct {
   468                Int id;
   469                String logger;
   470                String diagsMask;
   471            } modMap[string];
   472            struct {
   473                Int id;
   474                String msg;
   475            } evtMap[string];
   476        };
   477
   478        /*!
   479         *  ======== ViewInfo ========
   480         *  @_nodoc
   481         *  XGconf view descriptor.
   482         */
   483        metaonly struct ViewInfo {
   484            String viewType;
   485            String viewFxn;
   486            String fields[];
   487        }
   488
   489    internal:
   490
   491        typedef Bits32 LogEvent;
   492
   493        typedef Void (*LoggerFxn0)(Ptr, LogEvent, ModuleId);
   494        typedef Void (*LoggerFxn1)(Ptr, LogEvent, ModuleId, IArg);
   495        typedef Void (*LoggerFxn2)(Ptr, LogEvent, ModuleId, IArg, IArg);
   496        typedef Void (*LoggerFxn4)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg);
   497        typedef Void (*LoggerFxn8)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg,
   498                                   IArg, IArg, IArg, IArg);
   499
   500        struct Vec {
   501            Int len;
   502            Ptr arr;
   503        };
   504
   505        /*
   506         *  ======== Link ========
   507         *  Link used to maintain atomic linked lists
   508         */
   509        struct Link {
   510            Link *next;
   511            Link *prev;
   512        };
   513
   514        /*
   515         *  ======== InstHdr ========
   516         *  Header for all runtime created instance objects
   517         */
   518        struct InstHdr {
   519            Link link;
   520        }
   521
   522        /*
   523         *  ======== PrmsHdr ========
   524         *  Header for all _Params structures
   525         */
   526        struct PrmsHdr {
   527            SizeT size;     /* size of the entire parameter structure */
   528            Ptr self;       /* pointer to self; used to check params are init'd */
   529            Ptr modFxns;
   530            Ptr instPrms;
   531        }
   532
   533        /*
   534         *  ======== Base ========
   535         *  Header for all module vtables
   536         */
   537        struct Base {
   538            Base *base;     /* points to inherited interface base */
   539        }
   540
   541        /*
   542         *  ======== SysFxns ========
   543         *  Deprecated.  Use SysFxns2 instead
   544         */
   545        struct SysFxns {
   546            Ptr (*__create)(Ptr, SizeT, const Ptr, const Ptr, SizeT, Error.Block*);
   547            Void (*__delete)(Ptr);
   548            Label *(*__label)(Ptr, Label *);
   549            ModuleId __mid;
   550        }
   551
   552        /*
   553         *  ======== SysFxns2 ========
   554         *  System data embedded in module's vtable
   555         */
   556        struct SysFxns2 {
   557            Ptr (*__create)(Ptr, SizeT, const Ptr, const UChar *, SizeT, Error.Block *);
   558            Void (*__delete)(Ptr);
   559            Label *(*__label)(Ptr, Label *);
   560            ModuleId __mid;
   561        }
   562
   563    }
   564    /*
   565     *  @(#) xdc.runtime; 2, 1, 0,337; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   566     */
   567


module xdc.runtime.knl.Cache

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Cache.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18    import xdc.runtime.knl.ICacheSupport;
    19
    20    /*!
    21     *  ======== Cache ========
    22     *  Cache Services
    23     *
    24     *  The Cache module provide APIs to allow applications to maintain cache
    25     *  coherency.
    26     *
    27     *  This module will use an OS specific delegate (back-end) to manipulate the
    28     *  cache.
    29     *  This module has a module wide config parameter {@link #Proxy} which needs to
    30     *  be bound to an OS specific delegate before this module can be used.
    31     *
    32     *  Here is an example showing how the proxy is bound to an BIOS 6.x specific
    33     *  delegate.
    34     *
    35     *  @p(code)
    36     *  var Cache = xdc.useModule('xdc.runtime.knl.Cache');
    37     *  Cache.Proxy = xdc.useModule('ti.sysbios.xdcruntime.CacheSupport');
    38     *  @p
    39     *
    40     *  Typically the package containing the delegates have a Settings module that
    41     *  will bind all {@link xdc.runtime.knl} proxies. The following
    42     *  example sets up all the xdc.runtime.knl proxies.
    43     *
    44     *  @p(code)
    45     *  xdc.useModule("ti.sysbios.xdcruntime.Settings");
    46     *  @p
    47     */
    48
    49    module Cache
    50    {
    51        /*!
    52         *  ======== Proxy ========
    53         *  ICacheSupport proxy
    54         *
    55         *  Cache will use this proxy to access the cache hardware using
    56         *  OS specific APIs.
    57         */
    58        proxy Proxy inherits ICacheSupport;
    59
    60        /*!
    61         *  ======== inv ========
    62         *  Invalidate range of memory for all cache(s)
    63         *
    64         *  Invalidate the range of memory within the specified starting
    65         *  address and byte count.  The range of addresses operated on
    66         *  gets quantized to whole cache lines in each cache.  All lines
    67         *  in range are invalidated for all cache types.
    68         *
    69         *  @param(blockPtr) start address of range to be invalidated
    70         *  @param(byteCnt)  number of bytes to be invalidated
    71         *  @param(wait)     wait until the operation is completed
    72         *  @param(eb)       error block
    73         *  @a(returns)  true for success; false for error.
    74         */
    75        Bool inv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    76
    77        /*!
    78         *  ======== wb ========
    79         *  Writes back a range of memory from all cache(s)
    80         *
    81         *  Writes back the range of memory within the specified starting
    82         *  address and byte count.  The range of addresses operated on
    83         *  gets quantized to whole cache lines in each cache.  All lines
    84         *  within the range are left valid in all caches and the data
    85         *  within the range will be written back to the source memory.
    86         *
    87         *  @param(blockPtr) start address of range to be invalidated
    88         *  @param(byteCnt)  number of bytes to be invalidated
    89         *  @param(wait)     wait until the operation is completed
    90         *  @param(eb)       error block
    91         *  @a(returns)  true for success; false for error.
    92         */
    93        Bool wb(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    94
    95        /*!
    96         *  ======== wbInv ========
    97         *  Write back and invalidate range of memory.
    98         *
    99         *  Writes back and invalidates the range of memory within the
   100         *  specified starting address and byte count.  The range of
   101         *  addresses operated on gets quantized to whole cache lines in
   102         *  each cache.  All lines within the range are written back to the
   103         *  source memory and then invalidated for all cache types.
   104         *
   105         *  @param(blockPtr) start address of range to be invalidated
   106         *  @param(byteCnt)  number of bytes to be invalidated
   107         *  @param(wait)     wait until the operation is completed
   108         *  @param(eb)       error block
   109         *  @a(returns)  true for success; false for error.
   110         */
   111        Bool wbInv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
   112
   113        /*!
   114         *  ======== wait ========
   115         *  Wait for a previous cache operation to complete
   116         *
   117         *  Wait for the cache wb/wbInv/inv operation to complete.  A cache
   118         *  operation is not truly complete until it has worked its way
   119         *  through all buffering and all memory writes have landed in the
   120         *  source memory.
   121         *
   122         *  @param(eb)       error block
   123         *  @a(returns)  true for success; false for error.
   124         */
   125        Bool wait(Error.Block *eb);
   126    }
   127    /*
   128     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   129     */
   130


module xdc.runtime.knl.CacheSupportNull

     1    /*!
     2     *  ======== CacheSupport.xdc ========
     3     *  Empty ICacheSupport implementation
     4     */
     5
     6    module CacheSupportNull inherits ICacheSupport
     7    {
     8
     9    }
    10    /*
    11     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    12     */
    13


module xdc.runtime.knl.GateH

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== GateH.xdc ========
    15     */
    16
    17    import xdc.runtime.IGateProvider;
    18
    19    /*!
    20     *  ======== GateH ========
    21     *  Provides APIs to protect critical sections when an IGate.Handle is
    22     *  available.
    23     *
    24      * An application can isolate itself from IGate implementations by using
    25     *  this module. The application must first obtain an IGate.Handle.
    26     *  It can get such a handle by directly calling {@link GateThread#create} or
    27     *  {@link GateProcess#create}. Then the application can use the generic
    28     *  APIs provided by this module.
    29     *
    30     *  The underlying gates are nexting in nature and users have to leave
    31     *  the gate as many times as they entered it.
    32     */
    33
    34    module GateH
    35    {
    36        /*!
    37         *  Proxy used for optimization.
    38         *
    39         *  If ALL IGateProvider.Handles used by GateH are created using the same
    40         *  module (e.g GateProcess) then setting this Proxy to GateProcess and
    41         *  setting GateH.Proxy.abstractInstances$ = false, causes
    42         *  GateH APIs can have better performance.
    43         */
    44        proxy Proxy inherits IGateProvider;
    45
    46        /*!
    47         * ======== enter ========
    48         * Enter a gate
    49         *
    50         * @param(hdl)    IGateProvider.Handle
    51         * @a(returns)    key
    52         */
    53        IArg enter(IGateProvider.Handle hdl);
    54
    55        /*!
    56         * ======== leave ========
    57         * Leave a gate
    58         *
    59         * @param(hdl)    IGateProvider.Handle
    60         * @param(key)    key returned by enter();
    61         */
    62        Void leave(IGateProvider.Handle hdl, IArg key);
    63    }
    64    /*
    65     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    66     */
    67


module xdc.runtime.knl.GateProcess

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== GateProcess.xdc ========
    15     */
    16
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.Error;
    19    import xdc.runtime.IGateProvider;
    20    import xdc.runtime.knl.IGateProcessSupport;
    21
    22    /*!
    23     *  ======== GateProcess ========
    24     *  Provides protection of critical sections across processes.
    25     *
    26     *  This module provides services through its proxy
    27     *  IGateProcessSupport interface. It has a module wide config parameter
    28     *  {@link #Proxy} which needs to be bound to an OS specific delegate before
    29     *  this module can be used.
    30     *
    31     *  Here is an example showing how the proxy is bound to an BIOS 6.x specific
    32     *  delegate.
    33     *
    34     *  @p(code)
    35     *  var GateProcess = xdc.useModule('xdc.runtime.knl.GateProcess');
    36     *  GateProcess.Proxy =
    37     *      xdc.useModule('ti.sysbios.xdcruntime.GateProcessSupport');
    38     *  @p
    39     *
    40     *  Typically the package containing the delegates have a Settings module that
    41     *  will bind all {@link xdc.runtime.knl} proxies. The following
    42     *  example sets up all the xdc.runtime.knl proxies.
    43     *
    44     *  @p(code)
    45     *  xdc.useModule("ti.sysbios.xdcruntime.Settings");
    46     *  @p
    47     */
    48    @InstanceInitError      /* because initialization can fail */
    49    @InstanceFinalize       /* have to GateProcess_Proxy_delete(gate) on delete */
    50
    51    module GateProcess inherits IGateProvider
    52    {
    53        /*! Status returned by {@link #getReferenceCount} when there is an error */
    54        const Int GETREFCOUNT_FAILED = -1;
    55
    56        /*! Proxy that needs to be bound to an OS specific delegate. */
    57        proxy Proxy inherits IGateProcessSupport;
    58
    59        /*! Assert when  an invalid key is passed to create */
    60        config Assert.Id A_invalidKey = {
    61            msg: "A_invalidKey: the key must be set to a non-default value"
    62        };
    63
    64    instance:
    65
    66        /*!
    67         *  globally unique key for SysV-style semaphore
    68         *
    69         *  This is a required parameter.
    70         */
    71        config Int key = -1;
    72
    73       /*!
    74        *  ======== create ========
    75        *  Create a GateProcess object.
    76        *
    77        *  This function creates a new `GateProcess` object which is initialized to
    78        *  count.  All gates created with the same key reference the same
    79        *  underlying synchronization object and work between processes.  For
    80        *  compatibility with the IGateProvider interface the argument key is
    81        *  passes in the params struct rather than as a full argument, but it is
    82        *  required.  Therefore calling this function with a `NULL` params struct
    83        *  is illegal.
    84        */
    85        override create();
    86
    87        /*!
    88         *  ======== getReferenceCount ========
    89         *  Get the number of processes with references to this Gate.
    90         *
    91         *  @param(eb)        Pointer to Error.Block
    92         *  @a(returns)       Returns the number of processes that possess a
    93         *                    reference to this gate, or GETREFCOUNT_FAILED if an
    94         *            error occured.
    95         */
    96        Int getReferenceCount(Error.Block *eb);
    97
    98    internal:
    99
   100        struct Instance_State {
   101            Proxy.Handle proxyHandle;
   102        }
   103    }
   104    /*
   105     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   106     */
   107


module xdc.runtime.knl.GateProcessSupportNull

     1    /*!
     2     *  ======== GateProcessSupportNull.xdc ========
     3     *  Empty IGateProcessSupport implementation
     4     */
     5
     6    module GateProcessSupportNull inherits IGateProcessSupport
     7    {
     8    }
     9    /*
    10     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    11     */
    12


module xdc.runtime.knl.GateThread

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== GateThread.xdc ========
    15     */
    16
    17    import xdc.runtime.IGateProvider;
    18    import xdc.runtime.knl.IGateThreadSupport;
    19
    20    /*!
    21     *  ======== GateThread ========
    22     *  Provides protection of critical sections across threads.
    23     *
    24     *  This module provides services through its proxy
    25     *  IGateThreadSupport interface. It has a module wide config parameter
    26     *  {@link #Proxy} which needs to be bound to an OS specific delegate before
    27     *  this module can be used.
    28     *
    29     *  Here is an example showing how the proxy is bound to an BIOS 6.x specific
    30     *  delegate.
    31     *
    32     *  @p(code)
    33     *  var GateThread = xdc.useModule('xdc.runtime.knl.GateThread');
    34     *  GateThread.Proxy =
    35     *      xdc.useModule('ti.sysbios.xdcruntime.GateThreadSupport');
    36     *  @p
    37     *
    38     *  Typically the package containing the delegates have a Settings module that
    39     *  will bind all {@link xdc.runtime.knl} proxies. The following
    40     *  example sets up all the xdc.runtime.knl proxies.
    41     *
    42     *  @p(code)
    43     *  xdc.useModule("ti.sysbios.xdcruntime.Settings");
    44     *  @p
    45     */
    46
    47    @InstanceInitError      /* because initialization can fail */
    48    @InstanceFinalize       /* have to Gate_Proxy_delete(sem) on delete */
    49
    50    module GateThread inherits IGateProvider
    51    {
    52        /*! Proxy that needs to be bound to an OS specific delegate. */
    53        proxy Proxy inherits IGateThreadSupport;
    54
    55    internal:
    56
    57        struct Instance_State {
    58            Proxy.Handle proxyHandle;
    59        }
    60
    61    }
    62    /*
    63     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    64     */
    65


module xdc.runtime.knl.GateThreadSupportNull

     1    /*!
     2     *  ======== GateThreadSupportNull.xdc ========
     3     *  Empty IGateProcessSupport implementation
     4     */
     5
     6    module GateThreadSupportNull inherits IGateThreadSupport
     7    {
     8    }
     9    /*
    10     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    11     */
    12


interface xdc.runtime.knl.ICacheSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ICacheSupport.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18
    19    /*!
    20     *  ======== ICacheSupport ========
    21     *  Interface for OS specific back-end.
    22     *
    23     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    24     *  OS services. These xdc.runtime.knl modules require proxies to be
    25     *  bound to an OS specific delegate. This specifies the interface to
    26     *  be implemented by the OS specific delegate for
    27     *  {@link xdc.runtime.knl#Cache} module.
    28     *
    29     */
    30
    31    interface ICacheSupport
    32    {
    33        /*!
    34         *  ======== inv ========
    35         *  Invalidates range of memory.
    36         *
    37         *  Invalidate the range of memory within the specified starting
    38         *  address and byte count.  The range of addresses operated on
    39         *  gets quantized to whole cache lines in each cache.  All lines
    40         *  in range are invalidated for all the 'type' caches.
    41         *
    42         *  @param(blockPtr) start address of range to be invalidated
    43         *  @param(byteCnt)  number of bytes to be invalidated
    44         *  @param(wait)     wait until the operation is completed
    45         *  @param(eb)       error block
    46         *  @a(returns)  true for success; false for error.
    47         */
    48        Bool inv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    49
    50        /*!
    51         *  ======== wb ========
    52         *  Writes a range of memory from all cache(s)
    53         *
    54         *  Writes the range of memory within the specified starting
    55         *  address and byte count.  The range of addresses operated on
    56         *  gets quantized to whole cache lines in each cache.  All lines
    57         *  within the range are left valid in the 'type' caches and the data
    58         *  within the range will be written      to the source memory.
    59         *
    60         *  @param(blockPtr) start address of range to be invalidated
    61         *  @param(byteCnt)  number of bytes to be invalidated
    62         *  @param(wait)     wait until the operation is completed
    63         *  @param(eb)       error block
    64         *  @a(returns)  true for success; false for error.
    65         */
    66        Bool wb(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    67
    68        /*!
    69         *  ======== wbInv ========
    70         *  Writes back and invalidates range fo memory.
    71         *
    72         *  Writes and invalidates the range of memory within the
    73         *  specified starting address and byte count.  The range of
    74         *  addresses operated on gets quantized to whole cache lines in
    75         *  each cache.  All lines within the range are written      to the
    76         *  source memory and then invalidated for all 'type' caches.
    77         *
    78         *  @param(blockPtr) start address of range to be invalidated
    79         *  @param(byteCnt)  number of bytes to be invalidated
    80         *  @param(wait)     wait until the operation is completed
    81         *  @param(eb)       error block
    82         *  @a(returns)  true for success; false for error.
    83         */
    84        Bool wbInv(Ptr blockPtr, SizeT byteCnt, Bool wait, Error.Block *eb);
    85
    86        /*!
    87         *  ======== wait ========
    88         *  Wait for a previous cache operation to complete
    89         *
    90         *  Wait for the cache wb/wbInv/inv operation to complete.  A cache
    91         *  operation is not truly complete until it has worked its way
    92         *  through all buffering and all memory writes have landed in the
    93         *  source memory.
    94         *
    95         *  @a(returns)  true for success; false for error.
    96         */
    97        Bool wait(Error.Block *eb);
    98
    99    }
   100    /*
   101     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   102     */
   103


interface xdc.runtime.knl.IGateProcessSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IGateProcessSupport.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18
    19    /*!
    20     *  ======== IGateProcessSupport ========
    21     *  Interface for OS specific back-end.
    22     *
    23     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    24     *  OS services. These xdc.runtime.knl modules require proxies to be
    25     *  bound to an OS specific delegate. This specifies the interface to
    26     *  be implemented by the OS specific delegate for
    27     *  {@link xdc.runtime.knl#GateProcess} module.
    28     *
    29     *  The implementation of IGateThreadSupport should try to implement a gate
    30     *  that supports priority inversion.
    31     */
    32    interface IGateProcessSupport inherits IGateThreadSupport
    33    {
    34
    35        /*! Status returned by {@link #getReferenceCount} when there is an error */
    36        const Int GETREFCOUNT_FAILED = -1;
    37
    38    instance:
    39
    40        config Int key = -1; /*! globally unique key for SysV-style semaphore */
    41
    42       /*!
    43        *  ======== create ========
    44        *  Create a GateProcess object.
    45        *
    46        *  This function creates a new `GateProcess` object which is initialized to
    47        *  count.  All gates created with the same key reference the same
    48        *  underlying synchronization object and work between processes.  The
    49        *  underlying synchronization object should be automatically deleted when
    50        *  all references to it have been deleted, and the reference count should
    51        *  An implementation for a platform on which this is technically impossible
    52        *  (e.g. an operating system that does not support multiple processes) may
    53        *  provide a 'toy' implemenation with behavior matching that of
    54        *  IGateProcessSupport.
    55        */
    56        override create();
    57
    58        /*!
    59         *  ======== getReferenceCount ========
    60         *  Get the number of processes with references to this Gate.
    61         *
    62         *  @param(err)     Pointer to Error.Block
    63         *  @a(returns)     Returns the number of processes that possess a
    64         *          reference to this gate, or GETREFCOUNT_FAILED if an
    65         *          error occured.
    66         *                  A 'toy' implementation should always return 0.
    67         */
    68        Int getReferenceCount(Error.Block* err);
    69
    70    }
    71    /*
    72     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    73     */
    74


interface xdc.runtime.knl.IGateThreadSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IGateThreadSupport.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== IGateThreadSupport ========
    19     *  Interface for OS specific back-end.
    20     *
    21     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    22     *  OS services. These xdc.runtime.knl modules require proxies to be
    23     *  bound to an OS specific delegate. This specifies the interface to
    24     *  be implemented by the OS specific delegate for
    25     *  {@link xdc.runtime.knl#GateThread} module.
    26     *
    27     *  The implementation of IGateThreadSupport should try to implement a gate
    28     *  that supports priority inversion.
    29     *
    30     *  See {@link xdc.runtime.knl} for more details.
    31     */
    32    interface IGateThreadSupport inherits xdc.runtime.IGateProvider
    33    {
    34
    35    }
    36    /*
    37     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    38     */
    39


interface xdc.runtime.knl.ISemaphore

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13
    14    /*
    15     *  ======== ISemaphore.xdc ========
    16     */
    17
    18    import xdc.runtime.Error;
    19
    20    /*!
    21     *  ======== ISemaphore ========
    22     *  Interface implemented by all front-end semaphore providers.
    23     *
    24     *  {@link #SemThread} and {@link #SemProcess}. [EXPERIMENTAL]
    25     *  Semaphores can be used for synchronization and mutual exclusion.
    26     *
    27     *  pend() is used to wait for a semaphore. The timeout parameter allows the
    28     *  caller to wait until a timeout, wait indefinitely, or not wait at all.
    29     *  The return value indicates whether or not the wait was successful.
    30     *
    31     *  post() is used to signal a semaphore. If no thread is waiting on the
    32     *  semaphore, then post() increments the semaphore count (for binary
    33     *  semaphores, the count is always 0 or 1).
    34     *
    35     */
    36    interface ISemaphore {
    37
    38        /*!
    39         *  ======== PendStatus ========
    40         *  Error codes returned by Semaphore_pend
    41         */
    42        enum PendStatus {
    43            PendStatus_ERROR = -1,
    44            PendStatus_TIMEOUT = 0,
    45            PendStatus_SUCCESS = 1
    46        };
    47
    48        /*! Used as the timeout value to specify wait forever */
    49        const UInt FOREVER = ~(0);
    50
    51        /*! Types of semaphores. */
    52        enum Mode {
    53            Mode_COUNTING,  /*! Counting semaphore. */
    54            Mode_BINARY     /*! Binary Semaphore. */
    55        };
    56
    57    instance:
    58
    59        /*!
    60         *  ======== mode ========
    61         *  Semaphore mode. Default is COUNTING.
    62         *
    63         *  When mode is BINARY , the semaphore has only two states, available
    64         *  and unavailable. When mode is COUNTING, the semaphore keeps track of
    65         *  number of times a semaphore is posted.
    66         */
    67        config Mode mode = Mode_COUNTING;
    68
    69        /*!
    70         *  ======== pend ========
    71         *  Wait for the semaphore to become available.
    72         *
    73         *  @p(blist)
    74         *  -{@link #PendStatus_ERROR} if an error occured.
    75         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    76         *  -{@link #PendStatus_SUCCESS} semaphore was decremented.
    77         *    details.
    78         *  @p
    79         *
    80         *  @param(timeout) timeout in microseconds
    81         *  @param(eb)      error block
    82         *  @a(returns)     refer to description above
    83         */
    84        Int pend(UInt timeout, Error.Block *eb);
    85
    86        /*!
    87         *  ======== post ========
    88         *  Increment the semaphore count.
    89         *
    90         *  @param(eb)      error block
    91         *  @a(returns)     true for success, false for error in error block
    92         */
    93        Bool post(Error.Block *eb);
    94    }
    95    /*
    96     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    97     */
    98


interface xdc.runtime.knl.ISemProcessSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ISemProcessSupport.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18
    19    /*!
    20     *  ======== ISemProcessSupport ========
    21     *  Interface for OS specific back-end.
    22     *
    23     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    24     *  OS services. These xdc.runtime.knl modules however require proxies to be
    25     *  bound to an OS specific delegate. This specifies the interface to
    26     *  be implemented by the OS specific delegate for
    27     *  {@link xdc.runtime.knl#SemProcess} module.
    28     *
    29     *  create() takes a 32-bit integer key parameter to be used for identifying
    30     *  the semaphore to create across processes. For example, for Linux System V
    31     *  semaphores, the key is necessary so that different processes can access
    32     *  the same semaphore.
    33     */
    34    interface ISemProcessSupport inherits ISemaphore
    35    {
    36
    37    instance:
    38
    39       /*!
    40        *  ======== create ========
    41        *  Create a SemProcess object.
    42        *
    43        *  This function creates a new `SemProcess` object which is
    44        *  initialized to count.
    45        *  All semaphores created with the same key reference the same
    46        *  underlying synchronization object and work between processes.  The
    47        *  underlying synchronization object should be automatically deleted when
    48        *  all references to it have been deleted, and the reference count should
    49        *  be maintained consistently across process forks or similar operations.
    50        *  An implementation for a platform on which this is technically impossible
    51        *  (e.g. an operating system that does not support multiple processes) may
    52        *  provide a 'toy' implementation with behavior matching that of
    53        *  `{@link ISemProcessSupport}`.
    54        *
    55        *  @param(count)    initial semaphore count
    56        *  @param(key)      globally unique key
    57        */
    58        create(Int count, Int key);
    59
    60    }
    61    /*
    62     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    63     */
    64


interface xdc.runtime.knl.ISemThreadSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ISemThreadSupport.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== ISemThreadSupport ========
    19     *  Interface for OS specific back-end.
    20     *
    21     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    22     *  OS services. These xdc.runtime.knl modules require proxies to be
    23     *  bound to an OS specific delegate. This specifies the interface to
    24     *  be implemented by the OS specific delegate for
    25     *  {@link xdc.runtime.knl#SemThread} module.
    26     *
    27     *  This interface adds the create() function.
    28     */
    29    interface ISemThreadSupport inherits ISemaphore
    30    {
    31
    32    instance:
    33
    34       /*!
    35        *  ======== create ========
    36        *  Create a Semaphore object
    37        *
    38        *  This function creates a new Semaphore object which is initialized to
    39        *  count.
    40        *
    41        *  @param(count)    initial semaphore count
    42        */
    43        create(Int count);
    44    }
    45    /*
    46     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    47     */
    48


interface xdc.runtime.knl.ISync

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== ISync.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18
    19    /*!
    20     *  ======== ISync ========
    21     *  OS independent synchronization
    22     *
    23     *  This interface allows clients to select method of synchronization in an OS
    24     *  independent way.
    25     *
    26     *  Modules that require the user to pick a synchronization method, will
    27     *  request a `{@link #Handle}`. Clients of such modules can pick a blocking
    28     *  `ISync` implementation  or a non-blocking implementation.
    29     *
    30     *  This interface specifies two main functions `{@link #signal}` and
    31     *  `{@link #wait}`. These two functions are always used in pairs in modules
    32     *  that use `ISync` instances. The `signal()` function is used to signal
    33     *  completion of an activity. The `wait()` function will allow the module to
    34     *  block or poll for completion of the same activity.
    35     *
    36     *  `ISync` mandates that the sync mechanism be binary and not support counters.
    37     *  Although the `wait()` function seems meaningless in the case of
    38     *  non-blocking sync, it allows modules to be written generically and support
    39     *  all `ISync` implementations. For non-blocking `ISync` the `wait()` function
    40     *  will return `WaitStatus_TIMEOUT` to denote timeout.
    41     */
    42
    43    interface ISync
    44    {
    45        /*!
    46         *  ======== WaitStatus ========
    47         *  Error codes returned by ISync_wait
    48         */
    49        enum WaitStatus {
    50            WaitStatus_ERROR = -1,
    51            WaitStatus_TIMEOUT = 0,
    52            WaitStatus_SUCCESS = 1
    53        };
    54
    55        /*!
    56         *  ======== Q_BLOCKING ========
    57         *  Blocking quality
    58         *
    59         *  Implementations with this "quality" may cause the calling thread to
    60         *  block;
    61         */
    62        const Int Q_BLOCKING = 1;
    63
    64        /*! Used to wait forever */
    65        const UInt WAIT_FOREVER = ~(0);
    66
    67        /*! Used to specify no waiting */
    68        const UInt NO_WAIT = 0;
    69
    70    instance:
    71        /*!
    72         *  ======== create ========
    73         *  Create an ISync instance.
    74         */
    75        create();
    76
    77        /*!
    78         *  ======== query ========
    79         *  Query for a particular quality.
    80         *
    81         *  FALSE is returned if quality not supported.
    82         *
    83         *  @param(qual)    quality
    84         *  @b(returns)     TRUE or FALSE.
    85         */
    86        Bool query(Int qual);
    87
    88        /*!
    89         *  ======== signal ========
    90         *  Called at completion of an activity.
    91         *
    92         *  This function is non-blocking. It is also required that the underlying
    93         *  sync be binary in nature.
    94         *
    95         *  This function does not take an Error.Block intentionally because
    96         *  it can be called from ISR context.
    97         */
    98        Void signal();
    99
   100        /*!
   101         *  ======== wait ========
   102         *  Called to wait/poll for completion of an activity.
   103         *
   104         *  This function can block. Non-blocking implementations should return
   105         *  WaitStatus_TIMEOUT to indicate a timeout.
   106         *
   107         *  @p(blist)
   108         *  -{@link #WaitStatus_ERROR} if an error occured.
   109         *  -{@link #WaitStatus_TIMEOUT} denotes timeout.
   110         *  -{@link #WaitStatus_SUCCESS} semaphore was decremented.
   111         *  @p
   112         *
   113         *  @param(timeout)     Timeout in microseconds
   114         *  @param(eb)Hist      Pointer to Error.Block
   115         *  @b(returns)         Refer to description above
   116         */
   117        Int wait(UInt timeout, Error.Block *eb);
   118    }
   119    /*
   120     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   121     */
   122


interface xdc.runtime.knl.IThreadSupport

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IThreadSupport.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18
    19    /*!
    20     *  ======== IThreadSupport ========
    21     *  Interface for OS specific back-end.
    22     *
    23     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    24     *  OS services. These xdc.runtime.knl modules require proxies to be
    25     *  bound to an OS specific delegate. This specifies the interface to
    26     *  be implemented by the OS specific delegate for
    27     *  {@link xdc.runtime.knl.Thread} module.
    28     *
    29     *  Refer to {@link xdc.runtime.knl.Thread} for more details on the APIs.
    30     */
    31    interface IThreadSupport
    32    {
    33        /*! Thread priorities which are mapped to OS specific value by Proxy */
    34        enum Priority {
    35        Priority_INVALID,
    36            Priority_LOWEST,
    37            Priority_BELOW_NORMAL,
    38            Priority_NORMAL,
    39            Priority_ABOVE_NORMAL,
    40            Priority_HIGHEST
    41        };
    42
    43        /*! Invalid OS priority value */
    44        const Int INVALID_OS_PRIORITY = 0;
    45
    46        /*!
    47         *  The error status for {@link #getPriority} when an error is captured in
    48         *  the  Error.Block.
    49         */
    50        const Int GETPRI_FAILED = -2;
    51
    52        /*! Status returned by {@link #compareOsPriorities} when an error occurs */
    53        enum CompStatus {
    54            CompStatus_ERROR = -2,
    55        CompStatus_LOWER = -1,
    56        CompStatus_EQUAL = 0,
    57        CompStatus_HIGHER = 1
    58        };
    59
    60        /*! typedef for function that gets called when the Thread runs. */
    61        typedef Void (*RunFxn)(IArg);
    62
    63        /*! Struct to hold thread statistics from {@link #stat} */
    64        struct Stat {
    65            SizeT stackSize;
    66            SizeT stackUsed;
    67        }
    68
    69        /*!
    70         *  ======== self ========
    71         *  Acquire the currently executing thread's handle.
    72         *
    73         *  Refer to {@link xdc.runtime.knl.Thread#self} for more details.
    74         *
    75         *  @param(eb)     Pointer to Error.Block
    76         *  @a(returns)    Handle in case of success; null for error;
    77         */
    78        Handle self(Error.Block* eb);
    79
    80        /*!
    81         *  ======== start ========
    82         *  Start threads running.
    83         *
    84         *  Refer to {@link xdc.runtime.knl.Thread#start} for more details.
    85         *
    86         *  @param(eb)     Pointer to Error.Block
    87         *  @a(returns)    true for success; false for failure
    88         */
    89        Bool start(Error.Block* eb);
    90
    91        /*!
    92         *  ======== yield ========
    93         *  Yield the currently scheduled thread.
    94         *
    95         *  Refer to {@link xdc.runtime.knl.Thread#yield} for more details.
    96         *
    97         *  @param(eb)     Pointer to Error.Block
    98         *  @a(returns)    true for success; false for failure
    99         */
   100        Bool yield(Error.Block* eb);
   101
   102        /*!
   103         *  ======== compareOsPriorities ========
   104         *  Compare two priority values and find out which one represents a
   105         *  higher priority.
   106         *
   107         *  Refer to {@link xdc.runtime.knl.Thread#compareOsPriorities} for more
   108         *  details.
   109         *
   110         *  @p(blist)
   111         *  -{@link #CompStatus_ERROR} if an error occured
   112         *  -{@link #CompStatus_LOWER} if p1 is lower than p2
   113         *  -{@link #CompStatus_EQUAL} if p1=p2
   114         *  -{@link #CompStatus_HIGHER} if p1 is higher than p2
   115         *    details.
   116         *  @p
   117         *
   118         *  @param(p1)      priority one
   119         *  @param(p2)      priority two
   120         *  @param(eb)      Pointer to Error.Block
   121         *  @a(returns)     Refer to description above
   122         */
   123        Int compareOsPriorities(Int p1, Int p2, Error.Block *eb);
   124
   125        /*!
   126         *  ======== sleep ========
   127         *  Sleep for certain number of microseconds
   128         *
   129         *  Refer to {@link xdc.runtime.knl.Thread#sleep} for more details.
   130         *
   131         *  @param(timeout)     timeout in microseconds
   132         *  @param(eb)          Pointer to Error.Block
   133         *  @a(returns)         true for success; false for failure
   134         */
   135        Bool sleep(UInt timeout, Error.Block *eb);
   136
   137    instance:
   138
   139        /*! Thread function argument. Default is NULL. */
   140        config IArg arg = null;
   141
   142        /*!
   143         *  ======== priority ========
   144         *  Thread priority
   145         *
   146         *  Thread defines several constants which allows applications to select
   147         *  a priority in an OS independent way. Priority_LOWEST,
   148         *  Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and
   149         *  Priority_HIGHEST. These values get mapped to OS specific priorities
   150         *  by the OS specific delegate.
   151         */
   152        config Priority priority = Priority_NORMAL;
   153
   154        /*!
   155         *  ======== osPriority ========
   156         *  OS specific thread priority
   157         *
   158         *  Used to specify an OS specific value for priority. If set this value
   159         *  takes precedence over {@link #priority}.
   160         */
   161        config Int osPriority = INVALID_OS_PRIORITY;
   162
   163        /*! Thread stack size. If left at zero, OS default is used */
   164        config SizeT stackSize = 0;
   165
   166        /*! User-specified thread local storage data. */
   167        config Ptr tls = null;
   168
   169        /*!
   170         *  ======== create ========
   171         *  Create a Thread object.
   172         *
   173         *  This function spawns a new thread calling the function fxn.
   174         *
   175         *  @param(fxn) function for new thread to begin execution
   176         */
   177        create(RunFxn fxn);
   178
   179        /*!
   180         *  ======== join ========
   181         *  Join on a Thread.
   182         *
   183         *  Refer to {@link xdc.runtime.knl.Thread#join} for more details.
   184         *
   185         *  @param(eb)     Pointer to Error.Block
   186         *  @a(returns)    true for success; false for failure
   187         */
   188        Bool join(Error.Block* eb);
   189
   190        /*!
   191         *  ======== getPriority ========
   192         *  Obtain a thread's priority.
   193         *
   194         *  Refer to {@link xdc.runtime.knl.Thread#getPriority} for more details.
   195         *
   196         *  @param(eb)     Pointer to Error.Block
   197         *  @a(returns)    thread priority in case of success; Priority_INVALID in
   198         *                 case of error;
   199         */
   200        Priority getPriority(Error.Block* eb);
   201
   202        /*!
   203         *  ======== setPriority ========
   204         *  Set a thread's priority.
   205         *
   206         *  Refer to {@link xdc.runtime.knl.Thread#setPriority} for more details.
   207         *
   208         *  @param(newPri)    new thread priority
   209         *  @param(eb)        Pointer to Error.Block
   210         *  @a(returns)       true for success; false for failure
   211         */
   212        Bool setPriority(Priority newPri, Error.Block* eb);
   213
   214        /*!
   215         *  ======== getOsPriority ========
   216         *  Obtain a thread's os specific priority.
   217         *
   218         *  For OSes that support dynamic priority boosting, the value returned
   219         *  is the base priority of the thread.
   220         *
   221         *  Refer to {@link xdc.runtime.knl.Thread#getOsPriority} for more details.
   222         *
   223         *  @param(eb)      Pointer to Error.Block
   224         *  @a(returns)     thread priority in case of success; GETPRI_FAILED in
   225         *                  case of error;
   226         */
   227        Int getOsPriority(Error.Block *eb);
   228
   229        /*!
   230         *  ======== setOsPriority ========
   231         *  Set a thread's priority.
   232         *
   233         *  This API sets the base priority of the thread on OSes that
   234         *  support dynamic priority boosting
   235         *
   236         *  Refer to {@link xdc.runtime.knl.Thread#setOsPriority} for more details.
   237         *
   238         *  @param(newPri)  new thread priority
   239         *  @param(eb)      Pointer to Error.Block
   240         *  @a(returns)     true for success; false for failure
   241         */
   242        Bool setOsPriority(Int newPri, Error.Block *eb);
   243
   244        /*!
   245         *  ======== getOsHandle ========
   246         *  Get the OS thread handle
   247         *
   248         *   @a(returns)     null in case of error
   249         */
   250        Ptr getOsHandle();
   251
   252        /*!
   253         *  ======== getTls ========
   254         *  Obtain a thread's local storage pointer
   255         *
   256         *  @a(returns)     null in case of error
   257         */
   258        Ptr getTls();
   259
   260        /*!
   261         *  ======== setTls ========
   262         *  Set a thread's local storage pointer.
   263         *
   264         *  @param(tls)     thread tls
   265         */
   266        Void setTls(Ptr tls);
   267
   268
   269        /*!
   270         *  ======== stat ========
   271         *  Obtain a thread's stats
   272         *
   273         *  @param(buf)    Pointer to Stat
   274         *  @param(eb)     Pointer to Error.Block
   275         *  @a(returns)    true for success; false for failure
   276         */
   277        Bool stat(Stat* buf, Error.Block* eb);
   278
   279    }
   280    /*
   281     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   282     */
   283


package xdc.runtime.knl

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== package.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== xdc.runtime.knl ========
    19     *  XDC Runtime support for OS-related primitives
    20     */
    21    package xdc.runtime.knl [1,0,0]
    22    {
    23        module GateH;
    24        module Semaphore;
    25        module Thread;
    26        module Sync;
    27
    28        module GateThread;
    29        module GateProcess;
    30        module SemThread;
    31        module SemProcess;
    32        module SyncGeneric;
    33        module SyncNull;
    34        module SyncSemThread;
    35        module Cache;
    36        module CacheSupportNull;
    37        module GateThreadSupportNull;
    38        module GateProcessSupportNull;
    39
    40        interface ISemaphore;
    41        interface ISync;
    42
    43        interface IGateThreadSupport;
    44        interface IGateProcessSupport;
    45        interface ISemThreadSupport;
    46        interface ISemProcessSupport;
    47        interface IThreadSupport;
    48        interface ICacheSupport;
    49    }
    50    /*
    51     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    52     */
    53


module xdc.runtime.knl.Semaphore

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Semaphore.xdc ========
    15     */
    16
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.Error;
    19    import xdc.runtime.knl.ISemaphore;
    20
    21    /*!
    22     *  ======== Semaphore ========
    23     *  Provides semaphore services when an ISemaphore.Handle is available.
    24     *
    25     *  An application can isolate itself from ISemaphore implementations by using
    26     *  this module. The application must first obtain an ISemaphore.Handle.
    27     *  It make get such a handle by directly calling {@link SemThread#create} or
    28     *  {@link SemProcess#create}. Then the application can use the generic
    29     *  APIs provided by this module.
    30     */
    31
    32    module Semaphore
    33    {
    34        /*!
    35         *  ======== PendStatus ========
    36         *  Error codes returned by Semaphore_pend
    37         */
    38        enum PendStatus {
    39            PendStatus_ERROR = -1,
    40            PendStatus_TIMEOUT = 0,
    41            PendStatus_SUCCESS = 1
    42        };
    43
    44        /*! Used as the timeout value to specify wait forever */
    45        const UInt FOREVER = ISemaphore.FOREVER;
    46
    47        /*!
    48         *  Proxy used for optimization.
    49         *
    50         *  If ALL ISemaphore.Handles were created using the same module
    51         *  (e.g SemProcess) then setting this Proxy to SemProcess and
    52         *  setting Semaphore.Proxy.abstractInstances$ = false,
    53         *  Semaphore APIs can have better performance.
    54         */
    55        proxy Proxy inherits ISemaphore;
    56
    57        /*!
    58         *  ======== pend ========
    59         *  Wait for the semaphore to have a nonzero count, then decrement it.
    60         *
    61         *  @p(blist)
    62         *  -{@link #PendStatus_ERROR} if an error occured.
    63         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    64         *  -{@link #PendStatus_SUCCESS} semaphore was decremented.
    65         *    details.
    66         *  @p
    67         *
    68         *  @param(sem)     ISemaphore.Handle to be used
    69         *  @param(timeout) timeout in microseconds
    70         *  @param(eb)      Pointer to Error.Block
    71         *  @a(returns)     status returned. (refer to above description)
    72         */
    73        Int pend(ISemaphore.Handle sem, UInt timeout, Error.Block *eb);
    74
    75        /*!
    76         *  ======== post ========
    77         *  Increment the semaphore count.
    78         *
    79         *  @param(sem)     ISemaphore.Handle to be used
    80         *  @param(eb)      Pointer to Error.Block
    81         *  @a(returns)     true for success, false for error in Error block.
    82         */
    83        Bool post(ISemaphore.Handle sem, Error.Block *eb);
    84    }
    85    /*
    86     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    87     */
    88


module xdc.runtime.knl.SemProcess

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SemProcess.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18    import xdc.runtime.knl.ISemaphore;
    19    import xdc.runtime.knl.ISemProcessSupport;
    20
    21    /*!
    22     *  ======== SemProcess ========
    23     *  SemProcess Manager
    24     *
    25     *  This module manages multi-process semaphores through its proxy
    26     *  ISemProcessSupport interface. It has a module wide config parameter
    27     *  {@link #Proxy} which needs to be bound to an OS specific delegate before
    28     *  this module can be used.
    29     *
    30     *  Here is an example showing how the proxy is bound to an BIOS 6.x specific
    31     *  delegate.
    32     *
    33     *  @p(code)
    34     *  var SemProcess = xdc.useModule('xdc.runtime.knl.SemProcess');
    35     *  SemProcess.Proxy = xdc.useModule('ti.sysbios.xdcruntime.SemProcessSupport');
    36     *  @p
    37     *
    38     *  Typically the package containing the delegates have a Settings module that
    39     *  will bind all {@link xdc.runtime.knl} proxies. The following
    40     *  example sets up all the xdc.runtime.knl proxies.
    41     *
    42     *  @p(code)
    43     *  xdc.useModule("ti.sysbios.xdcruntime.Settings");
    44     *  @p
    45     */
    46
    47    @InstanceInitError      /* because initialization can fail */
    48    @InstanceFinalize       /* have to Semaphore_Proxy_delete(sem) on delete */
    49
    50    module SemProcess inherits ISemaphore
    51    {
    52
    53        /*! Proxy that needs to be bound to an OS specific delegate. */
    54        proxy Proxy inherits ISemProcessSupport;
    55
    56    instance:
    57
    58       /*!
    59        *  ======== create ========
    60        *  Create a SemProcess object
    61        *
    62        *  This function creates a new `SemProcess` object which is initialized to
    63        *  count.  All semaphores created with the same key reference the same
    64        *  underlying synchronization object and work between processes.
    65        *
    66        *  @param(count)    initial semaphore count
    67        *  @param(key)      globally unique key for SysV-style semaphore
    68        */
    69        create(Int count, UInt32 key);
    70
    71    internal:
    72
    73        struct Instance_State {
    74            Proxy.Handle proxyHandle;
    75        }
    76    }
    77    /*
    78     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    79     */
    80


module xdc.runtime.knl.SemThread

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SemThread.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18    import xdc.runtime.knl.ISemaphore;
    19    import xdc.runtime.knl.ISemThreadSupport;
    20
    21    /*!
    22     *  ======== SemThread ========
    23     *  SemThread Manager.
    24     *
    25     *  This module manages semaphores through its proxy ISemThreadSupport
    26     *  interface. It has a module wide config parameter
    27     *  {@link #Proxy} which needs to be bound to an OS specific delegate before
    28     *  this module can be used.
    29     *
    30     *  Here is an example showing how the proxy is bound to an BIOS 6.x specific
    31     *  delegate.
    32     *
    33     *  @p(code)
    34     *  var SemThread = xdc.useModule('xdc.runtime.knl.SemThread');
    35     *  SemThread.Proxy = xdc.useModule('ti.sysbios.xdcruntime.SemThreadSupport');
    36     *  @p
    37     *
    38     *  Typically the package containing the delegates have a Settings module that
    39     *  will bind all {@link xdc.runtime.knl} proxies. The following
    40     *  example sets up all the xdc.runtime.knl proxies.
    41     *
    42     *  @p(code)
    43     *  xdc.useModule("ti.sysbios.xdcruntime.Settings");
    44     *  @p
    45     */
    46
    47    @InstanceInitError      /* because initialization can fail */
    48    @InstanceFinalize       /* have to SemThread_Proxy_delete(sem) on delete */
    49
    50    module SemThread inherits ISemaphore
    51    {
    52
    53        /*! Proxy that needs to be bound to an OS specific delegate. */
    54        proxy Proxy inherits ISemThreadSupport;
    55
    56    instance:
    57
    58       /*!
    59        *  ======== create ========
    60        *  Create a SemThread object.
    61        *
    62        *  This function creates a new `SemThread` object which is initialized to
    63        *  count.
    64        *
    65        *  @param(count)    initial semaphore count
    66        */
    67        create(Int count);
    68
    69    internal:
    70
    71        struct Instance_State {
    72            Proxy.Handle proxyHandle;
    73        }
    74
    75    }
    76    /*
    77     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    78     */
    79


module xdc.runtime.knl.Sync

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Sync.xdc ========
    15     */
    16    import xdc.runtime.Error;
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.knl.ISync;
    19
    20    /*!
    21     *  ======== Sync ========
    22     *  Provides synchronization APIs when an ISync.Handle is available
    23     *
    24     *  The application must first obtain an ISync.Handle.
    25     *  It can get such a handle by directly calling {@link SyncGeneric#create} or
    26     *  {@link SyncSemThread#create}. Then the application can use the generic
    27     *  APIs provided by this module.
    28     */
    29
    30    module Sync
    31    {
    32        /*!
    33         *  ======== WaitStatus ========
    34         *  Error codes returned by Sync_wait
    35         */
    36        enum WaitStatus {
    37            WaitStatus_ERROR = -1,
    38            WaitStatus_TIMEOUT = 0,
    39            WaitStatus_SUCCESS = 1
    40        };
    41
    42        /*!
    43         *  ======== WAIT_FOREVER ========
    44         *  Used to wait forever
    45         */
    46        const UInt WAIT_FOREVER = ISync.WAIT_FOREVER;
    47
    48        /*!
    49         *  ======== NO_WAIT ========
    50         *  Used to specify no waiting
    51         */
    52        const UInt NO_WAIT = ISync.NO_WAIT;
    53
    54        /*!
    55         *  ======== Proxy ========
    56         *  Platform-specific implementation
    57         *
    58         *  If ALL `ISync.Handles` were created using the same module
    59         *  (e.g SyncSemProcess), then setting `Proxy` to `SyncSemProcess` and
    60         *  `Sync.Proxy.abstractInstances$` to `false` will improve the
    61         *  performance of the `Sync` APIs.
    62         */
    63        proxy Proxy inherits ISync;
    64
    65        /*!
    66         *  ======== query ========
    67         *  Query for a particular quality
    68         *
    69         *  FALSE is returned if quality not supported.
    70         *
    71         *  @param(sync)    sync handle
    72         *  @param(qual)    quality
    73         *
    74         *  @a(returns)     TRUE or FALSE.
    75         */
    76        Bool query(ISync.Handle sync, Int qual);
    77
    78        /*!
    79         *  ======== signal ========
    80         *  Called at completion of an activity.
    81         *
    82         *  This function is non-blocking. It is also required that the underlying
    83         *  sync be binary in nature.
    84         *
    85         *  @param(sync)    sync handle
    86         */
    87        Void signal(ISync.Handle sync);
    88
    89        /*!
    90         *  ======== wait ========
    91         *  Called to wait/poll for completion of an activity.
    92         *
    93         *  This function can block and typically waits for a semaphore to become
    94         *  available.
    95         *
    96         *  Non-blocking implementations should return {@link #WaitStatus_TIMEOUT}.
    97         *
    98         *  @param(sync)        sync handle
    99         *  @param(timeout)     timeout in microseconds
   100         *
   101         *  @a(returns)
   102         *  @p(blist)
   103         *  -{@link #WaitStatus_ERROR} if an error occured.
   104         *  -{@link #WaitStatus_TIMEOUT} denotes timeout.
   105         *  -{@link #WaitStatus_SUCCESS} semaphore was decremented.
   106         *  @p
   107         */
   108        Int wait(ISync.Handle sync, UInt timeout, Error.Block *eb);
   109    }
   110    /*
   111     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   112     */
   113


module xdc.runtime.knl.SyncGeneric

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SyncGeneric.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== SyncGeneric ========
    19     *  Generic ISync implementation
    20     *
    21     *  This module allows users to plug in their own
    22     *  functions for signal, wait and query.
    23     */
    24
    25    module SyncGeneric inherits xdc.runtime.knl.ISync
    26    {
    27        /*! typedef for user specified signal function */
    28        typedef Void (*SignalFunc)(UArg);
    29
    30        /*! typedef for user specified wait function */
    31        typedef Bool (*WaitFunc)(UArg, UInt);
    32
    33        /*! typedef for user specified wait function */
    34        typedef Bool (*QueryFunc)(Int);
    35
    36    instance:
    37        /*! user signal function */
    38        config SignalFunc userSignal = null;
    39
    40        /*! user signal function arg */
    41        config UArg signalArg = null;
    42
    43        /*! user wait function */
    44        config WaitFunc  userWait = null;
    45
    46        /*! user wait function arg */
    47        config UArg waitArg = null;
    48
    49        /*! user query function */
    50        config QueryFunc userQuery = null;
    51
    52    internal:
    53
    54        /* -------- Internal Structures -------- */
    55        struct Instance_State {
    56            SignalFunc  userSignal;
    57            UArg        signalArg;
    58            WaitFunc    userWait;
    59            UArg        waitArg;
    60            QueryFunc   userQuery;
    61        };
    62
    63    }
    64    /*
    65     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:32; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    66     */
    67


module xdc.runtime.knl.SyncNull

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SyncNull.xdc ========
    15     */
    16
    17    /*!
    18     *  ======== SyncNull ========
    19     *  Empty ISync implementation used mainly for testing
    20     */
    21
    22    module SyncNull inherits xdc.runtime.knl.ISync
    23    {
    24    }
    25    /*
    26     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    27     */
    28


module xdc.runtime.knl.SyncSemThread

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== SyncSemThread.xdc ========
    15     */
    16
    17    import xdc.runtime.knl.SemThread;
    18
    19    /*!
    20     *  ======== SyncSemThread ========
    21     *  A ISync implementation based on a SemThread. [EXPERIMENTAL]
    22     *
    23     *  This module implements the {@link ti.sdo.utils.ISync} interface
    24     *  using the {@link xdc.runtime.knl.SemThread} module.
    25     */
    26
    27    @InstanceInitError      /* instance initialization can fail */
    28    @InstanceFinalize       /* instances require finalization */
    29
    30    module SyncSemThread inherits xdc.runtime.knl.ISync
    31    {
    32
    33    internal:  /* not for client use */
    34
    35        struct Instance_State {
    36            SemThread.Handle    semThread;
    37        };
    38    }
    39    /*
    40     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
    41     */
    42


module xdc.runtime.knl.Thread

     1    /*
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Thread.xdc ========
    15     */
    16
    17    import xdc.runtime.Error;
    18    import xdc.runtime.Assert;
    19    import xdc.runtime.knl.IThreadSupport;
    20
    21    /*!
    22     *  ======== Thread ========
    23     *  Thread services.
    24     *
    25     *  This module manages threads through a proxy which inherits from
    26     *  IThreadSupport interface. It has a module wide config parameter
    27     *  {@link #Proxy} which needs to be bound to an OS specific delegate before
    28     *  this module can be used.
    29     *
    30     *  Here is an example showing how the proxy is bound to a BIOS 6.x specific
    31     *  delegate.
    32     *
    33     *  @p(code)
    34     *  var Thread = xdc.useModule('xdc.runtime.knl.Thread');
    35     *  Thread.Proxy = xdc.useModule('ti.sysbios.xdcruntime.ThreadSupport');
    36     *  @p
    37     *
    38     *  Typically a package containing the delegates has a Settings module that
    39     *  will bind all {@link xdc.runtime.knl} proxies. The following
    40     *  example sets up all the xdc.runtime.knl proxies.
    41     *
    42     *  @p(code)
    43     *  xdc.useModule('ti.sysbios.xdcruntime.Settings');
    44     *  @p
    45     */
    46
    47    @InstanceInitError      /* because initialization can fail */
    48    @InstanceFinalize       /* have to Thread_Proxy_delete(sem) on delete */
    49
    50    module Thread
    51    {
    52        /*! Thread priorities which are mapped to OS specific value by Proxy */
    53        enum Priority {
    54            Priority_INVALID,
    55            Priority_LOWEST,
    56            Priority_BELOW_NORMAL,
    57            Priority_NORMAL,
    58            Priority_ABOVE_NORMAL,
    59            Priority_HIGHEST
    60        };
    61
    62        /*! Invalid OS priority value */
    63        const Int INVALID_OS_PRIORITY = 0;
    64
    65        /*! Status returned by {@link #getPri} when an error occurs */
    66        const Int GETPRI_FAILED = -2;
    67
    68        /*! Status returned by {@link #compareOsPriorities} when an error occurs */
    69        enum CompStatus {
    70            CompStatus_ERROR = -2,
    71            CompStatus_LOWER = -1,
    72            CompStatus_EQUAL = 0,
    73            CompStatus_HIGHER = 1
    74        };
    75
    76        /*! Proxy that needs to be bound to an OS specific delegate. */
    77        proxy Proxy inherits IThreadSupport;
    78
    79        /*! Typedef for thread function */
    80        typedef Void (*RunFxn)(IArg);
    81
    82        /*! Struct to hold thread statistics from {@link #stat} */
    83        struct Stat {
    84            SizeT stackSize;
    85            SizeT stackUsed;
    86        }
    87
    88        /*! Assert when  timeout passed to {@link #sleep} is zero */
    89        config Assert.Id A_zeroTimeout= {
    90            msg: "A_zeroTimeout: Timeout value annot be zero"
    91        };
    92
    93        /*! Default thread stack size. */
    94        config SizeT defaultStackSize = 0;
    95
    96        /*!
    97         *  ======== self ========
    98         *  Return the currently executing thread's handle
    99         *
   100         *  @param(eb)      Pointer to Error.Block
   101         *  @a(returns)     Returns a handle to the currently executing thread.
   102         *                  If the current thread is the main thread, this function
   103         *                  returns `NULL`. NULL is also returned in case of error.
   104         */
   105        @DirectCall
   106        Handle self(Error.Block *eb);
   107
   108        /*!
   109         *  ======== start ========
   110         *  Start threads running
   111         *
   112         *  This function can be used to start all statically created threads,
   113         *  and all threads created dynamically before this function is called.
   114         *  Any thread created after this function is called, starts automatically.
   115         *  (i.e., there is no need to call Thread_start() more than once).
   116         *
   117         *  @param(eb)      Pointer to Error.Block
   118         *  @a(returns)     true for success; false for error
   119         */
   120        Bool start(Error.Block *eb);
   121
   122        /*!
   123         *  ======== yield ========
   124         *  Yield the currently scheduled thread
   125         *
   126         *  @param(eb)      Pointer to Error.Block
   127         *  @a(returns)     true for success; false for error
   128         */
   129        Bool yield(Error.Block *eb);
   130
   131        /*!
   132         *  ======== compareOsPriorities ========
   133         *  Compare two os specific priority values and find out which one
   134         *  represents a higher priority.
   135         *
   136         *  @p(blist)
   137         *  -{@link #CompStatus_ERROR} if an error occured
   138         *  -{@link #CompStatus_LOWER} if p1 is lower than p2
   139         *  -{@link #CompStatus_EQUAL} if p1=p2
   140         *  -{@link #CompStatus_HIGHER} if p1 is higher than p2
   141         *    details.
   142         *  @p
   143         *
   144         *  @param(p1)      priority one
   145         *  @param(p2)      priority two
   146         *  @param(eb)      Pointer to Error.Block
   147         *  @a(returns)     refer to description above
   148         */
   149        Int compareOsPriorities(Int p1, Int p2, Error.Block *eb);
   150
   151        /*!
   152         *  ======== sleep ========
   153         *  Sleep for given number of microseconds
   154         *
   155         *  This function is gauranteed to sleep for at least as long as the
   156         *  timeout value but the actual sleep time may be longer. NOTE:
   157         *  The timeout value cannot be zero.
   158         *
   159         *  @param(timeout)     timeout in microseconds
   160         *  @param(eb)          Pointer to Error.Block
   161         *  @a(returns)         true for success; false for error
   162         */
   163        Bool sleep(UInt timeout, Error.Block *eb);
   164
   165    instance:
   166
   167        /*! Thread function argument. Default is 0. */
   168        config IArg arg = 0;
   169
   170        /*!
   171         *  ======== priority ========
   172         *  Specify the new thread's priority
   173         *
   174         *  Thread defines several constants which allows applications to select
   175         *  a priority in an OS independent way: Priority_LOWEST,
   176         *  Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and
   177         *  Priority_HIGHEST. These values get mapped to OS specific priorities
   178         *  by the OS specific delegate.
   179         */
   180        config Priority priority = Priority_NORMAL;
   181
   182        /*!
   183         *  ======== osPriority ========
   184         *  OS specific thread priority
   185         *
   186         *  Used to specify an OS specific value for priority. If set this value
   187         *  takes precedence over {@link #priority}.
   188         */
   189        config Int osPriority = INVALID_OS_PRIORITY;
   190
   191        /*!
   192         *  ======== stackSize ========
   193         *  Thread stack size
   194         *
   195         *  The default value of 0 means that `{@link #defaultStackSize}` is used.
   196         */
   197        config SizeT stackSize = 0;
   198
   199        /*!
   200         *  ======== tls ========
   201         *  Thread local storage.
   202         *
   203         *  User data associated with a thread. Must persist for the life of
   204         *  the thread.
   205         */
   206        config Ptr tls = null;
   207
   208        /*!
   209         *  ======== create ========
   210         *  Create a Thread object
   211         *
   212         *  This function spawns a new thread calling the function fxn.
   213         *
   214         *  @param(fxn)     function for new thread to begin execution
   215         */
   216        create(RunFxn fxn);
   217
   218        /*!
   219         *  ======== join ========
   220         *  Block calling thread until given thread terminates.
   221         *
   222         *  Use this functions to ensure that a thread has terminated. It is OK to
   223         *  call this function on a thread that has already terminated.
   224         *
   225         *  @param(eb)      Pointer to Error.Block
   226         *  @a(returns)     true for success; false for error
   227         */
   228        Bool join(Error.Block *eb);
   229
   230        /*!
   231         *  ======== getPriority ========
   232         *  Obtain a thread's priority.
   233         *
   234         *  For OSes that support dynamic priority boosting, this function
   235         *  retrieves the base priority of the thread.
   236         *
   237         *  @param(eb)      Pointer to Error.Block
   238         *  @a(returns)     thread priority in case of success; PRIORITY_INVALID in
   239         *                  case of error;
   240         */
   241        Priority getPriority(Error.Block *eb);
   242
   243        /*!
   244         *  ======== setPriority ========
   245         *  Set a thread's priority.
   246         *
   247         *  For OSes that support dynamic priority boosting, this function
   248         *  changes the base priority of the thread.
   249         *
   250         *  @param(newPri)  new thread priority
   251         *  @param(eb)      Pointer to Error.Block
   252         *  @a(returns)     true for success; false for error
   253         */
   254        Bool setPriority(Priority newPri, Error.Block *eb);
   255
   256        /*!
   257         *  ======== getOsPriority ========
   258         *  Obtain a thread's OS specific priority.
   259         *
   260         *  For OSes that support dynamic priority boosting, the value returned
   261         *  is the base priority of the thread.
   262         *
   263         *  @param(eb)      Pointer to Error.Block
   264         *  @a(returns)     thread priority in case of success; GETPRI_FAILED in
   265         *                  case of error;
   266         */
   267        Int getOsPriority(Error.Block *eb);
   268
   269        /*!
   270         *  ======== setOsPriority ========
   271         *  Set a thread's priority.
   272         *
   273         *  This API sets the base priority of the thread on OSes that
   274         *  support dynamic priority boosting
   275         *
   276         *  @param(newPri)  new thread priority
   277         *  @param(eb)      Pointer to Error.Block
   278         *  @a(returns)     true for success; false for error
   279         */
   280        Bool setOsPriority(Int newPri, Error.Block *eb);
   281
   282        /*!
   283         *  ======== getOsHandle ========
   284         *  Get the OS thread handle
   285         *
   286         *   @a(returns)     OS thread handle
   287         */
   288        Ptr getOsHandle();
   289
   290        /*!
   291         *  ======== getTls ========
   292         *  Obtain a thread's local storage.
   293         *
   294         *   @a(returns)     null when tls has not been set.
   295         */
   296        Ptr getTls();
   297
   298        /*!
   299         *  ======== setTls ========
   300         *  Change a thread's local storage.
   301         *
   302         *  @param(tls)     tls
   303         */
   304        Void setTls(Ptr tls);
   305
   306        /*!
   307         *  ======== stat ========
   308         *  Get thread statistics
   309         *
   310         *  @param(buf)     Pointer to Stat
   311         *  @param(eb)      Pointer to Error.Block
   312         *  @a(returns)     true for success; false for failure
   313         */
   314        Bool stat(Stat* buf, Error.Block *eb);
   315
   316    internal:
   317
   318        struct Instance_State {
   319            Thread.Proxy.Handle proxyHandle; /*! handle for real implementation */
   320            Ptr                 tls;         /*! store tls parameter */
   321        }
   322    }
   323    /*
   324     *  @(#) xdc.runtime.knl; 1, 0, 0,146; 6-14-2011 11:49:33; /db/ztree/library/trees/xdc/xdc-x14x/src/packages/
   325     */
   326