1: /*
2: *----------------------------------------------------------------------
3: * T2EX Software Package
4: *
5: * Copyright 2012 by Ken Sakamura.
6: * This software is distributed under the T-License 2.0.
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/2/27.
11: *
12: *----------------------------------------------------------------------
13: */
14:
15: ==============================================================================
16: T2EX for T-Engine Reference Board Implementation Specifications
17: ==============================================================================
18:
19: ------------------------------------------------------------------------------
20: 1. Overview
21: ------------------------------------------------------------------------------
22:
23: This specifications describe settings, resource details, and limitations
24: related to the implementation of T-Kernel 2.0 Extension (T2EX) which operates
25: on the T-Engine reference board.
26:
27:
28: ------------------------------------------------------------------------------
29: 2. Differences from T-Kernel 2.0 Reference Implementation
30: ------------------------------------------------------------------------------
31:
32: T2EX implementation is basically created by adding functions to the
33: T-Kernel 2.0 reference implementation, but some modifications are made
34: as well.
35:
36: Following is the list of modifitications made to the original T-Kernel
37: 2.0 reference implementation.
38:
39: - Dispatcher (${BD}/kernel/sysdepend_t2ex/cpu/em1d/cpu_support.S)
40: In order to utilize register exclusive load and store
41: primitives (ldrex and strex) of the processor, clear
42: exclusive (clrex) operation is added to be called at
43: the time of dispatch.
44:
45: - Memory management (${BD}/kernel/extension/memory/t2ex)
46: Details are described later in section 3.
47:
48:
49: ------------------------------------------------------------------------------
50: 3. Memory Protection Function
51: ------------------------------------------------------------------------------
52:
53: 3.1 Basic Setting Items
54:
55: Basic settings of the memory management function in T2EX can be made by
56: rewriting settings in the following source program file.
57:
58: kernel/sysmain/build_t2ex/tef_em1d/Makefile
59:
60: Following parameters can be set:
61:
62: - T2EX_MM
63: Suffix of the name of the memory management function to be used
64: _t2ex : Uses the T2EX standard memory protection function
65: (empty) : Uses the T-Kernel 2.0 standard memory management
66: function (without memory protection)
67:
68: - T2EX_MM_USE_TASKEXCEPTION
69: How to handle memory protection violations
70: 1 : Uses the standard configuration which uses TaskMemFaultHdr()
71: 0 : Uses the simple configuration which does not use
72: TaskMemFaultHdr()
73:
74: - T2EX_MM_USE_DEFAULT_FAULT_HANDLER
75: Where to define memory protection violation handlers
76: 1 : Uses handlers defined internally in T2EX system code
77: 0 : Uses handlers defined in user application
78:
79: Sections 3.2 to 3.6 describe the configuration where T2EX_MM is set to
80: t2ex. The configuration where T2EX_MM is empty, which does not use the
81: T2EX memory protection function, is described in section 3.7.
82:
83: 3.2 MMU Setting
84:
85: It is the same as the T-Kernel 2.0 reference implementation, as shown
86: below. These settings should be set by T-Monitor at system startup and
87: left unchanged (must not be changed) thereafter.
88:
89: (a) SCTLR.AFE [29] = 1
90:
91: Enables the access flag of the page table.
92:
93: (b) SCTLR.TRE [28] = 1
94:
95: Enables the remap of the TEX memory attribute.
96:
97: (c) PRRR = 0x000a8aa4
98:
99: (d) NMRR = 0x44e048e0
100:
101: Allocates the remap of the memory attributes as shown below.
102:
103: TEX[0] C B Memory type Internal cache External cache
104: 0 0 0 Strongly-order None None
105: 0 0 1 Device None None
106: 0 1 0 Normal WT-NA WT-NA
107: 0 1 1 Normal WB-NA WB-NA
108: 1 0 0 Normal None None
109: 1 0 1 Normal WT-NA WB-A
110: 1 1 0 (Not used)
111: 1 1 1 Normal WB-A WB-A
112:
113: WT-NA Write-through, no allocate on write
114: WB-NA Write-back, no allocate on write
115: WB-A Write-back, allocate on write
116:
117: 3.3 Memory Map
118:
119: It is almost the same as the T-Kernel 2.0 reference implementation, as
120: shown below.
121:
122: Local address Mode
123: 0x00000000 +=======================+ ---
124: |Task space | | Virtual memory (Reserved)
125: 0x10000000 +=======================+ ---
126: |Peripheral device | S D RW-
127: |(including unused area)|
128: 0x30000000 +-----------------------+ ---
129: |RAM (64MB) | | Protected memory space
130: |(including unused area)| |
131: 0x40000000 +-----------------------+ ---
132: |Peripheral device | S D RW-
133: |(including unused area)| Physical address
134: 0x70000000 +-----------------------+ --- 0x00000000
135: |ROM (32MB) | S C R-X | Mapping NOR Flash (*1)
136: 0x72000000 +-----------------------+ --- 0x02000000
137: |(Reserved) |
138: 0x80000000 +=======================+ ---
139: |Used for program map | |
140: 0x90000000 +-----------------------+ | Virtual memory (Reserved)
141: |Used for memory map | |
142: 0xa0000000 +=======================+ ---
143: |Built-in SRAM (128KB) | S N RWX
144: |(including unused area)|
145: 0xb0000000 +-----------------------+
146: |Peripheral device | S D RW-
147: |(including unused area)|
148: 0xd0000000 +=======================+ ---
149: |Shared memory space | | Virtual memory (Reserved)
150: 0xf0000000 +=======================+ ---
151: |Built-in Boot ROM | S N R--
152: |(including unused area)|
153: 0xffffffff +-----------------------+
154:
155: Mode
156: Protection level attributes
157: S System level (inaccessible from user level)
158: U User level (accessible from system level and user level)
159:
160: Memory type/Cache attribute
161: C Cache ON Normal memory/Write-back cache, Write allocate
162: N Cache OFF Normal memory/Non-cacheable
163: D Device Device memory / Non-cacheable
164:
165: Access attribute ("-" means the attribute is turned off)
166: R Read enabled
167: W Write enabled
168: X Execution enabled
169:
170: * Domain of each area is 0.
171:
172: * The area specified as protected memory space is managed by the T2EX
173: memory protection function, and the mode is specified per page (4 KB).
174: In areas other than protected memory space, the mapping and mode are
175: specified per section (1 MB).
176:
177: * The areas specified as virtual memory are unused in this
178: implementation and reserved. They are configured as unallocated areas
179: and inaccessible.
180:
181: * The areas other than protected memory and virtual memory space are
182: mapped as logical address = physical address, and the mapping and mode
183: do not change dynamically.
184:
185: (*1) Note that the area for NOR Flash, which is hidden behind the
186: task space, is not mapped as logical address = physical
187: address but is mapped by moving it as the memory map shown
188: above. This mapping does not change dynamically.
189:
190: Addresses in this specifications means logical addresses unless
191: otherwise stated.
192:
193: * The built-in SRAM and built-in Boot ROM are used at system startup
194: (boot). After system startup, they are not used and managed by OS.
195: After system startup, the built-in SRAM can be used for any
196: application.
197:
198: * In the protected memory space, the areas used by dynamic memory
199: allocation API calls like tk_get_smb() and malloc() and internal
200: dynamic memory allocation by the system are called dynamic allocation
201: areas. In the initial state, these areas are specified as
202: inaccessible. Once allocated, they become accessible, and then revert
203: to inaccessible mode when released.
204:
205: * The memory areas other than the dynamic allocation areas are called
206: static allocation areas, for which the mode is statically specified.
207: Unlike the dynamic memory spaces, fixed modes are assigned to these
208: areas when T2EX is initialized. Appropriate mode can be assigned
209: to each application by properly changing the T2EX initialization
210: process.
211:
212: 3.4 Static Allocation Area
213:
214: This section describes the implementation overview of the static
215: allocation area in this implementation and how to change it depending
216: on an application.
217:
218: 3.4.1 Initialization
219:
220: The implementation uses sections in ELF object (linker sections) to
221: allocate static allocation areas. This means that a linker section is
222: mapped to a memory space containing symbols with the same mode, and
223: thus the memory space is specified via the linker section.
224:
225: The following files are used to set static allocation areas.
226:
227: - kernel/sysmain/build_t2ex/tef_em1d/kernel_t2ex-rom.lnk
228: - kernel/sysmain/build_t2ex/tef_em1d/kernel_t2ex-ram.lnk
229: Specifies the linker section that symbols belong to.
230: That is, this specifies the mode of the memory space that
231: symbols belong to.
232:
233: - kernel/extension/memory/t2ex/sysdepend/em1d/space.c
234: Specifies the mode for each static area.
235: (InitLogicalSpace Function)
236:
237: - kernel/sysdepend_t2ex/device/tef_em1d/icrt0_t2ex.S or icrt0_t2ex_ram.S
238: Initializes the content of the memory space including static
239: areas.
240:
241: As a specific example, kernel_t2ex-rom.lnk defines .data_usr and .bss_usr,
242: which are linker sections for user level data areas as follows.
243: This rule defines that both the .data_usr and .bss_usr. sections
244: include the data areas in object files whose filename is "*.uo".
245: These two sections are allocated contiguously, and __data_usr_start
246: and _end_usr symbols are defined at the top and end of them
247: respectively.
248:
249: __data_usr_org = LOADADDR(.bss) + SIZEOF(.bss);
250: .data_usr ALIGN(0x1000) : AT(__data_usr_org) {
251: __data_usr_start = . ;
252: *.uo(.data)
253: *.uo(.data.*)
254: *.uo(.data1)
255: KEEP (*.uo(.eh_frame))
256: *.uo(.gcc_except_table)
257: *.uo(.sdata)
258: *.uo(.sdata.*)
259: . = ALIGN(4);
260: _edata_usr = .;
261: PROVIDE (edata_usr = .);
262: }
263: .bss_usr ALIGN(4) : {
264: __bss_usr_start = .;
265: PROVIDE (__sbss_usr_start = .);
266: PROVIDE (___sbss_usr_start = .);
267: *.uo(.sbss)
268: *.uo(.sbss.*)
269: *.uo(.scommon)
270: PROVIDE (__sbss_usr_end = .);
271: PROVIDE (___sbss_usr_end = .);
272: *.uo(.bss)
273: *.uo(.bss.*)
274: *.uo(COMMON)
275: . = ALIGN(4);
276: _end_usr = .;
277: PROVIDE (end_usr = .);
278: }
279:
280: The InitLogicalSpace function in space.c uses this information for
281: initialization. Specifically, the following code initializes the area
282: from __data_usr_start to _end to the mode PTE_USR_RW
283: (user-accessible and readable/writable).
284: (la = __data_usr_start when this code is executed.)
285:
286: for ( ; (UW)la < (UW)&_end_usr; la = NextPage(la) ) {
287: /* User data area (__data_usr_start ... _end_usr) */
288: pte.w = PTE_USR_RW;
289: pte.a.pfa = LADRtoPFA(la);
290: SetPTE(la, pte, FALSE);
291: }
292:
293: icrt0_t2ex.S corresponds to icrt0.S in the T-Kernel 2.0 standard
294: implementation. However, since the BSS area are divided into two
295: areas, .bss, and .bss_usr, it has been changed to initialize each of
296: them separately. Modification of this file is required if an
297: initialization different from the previous one is to be performed
298: due to the change to the memory space.
299:
300: 3.4.2 Static Setting in Reference Implementation
301:
302: Based on the implementation described in section 3.4.1, the reference
303: implementation configures the static allocation area as described
304: below. A name in [] is a linker section name that each symbol is
305: assigned to.
306:
307: ---------------------------------------------------------------------
308: Area Privileged level User level
309: =====================================================================
310: User-level program area [.text] R,EX R,EX
311: Read-only data area [.rodata] R,EX R,EX
312: Privileged-level read/write data area R,W -
313: [.data, .bss]
314: User-level read/write data area R,W R,W
315: [.data_usr, .bss_usr]
316: ---------------------------------------------------------------------
317:
318: The mode setting in the reference implementation is generally basic
319: and conservative except that the write privilege to the system area
320: from the user level is disallowed entirely. Specifically, the
321: following operation is allowed and does no cause a protection
322: violation because the protection level is not distinguished between
323: the program area and the read-only data area.
324:
325: - Access to a static system program code from the user level
326:
327: This configuration intends to use codes from both the system and a
328: user program and share read-only data. For example, this configuration
329: allows codes in the SVC interface library (libsvc.a) to be shared,
330: which allows saving ROM or RAM occupied by a program code.
331:
332: 3.4.3 Data Area Allocation
333:
334: In Makefile of the T2EX reference implementation, the previous SRC is
335: divided into two parts: SRC_SYS for the system area and SRC_USR for
336: the user area.
337:
338: Data areas (.data and .bss) that can be read/written by objects linked
339: to the kernel are allocated to different spaces, depending on which is
340: specified for a source file, SRC_SYS or SRC_USR, as follows.
341:
342: - SRC_SYS: Allocated to a privileged-level read/write data area
343: (.data, .bss)
344: - SRC_USR: Allocated to a user-level read/write data area
345: (.data_usr, .bss_usr)
346:
347: Specification of SRC_SYS or SRC_USR can be performed using one of the
348: following files.
349:
350: kernel/sysmain/build_t2ex/tef_em1d/Makefile
351: kernel/sysmain/build_t2ex/Makefile.common
352:
353: 3.5 Protection Violation (Exception)
354:
355: An access to an unallocated dynamic area or a memory access against
356: the mode specification causes a memory protection violation,
357: and the protection violation exception is handled.
358:
359: When T2EX_MM_USE_DEFAULT_FAULT_HANDLER is set to 1, protection violation
360: exception handlers are defined in the following file. TaskMemFaultHdr()
361: and RawMemFaultHdr() in this file can be adequately modified to handle
362: exceptions properly.
363:
364: kernel/extension/memory/t2ex/sysdepend/em1d/exchdr.c
365:
366: This implementation defines these handlers for reference as
367: described below.
368:
369: - RawMemFaultHdr()
370: Intended to support debugging. It outputs a
371: "*** OS SYSTEM DOWN ***" message and transitions to T-Monitor.
372:
373: - TaskMemFaultHdr()
374: Sends a task exception with exception code 0 to the task
375: causing the exception.
376: A task can define the task exception handler for exception
377: handling to handle protection violation exceptions per task.
378: If it fails to send a task exception (or the target task does
379: not have the task exception handler implemented), it outputs a
380: "*** OS SYSTEM DOWN ***" message and transitions to T-Monitor
381: just like RawMemFaultHdr().
382:
383: On the other hand, when T2EX_MM_USE_DEFAULT_FAULT_HANDLER is set to 0,
384: the above sample handler implementations are not linked, and thus
385: needed to be defined in user applications.
386:
387: 3.6 Implementation Restrictions
388:
389: There is the following restriction:
390:
391: - The mode cannot be changed for a static area managed per section
392: (1 MB).
393:
394: 3.7 Not Using T2EX Memory Protection Function
395:
396: If T2EX memory protection function is not to be used, perform following
397: settings:
398:
399: - kernel/sysmain/build_t2ex/tef_em1d/Makefile
400: Set T2EX_MM to empty (for details, see section 3.1)
401:
402: - kernel/sysdepend_t2ex/cpu/em1d/cpu_conf.h
403: Set USE_MMU to 0.(It is set to 1 by default)
404:
405: For operations with these settings, see T-Kernel 2.0 implementation
406: specifications.
407:
408:
409: ------------------------------------------------------------------------------
410: 4. File Management Function
411: ------------------------------------------------------------------------------
412:
413: 4.1 Special File System
414:
415: The file management function uses the two special file systems described
416: below as well as the "basic FAT file system".
417:
418: (1) Root file system
419:
420: A virtual file system that corresponds to the root directory "/" to
421: connect the file system to.
422:
423: File system implementation part name "rootfs"
424: Connection name "/" (special name)
425: Subdirectory <Connection name of a connected file system>
426:
427: It is not possible to disconnect the root file system or unregist the
428: implementation part.
429:
430: (2) Console file system
431:
432: A file system that supports the console device to treat standard console
433: input and output as files.
434:
435: File system implementation part name "consolefs"
436: Connection name "console"
437: Files "stdin", "stdout", "stderr"
438:
439: It is not possible to disconnect the console file system or unregist the
440: implementation part. The above three files are fixed. It is not possible
441: to delete or add files.
442:
443: The console file system uses the following APIs in the console driver to
444: operate the console.
445:
446: ConsoleIO() Initialization
447: console_conf() Configuration
448: console_in() Input
449: console_out() Output
450:
451:
452: 4.2 File Management Common Part
453:
454: 4.2.1 System Configuration Information
455:
456: FsMaxFile Number of files that can be opened at the same time
457: (system-wide)
458:
459: This specifies the number of files that can be opened at the same time
460: from application tasks in the whole system. It does not include the
461: standard input/output files (stdin, stdout, and stderr) which are opened
462: automatically.
463: It must be two or more.
464:
465: FsMaxFIMP Number of file system implementation parts that can be
466: registered at the same time
467:
468: This specifies the number of file system implementation parts that can
469: be registered at the same time in the whole system. It does not include
470: the root file system implementation part and the console file system
471: implementation part which are registered automatically, but includes the
472: basic FAT file system implementation part.
473: It must be one or more.
474:
475: FsMaxCON Number of file system connections that can be connected at the
476: same time
477:
478: This specifies the number of file system connections that can be
479: connected at the same time in the whole system. It does not include the
480: root file system and the console file system which are connected
481: automatically.
482: It must be one or more.
483:
484: * These settings directly affect the dynamic memory consumption. They
485: should be set to the required minimal values.
486:
487: 4.2.2 Kernel Object
488:
489: File Managemet Common Part consumes the following kernel objects.
490:
491: ----------------------
492: Kind Number
493: ======================
494: Subsystem 1
495: Event Flag 1
496: ----------------------
497:
498: 4.2.3 Dynamic Memory Allocation
499:
500: File Managemet Common Part allocates/releases the following sizes of
501: memory by Kmalloc() / Kfree() dynamically.
502:
503: ---------------------------------------------------
504: Memory size to be allocated dynamically (in bytes)
505: ===================================================
506: At initialization: (not released until exited)
507: 8 * ( TMaxTskId )
508: 4 * ( TMaxTskId )
509: 4 * ( FsMaxFile + 3 ) + 16
510: 24 * ( FsMaxFile + 3 )
511: 76 * ( FsMaxFIMP + 2 )
512: 60 * ( FsMaxCON + 2 )
513: PATH_MAX( =1024 ) * 2
514: ---------------------------------------------------
515: Temporary:
516: PATH_MAX( =1024 )
517: ---------------------------------------------------
518:
519: 4.2.4 Implementation of APIs
520:
521: The file management function basically implements APIs as extended SVC,
522: except for the following ones implemented as libraries.
523:
524: (1) To handle variable arguments
525: int fs_open(const char *path, int oflag, ... /* mode_t mode */ );
526: int fs_ioctl(int fd, int request, ... /* arg */ );
527: int fs_fcntl(int fd, int cmd, ... /* arg */ );
528:
529: (2) To replace an equivalent API
530: int fs_creat(const char *pathname, mode_t mode);
531: --> fs_open(pathname, O_WRONLY | O_CREAT | O_TRUNC, mode);
532:
533: (3) To handle return codes
534: off_t fs_lseek(int fd, off_t offset, int whence);
535: off64_t fs_lseek64(int fd, off64_t offset64, int whence);
536:
537: 4.2.5 Case-sensitivity in Current Directory
538:
539: The current directory is managed by the file management function
540: (common part). A path name string set by fs_chdir() will be returned by
541: fs_getcwd() as it is.
542: Therefore, uppercase and lowercase in the path name may not match with
543: the real filename in a file system that is case-insensitive like the
544: FAT file system.
545:
546: Example: For the directory /FAT/local/bin/, fs_getcwd() returns
547: "/FAT/Local/BIN" after fs_chdir("/FAT/Local/BIN") is executed,
548: but it returns "/FAT/LOCAL/bin" after fs_chdir("/FAT/LOCAL/bin")
549: is executed.
550:
551: When fs_fchdir() is used, the result depends on the behavior of the file
552: system implementation part.
553:
554:
555: 4.3 Basic FAT File System Implementation Part (Basic FAT FIMP)
556:
557: 4.3.1 System Configuration Information
558:
559: FsAccessTime Whether or not to allow updating the time of last data
560: access
561:
562: This specifies whether or not to update the time of last data access. If
563: this is 0, the time of last data access is not updated. If this is not 0,
564: writing to the file system may occur to update the time of last data
565: access, even if there is no file that is created or written to.
566: (In the FAT file system, access time is managed per day, and the writing
567: does not occur unless the day changes from the date of last data access.)
568:
569: FiFAT_TskPri Task priority
570:
571: This specifies the priority of tasks that actually perform operations to
572: the file system. Although there is no dependency on other tasks,
573: generally, a higher priority than application tasks should be specified.
574:
575: FiFAT_StkSz Task stack size
576:
577: Stack size of tasks that actually perform operations to the file system.
578: No need to change it from 2048, which is the default.
579:
580: FiFAT_FCacheSz FAT cache size (in bytes)
581: FiFAT_FCacheNs Number of FAT cache unit sectors
582:
583: This specifies the cache size to access to the FAT area.
584: The number of unit sectors specifies the number of sectors per page which
585: is a unit of disc I/O. Specify 1 or a multiple of 2.
586:
587: Page size = Number of unit sectors * Disc sector size (usually 512 bytes)
588: Real cache size = ( Cache size / Page size ) * Page size
589:
590: FiFAT_RCacheSz Root directory cache size (bytes)
591: FiFAT_RCacheNs Number of root directory cache unit sectors
592:
593: This specifies the cache size to access to the FAT12/16 root directory
594: area. Not used in FAT32.
595: The number of unit sectors specifies the number of sectors per page
596: which is a unit of disc I/O. Specify 1 or a multiple of 2.
597:
598: Page size = Number of unit sectors * Disc sector size (usually 512 bytes)
599: Real cache size = ( Cache size / Page size ) * Page size
600:
601: FiFAT_DCacheSz Data cache size (in bytes)
602: FiFAT_DCacheNs Number of data cache unit sectors
603:
604: This specifies the cache size used to access to data area (cluster area)
605: of files/directories.
606: The number of unit sectors specifies the number of sectors per page
607: which is a unit of disc I/O. Specify 0, 1, or a multiple of 2. When 0 is
608: specified, the cluster size is used.
609:
610: Page size = Number of unit sectors * Disc sector size (usually 512 bytes)
611: or Cluster size (when the number of unit sectors is 0)
612: Real cache size = ( Cache size / Page size ) * Page size
613:
614: 4.3.2 Kernel Object
615:
616: Basic FAT FIMP consumes the following kernel objects for each connected
617: file system.
618:
619: ----------------------
620: Kind Number
621: ======================
622: Task 1
623: Rendezvous 1
624: ----------------------
625:
626: Operations to one connected file system are actually performed by one
627: task sequentially. The rendezvous is used to send process requests to the
628: task and receive process results from the task. The message size of a
629: rendezvous is 4 bytes.
630:
631: 4.3.3 Dynamic Memory Allocation
632:
633: Basic FAT FIMP allocates/releases the following sizes of memory by
634: Kmalloc() / Kfree() dynamically.
635:
636: ---------------------------------------------------------------
637: Memory size to be allocated dynamically (in bytes)
638: ===============================================================
639: At file system connection: (not released until disconnected)
640: 2,596
641: 44 * ( FiFAT_FCacheSz / ( FiFAT_FCacheNs * 512 ) )
642: 44 * ( FiFAT_RCacheSz / ( FiFAT_RCacheNs * 512 ) ) (*1)
643: 44 * ( FiFAT_FCacheSz / ( FiFAT_FCacheNs * 512 ) )
644: (512 + 44) * 2
645: 4 * ( FsMaxFile )
646: ---------------------------------------------------------------
647: At file open: (not released until closed)
648: 60 + 24
649: 80 * N (*2)
650: PATH_MAX(=1024) (*3)
651: ---------------------------------------------------------------
652:
653: (*1) Only used in FAT12/16. not in FAT32.
654: (*2) N = Number of contiguous clusters comprising the file / 10.
655: If every comprising cluster is located discontiguously, the number
656: of contiguous clusters is File size / Cluster size.
657: (*3) Only used when opening directory.
658:
659: 4.3.4 Considerations/Restrictions
660:
661: (1) Supports the FAT12, FAT16, and FAT32 file system.
662:
663: (2) Supports the short filename (SFN) and the long filename (LFN).
664:
665: MS-KANJI (CP932) is used for the character code of the short filename.
666:
667: If only ASCII characters are used in filenames, "FAT_ASCII_FN_ONLY" can
668: be defined at build to make the code translation table unnecessary
669: and to significantly reduce the code size.
670:
671: (3) Does not support reallocation of a directory.
672:
673: Contiguous directory entries are needed for the long filename (LFN).
674: When there is not enough space for contiguous directory entries in
675: creating a file, it is addressed by adding new clusters to enlarge the
676: directory instead of reallocating directory entries to make a contiguous
677: space.
678:
679: Note that creating file may cause an error in FAT12 and FAT16 even if
680: there is enough space for directory entries because it is not possible
681: to enlarge the root directory.
682:
683: (4) No guarantee of unique file serial numbers.
684:
685: The FAT file system does not have the file serial number. The position
686: from the beginning of the disk for the directory entry corresponding to
687: a file is used as the file serial numbers.
688:
689: Therefore, the file serial number has a 64-bit size, not 32-bit.
690: Because the file management function provides 32-bit APIs, they return
691: the lower 32 bits of 64 bits as the file serial number. This means that
692: different files can have the same file serial number. However,
693: it is guaranteed that all files in the same directory have unique file
694: serial numbers.
695:
696: (5) Path name of the current directory
697:
698: A path name of the current directory retuned by fs_fchdir() reflects
699: upper/lower cases of the filenames correctly, which requires a path
700: traversal.
701:
702: If it does not need to be case sensitive, "FAT_CURDIR_CASE_NOCARE" can be
703: defined at build to accelerate the fs_fchdir() operation and to reduce
704: the code size a bit.
705:
706:
707: ------------------------------------------------------------------------------
708: 5. Network Communication Function
709: ------------------------------------------------------------------------------
710:
711: 5.1 LAN driver
712:
713: The network communication function of the T2EX reference implementation
714: uses the LAN driver for the network interface card (NIC) of the T-Engine
715: reference board (tef_em1d), which conforms to the "T-Engine Standard
716: Device Driver Specifications". The LAN driver is provided in the T2EX
717: source code package and can be used both on an actual machine (tef_em1d)
718: and on an emulator for tef_em1d (QEMU-tef_em1d).
719:
720: The LAN driver is the only hardware-dependent part in the network
721: communication function. When the network communication function in the
722: T2EX reference implementation is ported to other hardware, only the LAN
723: driver requires modifications or rewrites to adapt to other target
724: systems.
725:
726: 5.2 Maximum Number of Sockets that can be Opened at the Same Time
727:
728: The maximum number of sockets that can be opened at the same time can be
729: specified by the system configuration information SoMaxSocket. It is the
730: total of sockets generated by so_socket() and so_accept().
731:
732: For the number of consumed kernel objects required to generate one
733: socket, see "5.7 Kernel Object".
734:
735: 5.3 Maximum Number of Device Drivers that can be Connected
736:
737: The number of device drivers that can be connected to the network
738: connection manager by so_ifattach() is limited. It is defined by
739: TKN_NIFDEV_MAX in the following header file.
740:
741: ${BD}/t2ex/network/net/src/netmain/tkn_init.h
742:
743: #define TKN_NIFDEV_MAX 3
744:
745: 5.4 Buffer Registered with LAN Driver
746:
747: (1) Number of buffers to be registered
748:
749: When so_ifattach() connects a device driver, buffers required for
750: reception are registered with the device driver. The number of receive
751: buffers registered with the device driver is set by the system
752: configuration information SoDrvRxBufNum.
753:
754: (2) Buffer size
755:
756: The size of a buffer registered with a device driver is 1520, which is
757: the maximum frame size of Ethernet. This value is defined by
758: TKN_RXBUF_SIZE in the following header file.
759:
760: ${BD}/t2ex/network/net/src/netmain/if_tkn.h
761:
762: #define TKN_RXBUF_SIZE 1520
763:
764: 5.5 Buffer Size of Socket Send/Receive Queue
765:
766: Here are the default values of the system configuration information
767: related to the buffer size for socket send/receive queue.
768:
769: ----------------------------------------------------
770: System configuration information Size (in bytes)
771: ====================================================
772: SoTcpTxBufSz 32,768
773: SoTcpRxBufSz 32,768
774: SoUdpTxBufSz 9,216
775: SoUdpRxBufSz 41,600
776: SoRawIPTxBufSz 8,192
777: SoRawIPRxBufSz 8,192
778: SoRawTxBufSz 8,192
779: SoRawRxBufSz 8,192
780: ----------------------------------------------------
781:
782: The maximum window size for the TCP flow control depends on the buffer
783: size of the send or receive queue. When the system configuration
784: information SoTcpDoAutoTx and SoTcpDoAutoRx are set to 1, the buffer
785: size of the send or receive queue are changed dynamically according to
786: the window size of the peer (automatic resizing). Their default values
787: are 0.
788:
789: Here are the default values of the system configuration information
790: related to the automatic resizing.
791:
792: ---------------------------------------------------
793: System configuration information Size (in bytes)
794: ===================================================
795: SoTcpIncAutoTx 16,384
796: SoTcpMaxAutoTx 262,144
797: SoTcpIncAutoRx 16,384
798: SoTcpMaxAutoRx 262,144
799: ---------------------------------------------------
800:
801: 5.6 Changes in Dynamic Memory Allocation
802:
803: The old source code, from which the current code is derived, allocates a
804: few KB buffer on the stack. The previous implementation is not
805: satisfactory for build-in devices. They are improved to dynamically
806: allocate buffers by malloc() and so on.
807:
808: ---------------------------------------------------------------
809: Function name File path
810: ===============================================================
811: res_queryN() net/src_bsdlib/libc/net/getaddrinfo.c
812: getanswer() net/src_bsdlib/libc/net/getaddrinfo.c
813: _gethtent() net/src_bsdlib/libc/net/getaddrinfo.c
814: res_querydomainN() net/src_bsdlib/libc/net/getaddrinfo.c
815: getanswer() net/src_bsdlib/libc/net/gethnamaddr.c
816: res_nquery() net/src_bsdlib/libc/resolv/res_query.c
817: res_nquerydomain() net/src_bsdlib/libc/resolv/res_query.c
818: res_nameinquery() net/src_bsdlib/libc/resolv/res_send.c
819: res_queriesmatch() net/src_bsdlib/libc/resolv/res_send.c
820: ---------------------------------------------------------------
821: (*) "${BD}/t2ex/network/" is omitted from the file paths.
822:
823: The dynamically allocated buffer sizes are defined in the following
824: header file.
825:
826: ${BD}/t2ex/network/net/src_bsdlib/libc/include/port_before.h
827:
828: #define T2EX_NS_MAXPACKET (64*1024)
829: #define T2EX_NS_HOSTBUFSZ (8*1024)
830: #define T2EX_NS_MAXDNAME (1025)
831: #define T2EX_NS_THRESHOLD (1024)
832:
833: T2EX_NS_MAXPACKET
834: Buffer size to send/receive DNS packets
835: - res_queryN() [getaddrinfo.c]
836:
837: T2EX_NS_HOSTBUFSZ
838: Buffer size to receive and analyze DNS packets
839: - getanswer() [getaddrinfo.c]
840: - _gethtent() [getaddrinfo.c]
841:
842: T2EX_NS_MAXDNAME
843: Buffer size to expand or compress DNS host names
844: - getanswer() [getaddrinfo.c]
845: - res_querydomainN() [getaddrinfo.c]
846: - getanswer() [gethnamaddr.c]
847: - res_nquerydomain() [res_query.c]
848: - res_nameinquery() [res_send.c]
849: - res_queriesmatch() [res_send.c]
850:
851: T2EX_NS_THRESHOLD
852: Buffer size for DNS query packets
853: - res_nquery() [res_query.c]
854:
855: 5.7 Kernel Object
856:
857: (1) Kernel objects consumed when initializing the network communication
858: function
859:
860: When so_main() initializes the network communication function, the
861: following kernel objects are consumed.
862:
863: -----------------------
864: Kind Number
865: =======================
866: Task 6
867: Semaphore 5
868: Event Flag 5
869: Mutex 1
870: Rendezvous 1
871: Cyclic Handler 1
872: Subsystem 1
873: -----------------------
874:
875: (2) Kernel objects consumed when connecting a device driver
876:
877: When so_ifattach() connects a device driver, the following kernel
878: objects are consumed.
879:
880: --------------------------
881: Kind Number
882: ==========================
883: Task 1
884: Message Buffer 1
885: --------------------------
886:
887: (3) Kernel objects consumed by generating a socket
888:
889: When so_socket() or so_accept() generates one socket, the following
890: number of kernel objects are consumed.
891:
892: -------------------------------------------
893: Kind Number
894: ===========================================
895: Event Flag ceil(2/32) + ceil(4/32)
896: -------------------------------------------
897:
898: "2/32" and "4/32" in this table mean 2 bits and 4 bits of the event flag
899: respectively. ceil() is the ceiling function. ceil(x) represents the
900: minimum integer that is equal to or larger than a real number x.
901:
902: When the total number of sockets generated by so_socket() and
903: so_accept() is N, the following number of event flags are needed.
904:
905: ceil((2*N)/32) + ceil((4*N)/32)
906:
907: (Calculation example) when N=9
908: ceil((2*9)/32) + ceil((4*9)/32)
909: = ceil(18/32) + ceil(36/32)
910: = 1 + 2
911: = 3
912:
913: (4) Kernel objects required for the network communication function
914:
915: Supposing that the maximum number of connected device drivers is D and
916: the maximum number of generated sockets is S (which is equal to the
917: system configuration information SoMaxSocket), they are summarized as
918: follows.
919:
920: --------------------------------------------------------------------
921: Kind Number
922: ====================================================================
923: Task 6 + D
924: Semaphore 5
925: Event Flag 1 + ceil((57 + 2*S)/32) + ceil((37 + 4*S)/32)
926: Mutex 1
927: Message Buffer D
928: Rendezvous 1
929: Cyclic Handler 1
930: Subsystem 1
931: --------------------------------------------------------------------
932:
933: The constants (57 and 37) in the ceiling functions of the event flag are
934: numbers of bits consumed by initialization with so_main().
935:
936: 5.8 Runtime Environment Setting
937:
938: No item is required to be set to verify the operation on the T-Engine
939: reference board (tef_em1d). Check that the LAN cable is connected to the
940: body before running a program.
941:
942: This section describes how to set up the runtime environment to use the
943: T2EX network communication function on an emulator (QEMU-tef_em1d) for
944: the T-Engine reference board (tef_em1d).
945:
946: Parameters can be set at startup to allow QEMU-tef_em1d to use a virtual
947: network device (TAP) on the host OS, as described in QEMU-tef_em1d guide.
948:
949: The network needs to be properly configured in order to allow
950: communication between QEMU-tef_em1d and the host OS. In this document,
951: we configure the network communication between QEMU-tef_em1d and the
952: host OS through bridge connection and allow direct access from
953: QEMU-tef_em1d to the physical network.
954:
955: (1) Prerequisite
956:
957: (a) Host OS
958:
959: Windows 7, Windows Vista, Windows XP
960: (depending on the host OS where QEMU-tef_em1d operates)
961:
962: Windows administer privilege is required to perform the following tasks.
963:
964: (2) TAP device
965:
966: (a) Install OpenVPN
967:
968: Download the OpenVPN installer from the following URL.
969:
970: http://openvpn.net/index.php/download/community-downloads.html
971: (Download from the link "Windows Installer")
972:
973: Execute the downloaded "openvpn-2.2.2-install.msi" and follow
974: instructions on screens to install OpenVPN.
975:
976: When the following message appears during installation, select
977: "Install".
978:
979: Would you like to install this device software?
980: Name: TAP-Win32 Provider V9 Network Adapter
981: Publisher: OpenVPN Technologies, Inc.
982:
983: (b) Changing TAP device name
984:
985: The name of the TAP device installed by OpenVPN may include Japanese
986: characters. Because QEMU-tef_em1d cannot use such a name, it must be
987: renamed to an acceptable one as shown in the following steps.
988:
989: Display "Network Connections" in following steps.
990:
991: - For Windows 7
992:
993: 1) From the Start menu, open "Control Panel".
994: 2) Click "View network status and tasks".
995: 3) Click "Change adapter settings".
996:
997: - For Windows Vista
998:
999: 1) From the Start menu, open "Control Panel".
1000: 2) Click "Network and Internet".
1001: 3) Click "Network Center".
1002: 4) Click "Manage network connections".
1003:
1004: - For Windows XP
1005:
1006: 1) From the Start menu, open "Control Panel".
1007: 2) Click "Network and Internet Connections".
1008: 3) Click "Network Connections".
1009:
1010: An adapter labeled with "TAP-Win32 Adapter V9" is the TAP device
1011: installed by OpenVPN. Right-click it and select "Rename".
1012:
1013: It can be changed to any name that includes only ASCII characters
1014: without spaces. "MY-TAP" is used in the following descriptions.
1015:
1016: (3) Bridge connection
1017:
1018: Display "Network Connections". (See (2)(b))
1019:
1020: Determine the network adapter that is used by the host PC. Ctrl-click
1021: the network adapter and the TAP device just created. Right-click one of
1022: the selected adapters and click "Bridge Connection".
1023:
1024: (4) Parameters for QEMU-tef_em1d
1025:
1026: qemu-net.bat can be found in ${BD}/kernel/sysmain/src/network_sample/.
1027: Copy this file to the QEMU-tef_em1d install directory "C:\qemu\bin\".
1028: To run a program that uses the network connection function, use
1029: qemu-net.bat instead of qemu.bat.
1030:
1031: qemu-net.bat adds the following options to qemu.bat. Modify them as
1032: needed for your environment.
1033:
1034: -net nic,macaddr=52:54:00:12:34:56
1035:
1036: This sets the MAC address of NIC in QEMU-tef_em1d. To run more than
1037: one QEMU-tef_em1d, set unique MAC addresses for them. A sample using
1038: the following MAC addresses is described in the man page of the
1039: original QEMU.
1040:
1041: 52:54:00:12:34:56, 52:54:00:12:34:57, 52:54:00:12:34:58
1042:
1043: -net tap,ifname=MY-TAP
1044:
1045: This sets the TAP device name.
1046:
1047: 5.9 Network Operation Check
1048:
1049: This section describes how to check network operations by using a sample
1050: program.
1051:
1052: (1) Modifying source code
1053:
1054: Modify appl_main() in ${BD}/kernel/sysmain/src/appl_main.c as follows.
1055: Include the header file net_test.h required for the following function
1056: call.
1057:
1058: #include "network_sample/net_test.h"
1059:
1060: Add the following function call to appl_main().
1061:
1062: net_test();
1063:
1064: The net_test() function assumes the address is set by DHCP. To use a
1065: static address, configure the macros related to IP address settings,
1066: then modify the parameters passed to net_conf() in net_test() in the
1067: following file. For details, see "(1) Setting network interface" in
1068: "5.11 Network Utility".
1069:
1070: ${BD}/kernel/sysmain/src/network_sample/net_test.c
1071:
1072: (2) Building network sample program
1073:
1074: Add the following line to the bottom of
1075: ${BD}/kernel/sysmain/build_t2ex/tef_em1d/Makefile to include Makefile.sample
1076: for building the sample program.
1077:
1078: include ../../src/network_sample/Makefile.sample
1079:
1080: Execute make in the following directory as usual.
1081:
1082: ${BD}/kernel/sysmain/build_t2ex/tef_em1d
1083:
1084: (3) Verifying network sample program
1085:
1086: On an actual machine, transfer and execute the program as usual. On the
1087: emulator, execute the built binary from qemu-net.bat, which is
1088: configured in 5.8(4).
1089:
1090: Results about the network interface setting and sample program
1091: operations are printed.
1092:
1093: 5.10 Program Development using Network Communication Function
1094:
1095: In order to communicate using the socket provided by the network
1096: communication function, initialization of the network communication
1097: function and proper setup of network interface is required.
1098:
1099: (1) Initializing network communication function
1100:
1101: so_main(0, NULL);
1102:
1103: (2) Setting network interface
1104:
1105: Call net_conf(), which is called from net_test() in the sample program,
1106: to configure the required address setting for the network interface Neta.
1107:
1108: For net_conf() and other utilities, see "5.11 Network Utility".
1109:
1110: The socket for communication can be used once the network interface
1111: setting is complete.
1112:
1113: 5.11 Network Utility
1114:
1115: Sample programs for network utilities are provided.
1116:
1117: To build network utilities, add the following line to the bottom of
1118: ${BD}/kernel/sysmain/build_t2ex/tef_em1d/Makefile.
1119:
1120: include ../../src/network_sample/Makefile.sample
1121:
1122: Execute make in the following directory as usual.
1123:
1124: ${BD}/kernel/sysmain/build_t2ex/tef_em1d
1125:
1126: (1) Setting network interface
1127:
1128: #include "network_sample/util.h"
1129: int net_conf(int emu, int dhcp);
1130:
1131: Parameter
1132:
1133: int emu whether it is the emulator or not
1134: int dhcp how to set address
1135:
1136: Description
1137:
1138: This sets the network interface Neta. Before calling it, use so_main()
1139: to initialize the network communication function.
1140:
1141: - loop-back device setting
1142: - network interface Neta setting
1143: - default gateway setting
1144: - DNS related setting
1145: - host name table setting
1146:
1147: net_conf() internally uses functions described in 5.11(3) or later in
1148: addition to T2EX API calls.
1149:
1150: When executing on an actual machine, specify 0 in emu. When executing
1151: on the emulator, specify 1 in emu. The following constant is defined
1152: for emu.
1153:
1154: #define NET_CONF_MACHINE (0)
1155: #define NET_CONF_EMULATOR (1)
1156:
1157: Specify 1 in dhcp to set DHCP address. Specify 0 in dhcp to set
1158: static address. The following constants are defined for dhcp.
1159:
1160: #define NET_CONF_STATIC (0)
1161: #define NET_CONF_DHCP (1)
1162:
1163: In addition, when using the static address, directly edit macros
1164: defined at the top of the following file.
1165:
1166: ${BD}/kernel/sysmain/src/network_sample/net_conf.c
1167:
1168: - IPADDR: IP address
1169: - NETMASK: Net mask
1170: - GATEWAY: Gateway
1171: - DNSSERVER1: First DNS server (Comment it out if not required)
1172: - DNSSERVER2: Second DNS server (Comment it out if not required)
1173: - DNSSERVER3: Third DNS server (Comment it out if not required)
1174: - DNSDOMAIN: DNS search domain (Comment it out if not required)
1175:
1176: Example (using DHCP on the actual machine)
1177:
1178: net_conf(NET_CONF_MACHINE, NET_CONF_DHCP);
1179:
1180: Example (using the static address on the emulator)
1181:
1182: net_conf(NET_CONF_EMULATOR, NET_CONF_STATIC);
1183:
1184: (*) Make sure that the above macros in net_conf.c are set correctly
1185:
1186: (2) Displaying network interface information
1187:
1188: #include "network_sample/util.h"
1189: void net_show(void);
1190:
1191: Description
1192:
1193: This displays the following information related to the network
1194: interface.
1195:
1196: - address information set for the network interface
1197: - DNS related setting
1198: - host name table
1199: - routing information
1200:
1201: (3) Setting network interface address
1202:
1203: #include "network_sample/util.h"
1204: void set_ifaddr(const char* ifname, in_addr_t addr, in_addr_t mask)
1205:
1206: Parameter
1207:
1208: const char* ifname interface name
1209: in_addr_t addr address
1210: in_addr_t mask network mask
1211:
1212: Description
1213:
1214: This sets the address addr and the network mask mask for the
1215: interface specified by ifname.
1216:
1217: (4) Starting/stopping network interface
1218:
1219: #include "network_sample/util.h"
1220: int if_updown(const char* ifname, int is_up)
1221:
1222: Parameter
1223:
1224: const char* ifname interface name
1225: int is_up starts/stops the interface
1226:
1227: Description
1228:
1229: This starts or stops the interface specified by ifname.
1230:
1231: To start the interface, specify a non-zero value in is_up. To stop the
1232: interface, specify 0 in is_up.
1233:
1234: (5) Adding a route
1235:
1236: #include "network_sample/route.h"
1237: void route_add(in_addr_t dest, in_addr_t gate, in_addr_t mask,
1238: int index, int direct);
1239:
1240: Parameter
1241:
1242: in_addr_t dest destination address
1243: in_addr_t gate gateway address
1244: in_addr_t mask network mask
1245: int index interface index
1246: int direct value indicating whether directly accessible
1247: to the destination address or not
1248:
1249: Description
1250:
1251: This adds the routing information specified by the destination address
1252: dest, the gateway address gate, and the network mask mask to the
1253: routing table.
1254:
1255: Specify the interface index in index. This value can be retrieved by
1256: so_ifnametoindex() and so on.
1257:
1258: Specify a value other than 0 in direct when connecting to the
1259: destination address directly, or 0 otherwise. The routing information
1260: flag is set to RTF_GATEWAY when 0 is specified in direct, or
1261: RTF_HOST instead of RTF_GATEWAY when a value other than 0 is
1262: specified.
1263:
1264: To specify the default gateway, specify INADDR_ANY in dest and mask.
1265:
1266:
1267: (6) Deleting a route
1268:
1269: #include "network_sample/route.h"
1270: void route_delete(in_addr_t dest, in_addr_t mask, int index,
1271: int direct);
1272:
1273: Parameter
1274:
1275: in_addr_t dest destination address
1276: in_addr_t gate gateway address
1277: in_addr_t mask network mask
1278:
1279: Description
1280:
1281: This deletes the routing information specified by the destination
1282: address dest, the gateway address gate, and the network mask
1283: mask from the routing table.
1284:
1285: To specify the default gateway, specify INADDR_ANY in dest and mask.
1286:
1287: (7) Listing routes
1288:
1289: #include "network_sample/route.h"
1290: void dump_rtlist(void);
1291:
1292: Description
1293:
1294: This displays the entries in the routing table in the standard output.
1295:
1296: (8) Adding an entry to host table
1297:
1298: #include "network_sample/util.h"
1299: void add_hosttable(const char* hostname, in_addr_t addr);
1300:
1301: Parameter
1302:
1303: const char* hostname name of host
1304: in_addr_t addr address
1305:
1306: Description
1307:
1308: This adds an entry that assigns the address addr to the host name
1309: hostname to the host table.
1310:
1311: (9) Setting address using DHCP
1312:
1313: #include "network_sample/dhclient.h"
1314: int dhclient(const char* ifname);
1315:
1316: Parameter
1317:
1318: const char* ifname interface name
1319:
1320: Description
1321:
1322: This tries to obtain the following setting for the interface specified
1323: by ifname using DHCP.
1324:
1325: - network interface address setting
1326: - default gateway setting
1327: - DNS related setting
1328:
1329: 5.12 Implementation Restrictions
1330:
1331: There is the following restriction:
1332:
1333: - Although the old source code, from which the current code is derived,
1334: provides the function of assigning a random value to the
1335: identification field of the IP header, this implementation does not
1336: support this function to reduce memory usage.
1337:
1338:
1339: ------------------------------------------------------------------------------
1340: 6. Calendar Function
1341: ------------------------------------------------------------------------------
1342:
1343: There are the following restrictions:
1344:
1345: - In API calls that have arguments or the return code of time_t type, an
1346: error occurs when a time value that is out of the range expressed by
1347: SYSTIM or SYSTIM_U is specified.
1348: Specifically, an error occurs when a time earlier than 1985/1/1 00:00:00
1349: is specified.
1350:
1351: - When %U or %W is specified in dt_strptime(), the value is ignored in
1352: the string and not stored in tm.
1353:
1354:
1355: ------------------------------------------------------------------------------
1356: 7. Program Load Function
1357: ------------------------------------------------------------------------------
1358:
1359: 7.1 Program Module Creation
1360:
1361: This implementation supports the ELF object as a program module format.
1362:
1363: A program module can be created by using build rules included in
1364: ${BD}/module/etc/makerules. See samples of the system and regular
1365: program modules, which are found in the following directories.
1366:
1367: ${BD}/module/test-sys
1368: System program module sample
1369:
1370: ${BD}/module/test-usr
1371: Regular program module sample
1372:
1373: 7.2 Restrictions
1374:
1375: There is the following restriction:
1376:
1377: - The initialization and termination processes of a regular program
1378: module are always performed at the system level regardless of the
1379: destination space specification when pm_load() is executed.
1380:
1381:
1382: ------------------------------------------------------------------------------
1383: 8. Standard C Compatible Library
1384: ------------------------------------------------------------------------------
1385:
1386: Standard C compatible library is implemented in portions of
1387: ${BD}/lib/libtk, and in ${BD}/lib/libc.
1388:
1389: In this implementation, static data is placed in user level
1390: memory space (.data_usr and .bss_usr).
1391:
1392:
1393: ------------------------------------------------------------------------------
1394: ------------------------------------------------------------------------------