1    /* 
     2     * Copyright (c) 2012, 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,543; 2-24-2012 11:40:29; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   166    
   167     */
   168