1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 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 166 167
168