Special Feature 1

Releasing T-Kernel Source Code

Yuichi Toyoyama

YRP Ubiquitous Networking Laboratory

The T-Kernel source code has at last been released to the general public. If those who desire it go through the prescribed procedures, they can get their hands on T-Kernel's source code.

T-Kernel is a new generation real-time operating system that was born from T-Engine. Because we have already given an introduction in this magazine concerning the project to make T-Kernel open, I would like to give an explanation here on how to actually obtain the T-Kernel that has been opened, and up to how to make it run.

The Method of Obtaining T-Kernel

You can apply to utilize the T-Kernel source code and obtain it from the T-Engine Forum's Web page by means of the procedure below [Fig. 1].

Figure 1. T-Kernel release Web page

(1)	Select "Subscription to T-Kernel" from from the T-Engine Forum's Web page (http://www.t-engine.org/). There is a link in the menu on the left side of the page.
(2)	Move to the "Subscription to T-Kernel" page. Here, after reading well the explanation concerning the use of T-Kernel, press the "Subscription" button at the bottom of the page.
(3)	Move to the T-Kernel License page. As the entire text of T-License [License Agreement for Source Code of T-Kernel] is displayed here, please read it well. In applying for the T-Kernel source code, it is necessary to agree with and consent to this license. Those who consent to it, please press the "Agreement" button at the bottom of the page.
(4)	Move to the page where you select who will be using T-Kernel, an individual or a corporation. Those who will be applying as individuals, please press the "Individual Contract" button. Those who will be applying as corporations, such as companies, please press the "Corporate Contract." Here, you move onto an explanation concerning an individual contract, but there is not a great difference with a corporate contract.
(5)	Move to the Individual Contract input page. Here, input the required items. Mandatory input items are "Name," "Address," and "E-mail address." Although it's not mandatory, if there is no problem, let's input a profile and the purpose of use, too. Concerning the handling of the input data, as there is a link to the page on the handling of personal information (privacy policy) from the previous page, it is mentioned there.
(6)	Move to the Subscription Confirmation page If there are no errors in the contents that are displayed, please press the "Submit" bottom of the page. By this, the application for a subscription is completed.

When the above application is completed, user registration will be carried out at the T-Engine Forum, and a user ID and password will be returned via e-mail. This is done in a way that there are even instances where, depending on the case, it takes as long as a week until you are registered, but normally it appears that registration takes place immediately. I think there are also some individuals who feel these application procedures are a little formal or to whom they seem strict, but because we have considered the license on the premise that T-Kernel will be used even in actual products such as embedded devices, it has ended up in this form. Because we have explained the T-Kernel license in a separate article, I will not write about it in detail here, but please pay attention to the fact that it is an original license that is different from the GPL. One of the big differences is that redistribution of T-Kernel source code is something that is forbidden. The T-Engine project, which includes T-Kernel, has as one of its objectives the creation of a distribution platform for middleware. In order to realize this, we make the operating system into a single version at the source code level, and, in principle, we do not allow the distribution of changed versions. Furthermore, what is forbidden is the redistribution of source code; remodeling T-Kernel and using it or embedding a changed version in a product is permitted. Conversely, even if you use T-Kernel by embedding it in a product, there is no restriction that says you have to make public the source code. Things of this nature have made it a license suitable to use in such things as embedded devices.

When T-Kernel user registration is finished and a user ID and password have been obtained, it is finally time to download the T-Kernel source code. Because the download page URL should have been sent together with the user ID, let's downloaded it without delay. At the point in time of this writing, the files that have been released are as in Table 1.

Table 1's tkernel.1.00.00.tar.gz is the T-Kernel source code itself. The explanation of the source code is tkernel.txt, and the organization of the source files, the method for constructing the kernel, an explanation of the kernel startup process, etc., are mentioned in it. It would be good to give it a reading when you are on the verge of reading through the source code. The other files are implementation specifications for T-Kernel. The T-Kernel that has been released at present is compatible with the five types of Standard T-Engine and two types of µT-Engine listed in Table 2, and there is an implementation specification for each T-Engine. In the implementation specifications, the hardware-dependent specification and how T-Kernel has actually been implemented are explained. I think these will be useful in such cases as when you create a program that's close to the system on top of T-Kernel, or when you want to know the construction of T-Kernel itself.

The Building and Execution of T-Kernel

If you have the T-Kernel source code in your possession, let's build the kernel and try to actually run it. To run as is the T-Kernel that has been released, any one of the Standard T-Engine or µT-Engine development kits listed in Table 2 is necessary. The GNU development environment that runs on top of Linux is included in the development kit together with the T-Engine hardware. A makefile and script file premised on building the T-Kernel source code in this development kit environment are attached. In the concrete example hereafter, I shall explain the build procedure for the Standard T-Engine/SH7727 kernel using bash in the Shell. With other T-Engines also it's basically the same procedure outside a portion of the path names changing. Also, in a shell other than bash, it is necessary to replace a portion of the commands.

First, as a preparation, we will install in the PC the GNU development environment of the T-Engine development kit. To check whether it's properly installed or not, please compile and try to run on T-Engine several of the attached sample programs in the development kit (as for the methods for installing the development environment and running the sample programs, please look at the development kit's manual).

Once the running of the development environment has been confirmed, expand the T-Kernel source code file 'tkernel.1.00.00.tar.gz' in some appropriate place. Here, let's try expanding it below the home directory. We execute the following commands on top of the Shell.

% cd

% tar xvfz tkernel.1.00.00.tar.gz

I think that a directory called tkernel_source has been created. Below this directory, there are the five directories shown in Table 3. In the kernel directory, the source code of the T-Kernel main part is entered. The lib directory is source code of the library that T-Kernel provides. Inside this, even an interface library of system calls is included. In the include directory, C language header files have been entered. These files are used from inside files inside kernel and lib and user programs. In the config directory, T-Engine system settings files, such as rominfo, SYSCONF, DEVCONF, have been entered. The details of these settings files are mentioned in the implementation specification of each T-Engine. In the etc directory, there is no source code. Files we use in the building of T-Kernel, such as make rules and script files, are entered here.

Once the source code has expanded, we set the path name of the directory into which we expanded the source code in the environment variable BD. As for this environment variable BD, we have shown the base directory of the development environment.

% export BD=~/tkernel_source

First, we will create each library file. Because the T-Kernel main part also uses a portion of this library, it is necessary to without fail create from the library. We move the library to the directory of the target system, and by means of performing make, it is possible to create it. The directory of the target system is below the build directory below the lib directory. In the case of Standard T-Engine/SH7727, we execute the commands in the following manner (with other T-Engines, the name of the target system directory differs).

% cd ~/tkernel_source/lib/build/std_sh7727

% make

Continuing on, we build the T-Kernel main part. We move to the target system directory of the kernel, and we create it by performing make. The target system directory is under the path of kernel/sysmain/build. In the case of Standard T-Engine/SH7727, we execute the commands in the following manner (in the same manner as the library, with other T-Engines, the the name of the target system directory differs).

% cd ~/t-kernel_source/kernel/sysmain/build/std_sh7727

% make

When you have succeeded in building the kernel, a file called kernel-rom.mot will be created on top of the current directory. This is the T-Kernel object file.

Finally, we will create a RomInfo object. We move to the target system directory under the config/build path. In the case of Standard T-Engine/SH7727, we execute command in the following manner (I am repeating, but with other T-Engines the target system directory name is different).

% cd ~/tkernel_source/config/build/std_sh7727

% make

A RomInfo object file with the name rominfo.mot will be created under the current directory. With the above, the building of the kernel is finished.

At last, let's try running on T-Engine an object of the T-Engine we built. For this, first we write into the Flash ROM of T-Engine the kernel-rom.mot object file of the T-Kernel we built. Writing into the Flash ROM can normally be carried out by means of the FlashLoad (FLLO) command of T-Monitor. Because there are cases where the method of writing into the Flash ROM is different both on the type and version of T-Engine, please read the manual attached to T-Engine. Please be careful when writing into the Flash ROM, because the development kit software that was in the Flash ROM up to that point will end up being overwritten. To restore the original Flash ROM software, restore by writing the ROM image object file that is attached to the development kit. Because this method also is mentioned in the manual attached to each T-Engine, please read it there.

When the writing in of kernel-rom.mot is finished, continue on and write into the Flash ROM with the same procedure the rominfo.mot object file of RomInfo. Because information necessary in starting up the system is set in this RomInfo, when you have modified the system, it is necessary to modify this along with it.

After the writing into the Flash ROM of the two files is finished, when you turn on the power of T-Engine again, the newly written in T-Kernel will start up. At this time, when you connect your personal computer to the T-Engine's serial interface and run the terminal software, an output from T-Kernel will be displayed. The communication settings are the same as the T-Monitor communication settings.

If the built T-Kernel starts up normally, the following message should be displayed.

T-Kernel Version 1.00.00

Push any key to shutdown the T-Kernel.

When we send the input of any key from the personal computer's terminal software here, T-Kernel will terminate. It depends on the T-Engine hardware, but if it's a T-Engine that has a function that cuts off the power from T-Monitor, the power also can be cut off.

With the above, I have finished everything from the building of T-Kernel to starting it up.

Embedding of a User Program

Well, did T-Kernel successfully start up for you? It started up, but outside of the startup message appearing nothing happens? This is as it is so; since the released source code is only the T-Kernel main part, an application program that runs on top of it does not exist. It's really a state in which only T-Kernel is running. To make T-Engine do something, you must run a user program for a purpose on top of T-Kernel.

First, I will briefly explain the flow from the startup of T-Kernel up to a user program being executed.

When the power supply is thrown into T-Engine, T-Monitor starts up first. T-Monitor calls up the T-Kernel startup program after it has carried out the initialization of hardware necessary at startup time. Because the T-Kernel built on this occasion has immediately started up by placing it on a Flash ROM, a special startup program is not necessary. Therefore, the start address of T-Kernel is directly called up from T-Monitor. Furthermore, by creating a startup program, it is also possible to do something starting up T-Kernel from a disk (the detailed sequence of the system start up processes is mentioned in the source code explanatory notes that have been released together with T-Kernel, so please take a look at them).

Well then, when T-Kernel is started from T-Monitor, T-Kernel first carries out internal initialization processing. When this initialization processing finishes, the kernel creates and executes a special task called the initial task (init_task). An initial task carries out various types of initialization processes executed in task context that are the final processes when T-Kernel is started up for the first time. When these processes are finished, the initialization processing of T-Kernel is completely finished. The initial task at last calls up the user program.

The user program that is called up from the initial task is the usermain initial task main process. This usermain program carries out the start processes of the user program in its entirety. Please look at the following path file of the T-Kernel source code.

/tkernel_source/kernel/usermain/usermain.c

In this file, one function that we call usermain() is defined. This is the usermain program. In List 1, I show the list of this function. As can be seen, the execution lines are a very short program of just three lines. The function called tm_putstring() of the first line is a service function of T-Monitor, and it performs character string output to the cursor. The characters "Push any key to shutdown the T-Kernel" that are displayed in the personal computer's terminal software when you have started up T-Kernel were output here. The function called tm_getchar() of the second line is also a service function of T-Monitor, and it performs the input of one character from the cursor. When -1 is specified in the argument, T-Monitor continuously waits up to where input is. When there is an input, the third line executes, and the usermain() function terminates. On the return value of 0, usermain() normally terminates, and T-Monitor displays the terminating of the system.

EXPORT  INT usermain( void )
{
    tm_putstring("Push any key to shutdown the T-Kernel.\n");
    tm_getchar(-1);


    return 0;
}

I think you understand that the above processes are the very operations at the time that you start up the previously mentioned T-Kernel. Because there is no user program in the T-Kernel that has been released, a brief program of this type has been described for the time being. You can execute a user program that you want to run by rewriting the contents of this usermain() function.

In embedding and running a user program in T-Kernel, the simplest method is writing out the user program itself inside this usermain() function. As a test, change the character string of the argument in the tm_putstring() in List 1 or add on another tm_putstring() function, and then build T-Kernel again and try executing it. You can confirm that the modifications are reflected.

Actually, not describing the user program inside the usermain() function, but rather creating a task that configures a user program and starting up from the usermain() function is the typical method of use. Because a user program of a certain extent in scale normally is comprised of multiple tasks, creating these tasks themselves and the other kernel objects these tasks use becomes the role of the usermain() function. At such time, when the usermain() function terminates, T-Kernel termination processing begins, so please be careful about the entire system completely shutting down. A scheme that does not allow the shutting down of the usermain() function until the termination of the system is necessary.

By the way, when it comes to the method explained so far, I think there are some individuals who consider this method troublesome, as it requires rebuilding from the entire system including T-Kernel. In efficiently carrying out the development of user programs, various types of tools that support development are necessary. The system explained on this occasion is only T-Kernel, and because it does not include these development tools, it has ended up in this manner. Normally, directly embedding a user program in T-Kernel is something done at the final stage, after development work, such as the debugging of that user program, is finished. In the original system of the development kits, in addition to T-Kernel, tools such as an IMS and CLI are embedded, and thus a means to easily load user programs is provided. Also, in debugging programs, a debugger called gdb can be used. In developing user programs, it would probably be better to use one of the development kits.

There are several points you should be cautious about in running programs developed on top of the development kits on top of the T-Kernel that has been released.

Figure 2. System configuration outline

In the development kit systems, as I show in Fig. 2 (a), a large number of programs are included in addition to T-Kernel. Conversely, the system constructed on this occasion, as I show in Fig. 2 (b), is a simple thing (for T-Monitor, we are using as is the one in ROM). First, in controlling various types of hardware on top of T-Engine, device drivers matched to the respective hardware are necessary. Because a device driver is hardware dependent, in other words, because it is something we need to create for every piece of hardware, it is not included in the main part of T-Kernel. T-Kernel Extension, in a word, is a software group for the purpose of extending T-Kernel's functions and creating more highly functional systems. In the development kits, a powerful Extension based on the BTRON specification called PMC T-Kernel Extension has been included. By means of this Extension, user programs can use functions such as file system and process management, and virtual memory management. In a T-Kernel only system, these functions naturally cannot be used.

Also, the T-Kernel included in the development kits at the present stage is a previous version of T-Kernel. Accordingly, it seems that there might also be parts that are slightly different. Concerning these points, it appears that they will be unified little by little.

In Conclusion

The T-Kernel source code that has been released is not a simple reference or at the test level, but rather it is a real-time operating system program premised on actual use in manufactured products. Also, it is highly portable among CPUs, having become source that has already been made compatible with seven types of CPUs. That the source code of this kind of genuine, real-time operating system has been released free of charge is something that I think is very meaningful.

Even at the level of the individual, this would probably make a fitting teaching material for people who want to study a real-time operating system. Also, it is probably something suitable even in cases where you would like to port a real-time operating system to hardware you have created yourself. If T-Kernel can be skillfully ported, software for T-Engine, which it seems will appear one after the other in the future, can also be utilized.

Those who have read this article and have developed an interest in T-Kernel, by all means, please try challenging it.

The above article on T-Engine appeared on pages 15-19 in Vol. 86 of TRONWARE . It was translated and loaded onto this Web page with the permission of Personal Media Corporation.

Copyright © 2004 Personal Media Corporation

Copyright © 2004 Sakamura Laboratory, University Museum, University of Tokyo