1: /*
2: *----------------------------------------------------------------------
3: * T2EX Software Package
4: *
5: * Copyright 2012-2015 by Ken Sakamura.
6: * This software is distributed under the latest version of T-License 2.x.
7: *----------------------------------------------------------------------
8: *
9: * Released by T-Engine Forum(http://www.t-engine.org/) at 2012/12/12.
10: * Modified by T-Engine Forum at 2015/02/27.
11: * Modified by TRON Forum(http://www.tron.org/) at 2015/06/04.
12: *
13: *----------------------------------------------------------------------
14: */
15: /*
16: * This software package is available for use, modification,
17: * and redistribution in accordance with the terms of the attached
18: * T-License 2.x.
19: * If you want to redistribute the source code, you need to attach
20: * the T-License 2.x document.
21: * There's no obligation to publish the content, and no obligation
22: * to disclose it to the TRON Forum if you have modified the
23: * software package.
24: * You can also distribute the modified source code. In this case,
25: * please register the modification to T-Kernel traceability service.
26: * People can know the history of modifications by the service,
27: * and can be sure that the version you have inherited some
28: * modification of a particular version or not.
29: *
30: * http://trace.tron.org/tk/?lang=en
31: * http://trace.tron.org/tk/?lang=ja
32: *
33: * As per the provisions of the T-License 2.x, TRON Forum ensures that
34: * the portion of the software that is copyrighted by Ken Sakamura or
35: * the TRON Forum does not infringe the copyrights of a third party.
36: * However, it does not make any warranty other than this.
37: * DISCLAIMER: TRON Forum and Ken Sakamura shall not be held
38: * responsible for any consequences or damages caused directly or
39: * indirectly by the use of this software package.
40: *
41: * The source codes in bsd_source in this software package are
42: * derived from NetBSD or OpenBSD and not covered under T-License 2.x.
43: * They need to be changed or redistributed according to the
44: * representation of each source header.
45: */
46: /*
47: * Acknowledgement
48: *
49: * TRON Forum would like to acknowledge the contribution of the
50: * TRON Forum T-Kernel Working Group members for completion of
51: * the T2EX package.
52: * The working group provided comments, held in-depth discussion
53: * and offered much assistance to detailed testing for the source code
54: * of the T2EX.
55: *
56: * T-Kernel Working Group members:
57: * eSOL Co., Ltd.
58: * FUJITSU COMPUTER TECHNOLOGIES LIMITED
59: * FUJITSU SEMICONDUCTOR LIMITED
60: * Hitachi ULSI Systems Co., Ltd.
61: * Personal Media Corporation
62: * Renesas Electronics Corporation
63: * YRP Ubiquitous Networking Laboratory
64: */
65:
66: ==============================================================================
67: T-Kernel 2.0 Extension Development Environment for T-Engine Reference Board
68: ==============================================================================
69:
70: ------------------------------------------------------------------------------
71: Table of Contents
72: ------------------------------------------------------------------------------
73: 1. Foreword
74: 2. Package Contents
75: 3. Workflow
76: 3.1 Installing Development Environment
77: 3.2 Extracting Source Code Package
78: 3.3 How To Build System
79: 3.4 System Configuration Information
80: 3.5 Building Application
81:
82: ------------------------------------------------------------------------------
83: 1. Foreword
84: ------------------------------------------------------------------------------
85:
86: This document describes the procedure to build T-Kernel 2.0 Extension for
87: T-Engine reference board (tef_em1d) and applications running on it using the
88: Eclipse or Linux command line development environment.
89:
90: T-Kernel 2.0 Extension (T2EX) is an extension added onto T-Kernel 2.0, and the
91: underlying T-Kernel 2.0 system is used as it is.
92:
93: This package contains only the part added as T2EX to the T-Kernel 2.0 software
94: package. T-Kernel 2.0 source code included in T-Kernel 2.0 software package
95: (T-Kernel 2.02.00 Software Package) can be used as they are.
96:
97: Please use version 2.02.00 or later for T-Kernel 2.0. Make sure to use the latest
98: version, since the T-Kernel 2.0 software package does not operate properly on the
99: older versions than T-Kernel 2.02.00.
100:
101: ------------------------------------------------------------------------------
102: 2. Package Contents
103: ------------------------------------------------------------------------------
104:
105: This package contains:
106:
107: README.md
108: t2ex-dist-ucode.png Distribution ucode
109: TEF000-218-150401.pdf T-License 2.1
110:
111: /doc/ja/
112: t2ex-guide.txt T2EX guide (this document)
113: impl-t2ex.txt T2EX implementation specifications
114: Ver2.01.00.txt Change history (v2.01.00)
115:
116: t2ex_source T2EX and device driver source code
117: bsd_source Source code derived from NetBSD or OpenBSD
118:
119: --------------------------------------------------
120: 3 Source code structure
121: --------------------------------------------------
122:
123: Of the T2EX source code, NetBSD or OpenBSD-derived source code is separated into
124: the bsd_source directory. When building T2EX, you need to merge the bsd_source files.
125:
126: include/ Definition files
127: t2ex/** T2EX function definition files
128: sys/
129: atomic.h Atomic operation definition file
130: sysdepend/
131: atomic_common.h
132: tef_em1d/
133: atomic_depend.h
134: device/
135: netdrv.h Network driver definition file
136:
137: kernel/ Kernel
138: extension/ Extension
139: memory/
140: t2ex/** Memory manager for T2EX
141:
142: sysdepend/t2ex/** System-dependent portion
143:
144: sysinit/ System initialize
145: build_t2ex/** For T2EX build
146: src_t2ex/** Sources for T2EX
147:
148: sysmain/ System main
149: build_t2ex/** For T2EX build
150: src/
151: usermain_t2ex.c User main for T2EX
152: appl_main.c Application main for T2EX
153: commoand.c Command processer for T2EX
154: ref_command.c Reference command processing program for T2EX
155: network_sample/** Network Sample sources for T2EX
156:
157: sysmgr/ System manager
158: build_t2ex/** For T2EX build
159: src_t2ex/** Sources for T2EX
160:
161: tkernel/ T-Kernel
162: build_t2ex/** For T2EX build
163: src_t2ex/** Sources for T2EX
164:
165: lib/ Libraries
166: build_t2ex/** For T2EX build
167: libtk/ T-Kernel libraries
168: build_t2ex/** For T2EX build
169: src_t2ex/** Sources for T2EX
170: libc/** Standard C compatible libraries
171: libusermod/** Libraries for T2EX program module
172:
173: t2ex/ T2EX function sources
174: build/** For T2EX build
175: fs/** T2EX file management function
176: network/** T2EX network communication function
177: datetime/** T2EX calendar function
178: load/** T2EX program load function
179:
180: module/** For T2EX program module sample/build
181:
182: config/ Configuration (RomInfo, SYSCONF, DEVCONF)
183: src_t2ex/** Sources for T2EX
184: build_t2ex/** For T2EX build
185:
186: driver/ Device drivers
187: tef_em1d/
188: build_t2ex/** For T2EX build
189: netdrv/** Network drivers for reference board
190:
191: etc/ Others (script, etc.)
192: mkt2exsvc for creating T2EX SVC I/F library
193: sysdepend/
194: cpu/
195: em1d/
196: makeift2ex.pl for creating T2EX SVC I/F library
197: tef_em1d/
198: makerules.sysdepend Common Make rules
199:
200: --------------------------------------------------
201: 4 How To Build System
202: --------------------------------------------------
203:
204: T2EX is used by incorporating it into the T-Kernel 2.0 Software Package.
205: As with the T-Kernel 2.0 system, you can choose from three development
206: methods: Eclipse, Cygwin, and Linux. For details, refer to the T-Kernel 2.0
207: software package documentation.
208:
209: The T-Kernel 2.0 software package can be obtained from the following URL
210: on the TRON Forum.
211: The package also includes various development environments. However, please
212: note that the development environment is as of the time of publication.
213:
214: https://www.tron.org/download/index.php?route=product/product&path=37_38&product_id=133
215:
216: --------------------------------------------------
217: 4.1 Installing Development Environment
218: --------------------------------------------------
219:
220: Application on T2EX system can be developed using Eclipse, Cygwin or Linux in
221: the same manner as on T-Kernel 2.0 system. For details, refer to T-Kernel 2.0
222: software package manual.
223:
224: Install the T-Kernel 2.0 development environment included in the T-Kernel 2.0
225: software package in the host PC for development.
226:
227: It can be installed in any directory. By default, it is installed in the
228: following directory.
229:
230: /usr/local/tef_em1d
231:
232: --------------------------------------------------
233: 4.2 Extracting Source Code Package
234: --------------------------------------------------
235:
236: First, extract (untar) source files from the T-Kernel source code package
237: (tkernel_source.tar.gz) in T-Kernel 2.0 software package under the directory
238: (/usr/local/tef_em1d) where development environment is installed.
239: This creates tkernel_source directory.
240:
241: Next, create the t2ex_source directory included in this package on the same
242: directory.
243:
244: And then, execute the following commands to copy the content of t2ex_source
245: directory to tkernel_source directory.
246:
247: $ cd /usr/local/tef_em1d/t2ex_source
248: $ cp -r * ../tkernel_source
249:
250: * The content of t2ex_source directory is no longer needed after copying
251: and can be deleted.
252:
253: The source files of T2EX will be added to tkernel_source directory by copying.
254: However, the following file will overwrite the original source files of
255: T-Kernel as an exception. (Other files will be added.)
256:
257: tkernel_source/etc/sysdepend/tef_em1d/makerules.sysdepend
258:
259: * The above overwritten (and thus changed) file can be used as-is
260: for T-Kernel, too.
261:
262: --------------------------------------------------
263: 4.3 How To Build System
264: --------------------------------------------------
265:
266: Execute the following commands to build the whole T2EX system including T-Kernel.
267:
268: $ cd $BD/kernel/sysmain/build_t2ex/tef_em1d
269: $ make emu
270:
271: * $BD is the value of environment variable BD, i.e., tkernel_source
272: subdirectory (/usr/local/tef_em1d/tkernel_source) of the directory
273: where T-Kernel source code package is installed.
274:
275: * In case of Eclipse environment, set up the build environment with
276: "kernel/sysmain/build_t2ex/tef_em1d" as its build destination
277: directory and execute "make emu".
278:
279: * If T-Kernel was built under $BD, make sure to execute "make clean"
280: before building T2EX system.
281:
282: * The original T-Kernel not including the T2EX addition can be built by
283: executing "make clean" and "make emu" under "kernel/sysmain/build/tef_em1d".
284:
285: The following files, the build results, will be created in
286: "$BD/kernel/sysmain/build_t2ex/tef_em1d" directory where "make emu"
287: is executed.
288: "_t2ex" will be added to the file names of T2EX system binaries.
289: These files will also be copied to "$BD/bin/tef_em1d" directory.
290:
291: (a) For RAM execution (for debug)
292:
293: kernel_t2ex-ram.sys Executable object of RAM version T2EX
294: kernel_t2ex-ram.map Link map of RAM version T2EX
295: kernel_t2ex-ram.mot Load image of RAM version T2EX (S-Format)
296: kernel_t2ex-ram.bin Load image of RAM version T2EX (Binary)
297:
298: rominfo_t2ex-ram.mot Load image of RAM version RomInfo (S-Format)
299:
300: rom_t2ex-dbg.bin Load image of RAM version for Emulator (Binary)
301: ( T-Monitor + RomInfo )
302:
303: (b) For ROM execution (for writing into Flash ROM)
304:
305: kernel_t2ex-rom.rom Executable object of ROM version T2EX
306: kernel_t2ex-rom.map Link map of ROM version T2EX
307: kernel_t2ex-rom.mot Load image of ROM version T2EX (S-Format)
308:
309: rominfo_t2ex-rom.mot Load image of ROM version RomInfo (S-Format)
310:
311: rom_t2ex.bin Load image of ROM version for Emulator (Binary)
312: ( T-Monitor + RomInfo + T-Kernel )
313:
314: (c) For RAM/ROM execution (for writing into Flash ROM)
315:
316: tmonitor.mot Load image of T-Monitor (S-Format)
317: tmonitor.map Link map of T-Monitor
318:
319: * The used T-Monitor is the same one built for T-Kernel.
320:
321: Using the above build files, you can run and debug T2EX application by using
322: emulator (QEMU) or target hardware in the development environment of Eclipse,
323: Cygwin, or Linux. For details, refer to T-Kernel 2.0 software package manual.
324:
325:
326: Executable image including only a limited set of T2EX functions can be
327: created by deleting the following definitions in Makefile in
328: "$BD/kernel/sysmain/build_t2ex/tef_em1d" directory.
329:
330: # use T2EX memory management
331: T2EX_MM = _t2ex
332:
333: # use task fault function of T2EX memory management
334: T2EX_MM_USE_TASKEXCEPTION = 1
335:
336: # use default memory fault handlers
337: T2EX_MM_USE_DEFAULT_FAULT_HANDLER = 1
338:
339: # use T2EX file management
340: T2EX_FS = yes
341:
342: # use T2EX network communication
343: T2EX_NET = yes
344:
345: # use T2EX calendar
346: T2EX_DT = yes
347:
348: # use T2EX program load
349: T2EX_PM = yes
350:
351: # use T2EX network sample programs
352: T2EX_NET_SAMPLE = yes
353:
354: * When the file management function or network communication function
355: are used, the calendar function is required and cannot be deleted.
356:
357: * If the file management function is deleted, the standard I/O functions
358: of standard C library cannot be used.
359:
360: The device drivers to be embedded in the executable image can be selected
361: by changing the following definitions.
362:
363: # device driver definitions
364: DRV_CONSOLE = yes
365: DRV_CLOCK = yes
366: DRV_SYSDISK = yes
367: DRV_SCREEN = yes
368: DRV_KBPD = yes
369: DRV_LOWKBPD = yes
370: DRV_NET = yes
371:
372: * The device drivers required for each T2EX function are as follows.
373:
374: DRV_CLOCK T2EX calendar function
375: DRV_CONSOLE T2EX file management function (Standard input/output)
376: DRV_SYSDISK T2EX file management function
377: DRV_NET T2EX network communication function
378:
379: --------------------------------------------------
380: 4.4 System Configuration Information
381: --------------------------------------------------
382:
383: Settings for T2EX have been added to the system configuration information.
384: To modify their values, modify SYSCONF in the following directories.
385:
386: $BD/config/src_t2ex/sysdepend/tef_em1d/SYSCONF
387:
388: * For the setting for T2EX of the system configuration information,
389: see "T2EX Specifications" and "T2EX Implementation Specifications".
390:
391: --------------------------------------------------
392: 4.5 Building Application
393: --------------------------------------------------
394:
395: A T2EX user application is linked with the T2EX system to be an object at
396: runtime.
397:
398: To write an application program, generally, a program in the $BD/kernel/sysmain/src
399: directory can be modified or added. The following sample programs are
400: included in the $BD/kernel/sysmain/src directory of this package for
401: reference.
402:
403: usermain_t2ex.c
404: This program is run as the initial task of an application.
405: It performs the initialization of device drivers and T2EX functions,
406: and calls appl_main().
407:
408: appl_main.c
409: This synchronizes the calendar time with the RTC hardware and handles
410: command inputs from the debugging console.
411:
412: command.c
413: This handles basic commands about date/time or file.
414: It also provides the function to display the status of T-Kernel
415: resources.
416: Simple help summary for commands will be shown by "?".
417:
418: ref_command.c
419: This processes of ref command which displays the status of T-Kernel
420: resources.
421: It is included in command.c.
422:
423: network_sample/*
424: Sample programs to test T2EX network function.
425: It can be executed by "net" command. For execution, target needs to
426: be connected to Internet-ready network environment with a DHCP server.
427:
428: For details and limitations on each T2EX function implemented in this package,
429: see "T2EX Implementation Specifications".
430:
431: END.