TE@Onghu RSS Feed

SDI Device Driver Guide - Part 2

Tue, 01 Apr 2008 04:20:00 GMT

SDI Device Driver Guide – Part 2

Written by: Mukul Sharma and Fauzi Abbas, Centre for High Performance Embedded Systems, NTU Singapore
Edited by: Mohit Sindhwani (TE@Onghu)

In the first part of this article, we explained the process for writing a device driver. In this concluding part, we look at the process for using the device driver – building, running and accessing the driver from an application.

The main thing to remember is that a device driver is not very different from a regular application, and many of the rules regarding applications apply also to device drivers.

Compiling the Device Driver

The Sample Device Driver can be build and compiled similarly as any other T-Kernel Application. The procedure described in the article, “Building and Running a Sample Program”, is applicable to the device driver also. It compiles like a regular application.

However, there is one big difference – the makefile.

The Makerules files for applications and device drivers are quite different and the Makefile for the driver should point to the correct Makerules file which is at /te/etc/Makerules. It is a good idea to build the driver from a project folder inside the /te/driver directory, so that the Makefile points to the correct Makerules file.

Running the Device Driver

If you follow the procedure in the above article, you can download the device driver executable to the T-Engine using the serial console. Assuming that the executable is called sample_driver run the following command to launch the driver after it has been downloaded.


lodspg     sample_driver

If you want to automatically launch the device driver when the T-Engine is started, you can follow the steps in this HOWTO article.

Sample Device Driver – Include File

As mentioned in the previous part, the device driver can define certain constants that may be needed by the application that uses the device driver. This can be done by defining the constants in a header file (e.g. sample_drvr.h) and this header file can be copied to an include folder of the T-Engine environment (somewhere under /te/include).

Sample Application using the Device Driver

The following source code shows a simple application that uses the device driver.

#include <stdio.h>
#include <tk/tkernel.h>
#include <string.h>
#include <sample_drvr.h>

void main(void)
{
    UB  devnm[8]; /* device name */
    ID  dds;      /* device descriptor */
    INT asiz;     /* read/write size */
    ER  ercd;     /* error code */
    INT dvc;

    strcpy( devnm, "DRVSAMP" );  /* our device name */
    
    /* The next line will result in our openfn function being called */
    dds = tk_opn_dev( devnm, TD_UPDATE ); /* open device in update mode */

    if (dds < E_OK)
    {
        printf (" Failed to open device. \n");
        exit -1;
    }

    printf(" Device Descripter - %x \n", dds);

    /* read the device specifications */
    ercd = tk_srea_dev( dds, DN_DVCSPEC, &dvc, sizeof(INT), &asiz );
    if (ercd < E_OK) goto ext;

    /* write device specification */
    ercd = tk_swri_dev( dds, DN_DVCSPEC, &dvc, sizeof(INT), &asiz );
    if (ercd < E_OK) goto ext;

    /* Use the device for other things */

ext:
    tk_cls_dev( dds, 0 );  /* Close device - will call our closefn */
    printf(" Exiting Demo ! \n");

    return;
}

Building and Running the Application

Build the application like a regular T-Kernel application, download it to the T-Engine and if it is called driver_demo, launch it using:


lodspg     driver_demo

You should see something like the screen below when it runs.

HOWTO: Assembly Language Interrupt Service Routines

Mon, 31 Mar 2008 07:39:00 GMT

HOWTO: Assembly Language Interrupt Handlers

Written by: Mohit Sindhwani, Viometrix

In a previous article, I had written about defining your own high-level interrupt handler from a T-Kernel application/ middleware. In this brief ‘how-to’ article, we look at some of the concepts in creating a low-level interrupt handler for the T-Kernel.

Background

In many embedded systems, interrupts are used to interface with the real world. When an event happens, the peripheral responsible for dealing with it raises an interrupt to the CPU. The CPU then stops doing what it’s doing, saves some of its essential context and attends to the interrupt. The routine that deals with the interrupt is called the interrupt handler (or interrupt service routine) and is supposed to quickly do interrupt-related processing. After this is completed, the CPU restores the context of the previously running program and execution continues as though nothing happened. The specifics of how to install and use interrupt handlers is usually dependent on the CPU and/ or the RTOS.

The T-Kernel allows developers to create two types of interrupt handlers: handlers written in assembly or handlers written in a high-level language. This article focuses primarily on assembly language handlers. Details for high-level language handlers are available in the T-Kernel specification and in our other article.

Essential Reading: As before, the main reference for this is actually Section 4.8 – Interrupt Management Function of the T-Kernel specification. Refer to that section for more details.

Coding the Interrupt Handler

Similar to high-level interrupt handlers, a low-level interrupt handler must do at least the same sets of things:

Read/ write data from/ to the peripheral: This is the main task that needs to be done to respond to the interrupt.
Remove the interrupt request: In devices such as the UART, a read interrupt request is automatically removed when you read from the device. However, in some devices such as timers, it is necessary to write to a special flag that clears the interrupt request.
Inform the application that the interrupt occurred: In many cases, you will need to communicate to the running application that the event has happened. Typically, this is done by issuing a system call. To see the system calls that are possible from the ISR, check Section 3.2.2 of the T-Kernel specification.
Return from the exception: Finally, you need to return from the service handler.

The main points of difference between an assembly interrupt handler and high-level interrupt handler are:

Entry into the Handler
Return from the exception

Entry into the Handler

In the case of a high-level ISR, the T-Kernel carries out a number of processes before the high-level ISR function is called. Most importantly, this involves processes related to saving context so that the ISR can do its processing without causing problems to the running task.

A low-level interrupt handler is started either by the CPU directly in response to the interrupt or by a support function in the T-Monitor. Depending on the CPU architecture, some CPU state may have been saved before the interrupt is invoked. The remaining state has to be saved by your low-level ISR when it starts. The details of this are highly dependent on the CPU architecture and the specific implementation of the T-Monitor for that architecture. You will need to refer to the Implementation Specification of the T-Monitor for the T-Engine and the Architecture Manual for the CPU to get a better understanding of this aspect.

Return from the Exception

A high-level ISR can issue a return from the exception/ interrupt simply by executing a C-style return from function. In the case of an assembly ISR, the ISR is responsible for more things – it must properly return from the exception and also restore the context. Further, if interrupts are enabled when a low-level ISR is run, there is a chance that dispatching may be required when returning from a low-level ISR. Therefore, returning from a low-level ISR requires a special process.

The T-Kernel requires every port to provide a system call to support a return from interrupt. This system call is called tk_ret_int and must be called at the end of a low-level interrupt handler. It ensures that the necessary processing for possible dispatching is carried out when it returns from the ISR.

Again, these processes are highly dependent on the CPU and the T-Monitor architecture. The Implementation Specification for the port should outline the specific process for creating a low-level ISR.

Template for Low-level ISRs

The main flow of a low-level ISR is as follows:

Save the context of the CPU
Read/ write data from/ to the peripheral
Inform the application that the interrupt has occurred
Return from the exception by calling tk_ret_int

Specifically in this case, the details are system dependent – so please refer to the following sources:

CPU Port Implementation Specification
T-Kernel Specification Section 4.8
CPU Architecture Manual

Examples of Low-level ISRs

The main example of a low-level ISR is the timer service routine that runs at every system tick. The source code for this function can be found in each of the CPU ports of the T-Kernel. If you have access to the source (or if you download it from the T-Engine Forum site), you can find the relevant function and use that as a basic template of a low-level ISR for your CPU.

Registering/ defining a Low Level ISR

This step is similar to that for a high-level ISR. Once you have written the function for the interrupt handler, you need to register it with the T-Kernel so that it is called when the interrupt happens the next time. You register an interrupt handler by calling tk_def_int.

The C language interface for tk_def_int is as shown below:

ER ercd = tk_def_int (UINT dintno, T_DINT *pk_dint ) ;

The first parameter dintno is the interrupt number. Usually, this is the interrupt vector number – the specific meaning of this number is implementation dependent and can be found in the Implementation Specifications that came with your T-Kernel port.

Other than this, all you need to do is fill out the details of the T_DINT structure to include the following information:

The type of handler: high level or assembly (specified using TA_HLANG or TA_ASM respectively) – we specify TA_ASM in this case
The address of the handler function

The TA_ASM specifies that the interrupt handler being registered is an assembly language interrupt handler. The code for defining the interrupt handler is shown below. You need to call tk_def_int and pass it the interrupt number and the address of the T_DINT structure.


{
    T_DINT int_pkt;
    ER ercd;
    int_pkt.intatr = TA_ASM;
    int_pkt.inthdr = tk_my_isr;
    ercd = tk_def_int (SERIAL_RX_ISR, &int_pkt);
}

That’s all there is to it! Once this is done, the T-Kernel will now call your specific function when the interrupt occurs.

If you want to remove the definition that you have made, you need to call tk_def_int and pass it the interrupt number (usually the interrupt vector number) and NULL as the address of the T_DINT structure.

HOWTO: Load an Application at System Startup

Sun, 30 Mar 2008 08:59:00 GMT

HOWTO: Load an Application at System Startup

Written by: Mukul Sharma, Centre for High Performance Embedded Systems , NTU Singapore
Edited by: Mohit Sindhwani, TE@Onghu

In a system, it is a common need to load certain types of applications or system modules when the system starts. The T-Engine allows applications to be loaded using the Command Line Interface (CLI). In addition, it is possible to request the T-Engine to load certain drivers, middleware or applications when the system starts. In this how-to article, we show the procedure for getting the system to automatically load your application, driver or middleware when it starts.

Step 1 – Finding your friends (the files)

The procedure is simple. When the Initial Monitor System (IMS) starts up, it looks for a file and runs the script found in it. This file is called STARTUP.CMD and is usually located in ”/” (root) directory and can also be found in ”/SYS” when booting from a Flash Card. The file is a plain text file that contains a list of commands to be run during startup.

The format of this file is shown below:


*
*       @(#)STARTUP.CMD (T-Engine/SH7727)
*
*       システム起動用 IMS 初期コマンドスクリプト
*       Copyright (C) 2002-2004 by Personal Media Corporation
*
$chgsys uda rda
lodspg  kbpd            !30
lodspg  lowkbpd         !28
lodspg  rsdrv           !26
lodspg  screen          !35
lodspg  unixemu
$cli    STARTUP.CLI     !224
exit    1

Step 2 – Adding your Entry

The lines that we need to observe are the lines that look like this:


lodspg  lowkbpd         !28

This line basically tells the system to load the system program called ‘lowkbpd’ with a task priority of ‘28’.

Similarly, you need to edit STARTUP.CMD to add an entry for your application, middleware or driver. We can add any number of commands that we would like to run. The system will run all of these in the sequence in which they appear in the file. For example, you could get the system to load your application, program or middleware at piority 76 by adding this to the file:


lodspg  my_driver_or_app_or_mw         !76

It’s important to remember that this is the method to load T-Kernel-based programs (not programs that are based on TK/SE), i.e., task-based programs (not process-based programs).

Also, note the line called $cli STARTUP.CLI !224 – it starts the command line interface (CLI) as a process and runs commands from the file STARTUP.CLI. If we are starting device drivers and middleware, typically, we would add our commands before this line.

That’s all there is to it – the next time you restart the T-Engine, it will run your application also.

More Information: For further information, refer to the T-Engine Development Kit Manual that comes with your T-Engine. It explains the commands that can be used in the STARTUP.CMD and the STARTUP.CLI files.

SDI Device Driver Guide - Part 1

Sat, 29 Mar 2008 17:04:00 GMT

SDI Device Driver Guide – Part 1

Written by: Mukul Sharma and Fauzi Abbas, Centre for High Performance Embedded Systems, NTU Singapore
Edited by: Mohit Sindhwani (TE@Onghu)

The T-Kernel supports a number of models for device drivers. In order to make it easy for developers to write device drivers, the T-Engine Forum has released a document called T-Engine Device Driver Interface Library Specification and associated source code. One of the device driver models mentioned in the specification is called the Simple Device Driver Interface or SDI. In this article, we present the steps that are needed to create an SDI device driver for the T-Kernel.

For this example, we create a dummy device and a device driver to access it. Although this is a simplistic example, it demonstrates the basic workings of a simple driver and also points out the main steps involved in creating a device driver.

Some parts of this article are based on the presentation about device drivers available from TEADEC and includes other information based on our experience of writing a device driver.

Equipment and Tools

Our developing environment is set up using the following:

Red Hat Linux 9.0 or Ubuntu Linux 5.04 (Intel x86 versions) or Cygwin.
T-Engine Development Kit Release 1.11E or later.
T-Engine/SH7727 with 128MB Compact Flash

In this guide, references are made to the device driver source codes available on the T-Engine Development Kit Release while working on the current sample device drivers. These device drivers include the LCD, Console, Touch Panel and several other device drivers and they strictly follow the standard specifications provided by T-Engine Forum. These sample drivers provide a good way to learn how device drivers are written.

Background

The picture below shows the device driver stack that is used for creating a device driver.

T-Kernel Device Management Function (from T-Kernel Specification – TEF020–S001–01.00.00/en)

As can be seen, the device driver itself works with 3 main parts:

The device driver must interface with the physical hardware that it controls
It must work with the kernel so that the kernel knows when/ how to call it
It must be accessible by applications/ middleware that require to use the device

Since Item #3 in the above list is highly hardware dependent, for the sake of this example, we try to create a simple device that does not actually work with physical hardware. Instead, it simply outputs messages to indicate when the various functions are called. When creating a real device driver, those lines should be replaced with the correct processing for controlling/ accessing/ using the device. The main focus of this article is how to use SDI to manage Items #1 and #2.

Typically, a simple device driver must provide at least the following functions:

Open Device and Close Device
Read from and Write to the device
Event Function (used for events like suspend, resume, etc.)

Essential Reading: The following references are essential reading for this article:

T-Kernel Specification: Section 5.3 – Device Management Functions: This explains the various functions that we use.
T-Engine Device Driver Interface Library Specification: This explains SDI and related data structures, etc.

Creating the Device Driver

The main steps in creating a device driver are as follows:

Create functions to open and close the device (if required)
Create functions to read from and write to the device (if required)
Create the event function to receive events (if required)
Create a structure to describe your device
Register your device with the T-Kernel

Step 1 – Functions to open and close the Device

These functions are called when an application tries to open or close the device. In the accompanying source code, refer to sample_device_driver/src/main.c, line 18 – 35.

The open function usually initializes the device while the close function handles the necessary cleanup before ‘free’ing the device. The open function is called during the tk_opn_dev() call and close function is called during the tk_cls_dev() call.

If a device is opened multiple times, open function is called the first time it is opened and close function the last time it is closed. If TDA_OPENREQ is designated as driver attribute, then open/close function will be called for all open/close operations even in case of multiple openings.

In the code below, the open function and close functions are shown for our sample device.


LOCAL ER openfn  ( ID devid, UINT omode, VP exinf)
{
    /* start device use */
    // Content is Device Dependent
    printf(" A call has been made for the Device Open Function.\n");
    return E_OK;
}

LOCAL ER closefn  ( ID devid, UINT option, VP exinf)
{
    /* terminate device use */
    // Content is Device Dependent
    printf(" A call has been made for the Device Close Function.\n");
    return E_OK;
}

ID devid    : Device ID of the device to open
UINT omode  : Open mode (same as tk opn dev)
VP exinf    : Extended information set at device registration
Return code : Error

For more information, refer to the following:

T-Kernel Specifications Chapter 5.3.4 – Device Driver Interface.
T-Kernel Specifications Chapter 5.3.3 – Device Registration.
T-Kernel Specifications Chapter 5.3.2 – Application Interface.

Step 2 – Functions to read and write

The next step is to declare the Read/Write Functions for the Device. These functions are required to process read or write requests to the device. Read and Write Functions follow a standard definition to serve the various Read/Write Requests done from the device. The functions will typically use a switch case statement format to serve different read/write requests.

In the accompanying source code, refer to sample_device_driver/src/main.c, line 40 – 85 for our read/ write functions. The read function is shown below and the write function is created in a similar fashion.


LOCAL    INT    readfn(ID devid, INT start, INT size, VP buf, SDI sdi)
{
    printf(" A call has been made for the Device Read Function.\n");

    switch (start)
    {
        case DN_DVCSPEC:    /* Developer defined Device Specifications Read Call */
                            // Content is Device Dependent                        
            printf(" This function gets the Device Specifications and returns them back to the application.\n");
            break;

        case DN_DVCREAD:    /* Developer defined Device Read Call */
                            // Content is Device Dependent
            printf(" This function gets the Device Specific Data and returns it back to the application.\n");
            break;

        default:
        printf(" This is default action for the read function call.\n");
            break;
    }
    return E_OK;
}

In general, start refers to the starting address from which data is to be read/ written. According to the specification, zero or positive values are used to read/ write device specific data and negative values are used to read/ write attribute information about the device. Attribute information that can be read/ written is device-dependent and for this, developers should define their own constants referring to the various attributes. This can be done by defining the constants in a header file (e.g. sample_drvr.h) and this header file should be copied to the include folder of the T-Engine environment (/te/include).

Read/ Write Functions are called during tk_rea_dev()/tk_srea_dev() or tk_wri_dev()/tk_swri_dev() calls.

Note that the order of arguments received by the Read/ Write Functions differs from the order in which these arguments are passed from application.

For more information, refer to the following:

T-Kernel Specifications Chapter 5.3.4 – Device Driver Interface.
T-Kernel Specifications Chapter 5.3.2 – Application Interface.

Step 3 – Event Function

A device driver can receive events from the system and must carry out processing related to these events. For physical devices, the driver may be issued requests to suspend or resume the devices. In the accompanying source code, refer to sample_device_driver/src/main.c, line 90 – 124 for our event function. Event requests are called when processing the tk_evt_dev() call.


LOCAL    INT    eventfn  (INT evttyp, VP evtinf, SDI sdi)
{
    INT    er;
    printf(" A call has been made for the Device Event Function.\n");
    switch (evttyp)
    {
        case    TDV_SUSPEND:    //  Predefined Suspend Call 
            if (suspended == FALSE)
            {
            // Developer defined function to set device in suspended mode
            printf(" This function will set the device in suspended state.\n");
            suspended = TRUE;
            }
            er = E_OK;
            break;

        case    TDV_RESUME:        //  Predefined Resume Call 
            if (suspended == TRUE)
            {
            // Developer defined function to resume the device from suspended mode
            printf(" This function will resume the device from the suspended state.\n");
            suspended = FALSE;
            }
            er = E_OK;
            break;
        default:
            er = E_ILUSE;
            break;
    }

    return er;
}

The constants used here (TDV_SUSPEND and TDV_RESUME) are defined by the Device Manager in the “tk/devmgr.h” header file. For more information, refer to:

T-Kernel Specifications Chapter 5.3.4 – Device Driver Interface.
T-Kernel Specifications Chapter 5.3.2 – Application Interface.
T-Kernel Specifications Chapter 5.3.6 – Device Event Notification

Step 4 – Driver Registration Structure

Once we have decided the functions that the device driver will support, it is necessary to package the functions and inform the kernel about the functions it call when dealing with the device. In registering the device, the first step is to create and populate the Device Registration Structure. This structure tells the T-Kernel what the device is called and also specifies the capabilities and attributes of the device. The structure shown below is based on SDI. In the attached source code, refer to sample_device_driver/src/main.c, line 134 – 146 to see where the device is defined.

In this structure, it is necessary to specify the functions that the device driver supports. An SDI device driver may support any of the following functions:

Open
Close
Read
Write
Event

Where the function is supported, the corresponding entry in the structure should store the address of the function in the driver. Where the function is not supported, the entry should be stored as NULL. Note that we used the names openfn, closefn, etc. for the functions in our device driver and are assigning these in the structure. However, these functions may be named to your choosing – just make sure that the correct names are assigned in the device structure below.


SDefDev    ddev = {
    NULL,       /* exinf: extended information */
    "DRVSAMP",    /* devnm: physical device name */
                /* devnm should be max. 8 char in the format:
                   "format type + unit + subunit" */
    0,            /* drvatr driver attribute */
    TDK_UNDEF,    /* devatr device attribute */    //Undefined Device Type
    0,        /* nsub: number of subunits */
    1,        /* blksz : block size for specific data */
    openfn,    /* open function*/
    closefn,    /* close function*/
    readfn,    /* read function*/
    writefn,    /* write function*/
    eventfn,    /* event function*/
};

For more details about the device registration structure, refer to:

T-Kernel Specification Chapter 5.3.3 – Device Registration
T-Engine Device Driver Interface Library Specification

Step 5 – Entry Routine for Device Driver

The final step in creating a device driver is to register the device with the T-Kernel. The structure above describes the features of the device and the functions that the driver supports. Finally, we need to create an entry routine for the device driver and register the device.

The entry routine of the device driver is called when the device driver is loaded. The entry routine may be used to perform device-specific initialization, if required. In addition, it must make a system call to the T-Kernel to define and register the device. In the attached source code, this is done in sample_device_driver/src/main.c, line 130 – 160.

This is a standard step for the device drivers and is done by a call to SDefDevice().


LOCAL SDI DvcSdi;    /* device driver I/F handle */ (Global Variable)
ER    er;
T_IDEV    idev;

er  =   SDefDevice (&ddev, &idev, &DvcSdi);

ddev    : Pointer to Device Registration Structure (Refer to Step 1)
idev    : Pointer to location of device initialization information (T-Kernel)
DvcSdi  : Pointer to location of driver interface access handler    
er      : Error code returned

For more detail, refer to:

T-Engine/SH7727 Development Kit Device Driver Manual Chapter 2.4.1 – Define Device.

In Conclusion

This article introduces how to write a device driver for the T-Kernel based on the Simple Device Driver Interface. The concepts for a General Device Driver Interface (GDI) are similar and the concepts here can be extended to apply to the GDI model.

In Part 2 of this article, we will look at some of the issues in packaging, building and loading the device driver. We will also look at a simple application to use this device driver.

We are currently packaging the source code for this article and it will be made available soon.

Ubiquitous ID Technologies 2008

Fri, 28 Mar 2008 09:09:00 GMT

Ubiquitous ID Technologies 2008

The T-Engine Forum has just released more information that introduces the T-Engine in detail. It’s called “Ubiquitous ID Technologies 2008 by Ken Sakamura” and is available as a PDF from the Ubiquitous ID Center website at http://www.uidcenter.org/.

The document itself has 52 pages (all included) and has all the information that you need to understand what the Ubiquitous ID infrastructure provides. It goes into details about the technology aspects, such as the Ubqiutous ID infrastructure, authorized tags, security technology, sensor network technology and the ubiquitous communicator.

Afte this introduction, a significant portion of the document is devoted to applications of the Ubiquitous ID Technology. It covers experiments such as Ubiquitous Tracing, Food Traceability, Equipment management… and so on. This section is complemented by a comprehensive look at the Ubiquitous location information systems being deployed in Japan.

Finally, the document wraps up with an introduction to the T-Engine Forum and the TRONSHOW.

The document seems to be derived mostly from the panels that were released earlier and provides good high-level information about the Ubiquitous ID architecture. It can be got from http://www.uidcenter.org/english/documents.html

μT-Kernel Patch Spotted

Thu, 27 Mar 2008 05:18:00 GMT

μT-Kernel Patch Spotted

While doing a search for μT-Kernel related information, I stumbled across an “unofficial patch” for the μT-Kernel to make it run on the H8/3069. It is developed by SASANO Takayoshi and seems to be based on the H8S/2212 μT-Kernel port download available from the T-Engine Forum.

From what I can tell, it’s available in the public domain and can be used. The only problem you might face is that the documentation (comments, etc.) are all in Japanese.

I’ve contacted the author to find out more information about the port. If I find out anything else, I shall post it here.

The patch is available at the following URL: http://www.bi.a.u-tokyo.ac.jp/~uaa/codes/utkernel/20080320/

HOWTO: Define your own Interrupt Handler

Wed, 26 Mar 2008 01:26:00 GMT

HOWTO: Define your own Interrupt Handler

Written by: Mohit Sindhwani, Viometrix

In this brief ‘how-to’ article, we look at the method to be used for defining your own interrupt handler in the T-Kernel environment.

Background

Essential Reading: The main reference for this is actually Section 4.8 – Interrupt Management Function of the T-Kernel specification. Refer to that section for the necessary details.

Coding the Interrupt Handler

The T-Kernel allows developers to create two types of interrupt handlers: handlers written in assembly or handlers written in a high-level language. This article focuses primarily on high-level language handlers. Details for assembly language handlers is available in the T-Kernel specification.

The C function prototype for a high-level T-Kernel ISR is shown below:

EXPORT void tk_serial_isr (UINT dintno);

Typically, an interrupt handler should do the following:

Read/ write data from/ to the peripheral: This is the main task that needs to be done to respond to the interrupt.
Remove the interrupt request: In devices such as the UART, a read interrupt request is automatically removed when you read from the device. However, in some devices such as timers, it is necessary to write to a special flag that clears the interrupt request.
Inform the application that the interrupt occurred: In many cases, you will need to communicate to the running application that the event has happened. Typically, this is done by issuing a system call. To see the system calls that are possible from the ISR, check Section 3.2.2 of the T-Kernel specification.
Return from the exception: Finally, you need to return from the service handler. In the case of the high-level interrupt handler, you only need to issue a return; just as in a normal function. The T-Kernel handles the rest for you.


void tk_my_isr(UINT dintno)
{
    /*
     * Perform hardware-related work
     *
     * This is where you should put code for reading or writing to the
     * specific peripheral.  This part depends on your device
     */

     /* Sample: */
     c = ReadDatafromSerialDevice();

    /*
     * Remove the Interrupt Request
     *
     * If the hardware requires a specific method for removing the
     * interrupt request, you should deal with it.  Devices like
     * UART usually de-assert the interrupt when you read the data
     * but devices like timer require a special write request to
     * de-assert the interrupt.
     */

    /* Inform the application that the interrupt happened */

    /* Sample: */
    tk_sig_sem(sem_id, 1);

    return;
}

Registering/ Defining your Interrupt Handler

Once you have written the function for the interrupt handler, you need to register it with the T-Kernel so that it is called when the interrupt happens the next time. You register an interrupt handler by calling tk_def_int.

The C language interface for tk_def_int is as shown below:

ER ercd = tk_def_int (UINT dintno, T_DINT *pk_dint ) ;

Other than this, all you need to do is fill out the details of the T_DINT structure to include the following information:

The type of handler: high level or assembly (specified using TA_HLANG or TA_ASM respectively)
The address of the handler function

The TA_HLNG specifies that the interrupt handler being registered is a high-level language interrupt handler. The T-Kernel will do the necessary part to save the context, etc. before this function is called and will automatically restore the context after execution of the handler is completed.

The code for defining the interrupt handler is shown below. You need to call tk_def_int and pass it the interrupt number and the address of the T_DINT structure.


{
    T_DINT int_pkt;
    ER ercd;
    int_pkt.intatr = TA_HLNG;
    int_pkt.inthdr = tk_my_isr;
    ercd = tk_def_int (SERIAL_RX_ISR, &int_pkt);
}

That’s all there is to it! Once this is done, the T-Kernel will now call your specific function when the interrupt occurs.

What's the difference between ITRON and T-Engine?

Tue, 25 Mar 2008 12:35:00 GMT

What’s the difference between ITRON and T-Engine?

Written by: Mohit Sindhwani, Viometrix

This question came up recently on the TE@Onghu Developer Forum/ BBS and it seemed that this hasn’t really been adequately answered in any place. I had posted an answer to the forum and thought that it would be good to copy the ideas here also so that it serves as a reference for people searching exactly that question.

In this article, I’m expanding the question slightly and will try to explain the difference between T-Engine, ITRON and T-Kernel.

Software versus Platform

The first thing that one must realize is that both ITRON and T-Engine provide a set of specifications for real-time and embedded systems. The specifications are agreed on by a set of members and are released to members and the public. So, in its simplest sense, both come with open specifications.

However, there is a big difference in what they specify. In the case of ITRON, the specifications are for a hard real-time operating system (RTOS). On the other hand, the T-Engine specifications cover a much larger set of items – in simple terms, it is said that the T-Engine is an open platform for the development and execution of real-time and embedded systems. While it seems like a simple enough statement, looking at each of the words in that sentence gives a much better understanding of what it means. I’m not going to take the words in sequence but look at them in a different order.

Platform: It’s important to note that the T-Engine is a platform. In this sense, the specifications for the T-Engine cover not only the software aspects of the system (such as the operating system, boot monitor support and device driver profiles), but they also go further and cover other items such as the hardware platform, the vendor code system, binary formats, development environment and so on. In that sense, it is a complete set that specifies a platform that can then be used for a variety of purposes. Naturally, this is a big difference from ITRON that specifies just the Operating System kernel (since the TRON in ITRON stands for The Realtime Operating Nucleus). However, if you really must compare, you should compare ITRON with the T-Kernel that is the standard RTOS in the T-Engine platform.
Open: Well, the T-Engine is open in the sense that it is openly specified upon consensus between members who participate in various standardization (or specification?) committees. The specifications are then made open to the public and can be used by the general public in any way they see fit as long as due credit is attributed. The ITRON specifications are also open and can be obtained by the public.
Open = Open Source? There is a common tendency today to consider open to be analogous in meaning to the term ‘open source’. In terms of open source credentials, the T-Kernel is, in fact, available in source form. The source code has been prepared and released by the T-Engine Forum and it centrally manages the release of the code. The source code can be used in any commercial or non-commercial project on a number of processors without any changes being required and without charge. Although developers are free to make any modifications to the RTOS as they feel are needed, there are certain restrictions relating to the disclosure of the modified source code. One must read the license, of course. On the other hand, ITRON was very much, just a specification. There is an open-source implementation of ITRON called TOPPERS/JSP but most ITRON implementations are commercial implementations that are available from a number of vendors, including semiconductor companies.
Realtime and Embedded Systems: The T-Engine platform squarely targets the area of realtime and embedded systems. Therefore, all the specifications are designed with the policy of reducing unnecessary overheads and minimizing or removing items that may affect the hard real-time nature of the system. In this sense, ITRON is the same – it is also a hard RTOS targeted at embedded systems.
Development and Execution: Finally, the platform is targeted at being a development platform first – this means that it is specifically created in a manner to allow a large amount of flexibility so that it behaves like a super-development platform (it has most things you need and more!). This is clearly shown in the amount of expansion support it has – PCMCIA, USB host, serial and bus expansion. Further, you can purchase a number of expansion boards for the bus expansion connector – most notably, you can get a bare board for any custom chips you may need to integrate or an FPGA board for prototyping digital modules in hardware (either before creating a special board, or before you create your system on a chip). That said, the T-Engine is not just a ‘development’ platform – it’s also a platform for ‘execution’. If you are going to ship only small quantities of your system to your customers, you could ship the T-Engine board itself. The T-Engine has been designed to look good and smart in a form factor similar to a slightly large PDA and not like a sprawled out development platform with a lots of wires running across it and too big to pass off as a product.

In short, that concludes a first look at the T-Engine itself. So, it’s clear that the T-Engine and ITRON are not the best entities to compare. If we wish to make a technical comparison, we need to compare ITRON against T-Kernel.

What’s the difference between ITRON and T-Kernel?

Both ITRON and T-Kernel are real-time operating systems. In many sense, T-Kernel is the evolution of ITRON and should be seen as such. Therefore, there are a number of technical enhancements in the T-Kernel. However, there are a few important differences between ITRON and T-Kernel. The main differences between T-Kernel and ITRON are as follows:

Specification versus Source: In terms of deliverables from the T-Engine Forum, ITRON is only a specification. People who use the specification will build or buy an RTOS that is compatible with the specification. In the case of T-Kernel, the T-Engine Forum provides an implementation of the kernel in source form. This can be used under the conditions of the T-License.
As mentioned, T-Kernel (the RTOS in the T-Engine) is an evolution of ITRON. However, it has a richer API that supports its goal of being a platform for middleware distribution.
T-Kernel has a clear well-specified driver and subsystem guidelines to promote middleware distribution. ITRON focuses more on performance.
T-Kernel has extensions that cover the use of virtual memory. ITRON does not.
The single source of T-Kernel is written mostly in C but most ITRON implementations used to be written in C with a substantial amount of it also being written in assembly to support high performance on small-scale CPUs.
The T-Kernel API is similar to the ITRON API although it includes more functions. Also, one big advantage of the T-Kernel API is that the API is very similar for kernel versions ranging from small-scaled CPUs (like 8-bit or 16-bit microcontrollers) all the way to multi-CPU implementations. ITRON was never designed with such wide scalability in mind.

This list summarizes the main differences between ITRON and T-Kernel. However, there is one more contender that you should consider when looking at TRON Project outputs – this one is called the μT-Kernel. The μT-Kernel is a version of the T-Kernel that is specifically targeted at small-scale embedded systems. The picture below shows the evolution of the different kernels in the T-Engine space. As can be seen, there is a clear intention to move from the ITRON family to the T-Kernel family. The T-Kernel family essentially shares the same API across all the processor types – this allows programs written for the smallest CPUs to be run largely unmodified even on multi-processor CPUs.

Picture from: http://www.tron.org/tronshow/2008/bookmark/exhibit/00001c0000000000000100000009020c.pdf

So, is ITRON dead?

I think it’s wrong to say that ITRON is dead. There is still a lot of work that is ongoing with ITRON and many companies have large numbers of products, applications and middleware that currently run on ITRON – and there’s no immediate reason to change. To get some idea of the products that are running on ITRON, take a look at the Products Catalogue [PDF, 18MB] issued by the TRON Association – it gives a long list of products based on T-Engine, T-Kernel and ITRON. (In reality, the list is incomplete because the TRON Association did not require users of ITRON to specify that they are using the ITRON specification – the list is therefore based on voluntary disclosures).

Short Note: Source files for T-Engine Device Driver Interface Library

Mon, 24 Mar 2008 11:20:00 GMT

Short Note: Source files for T-Engine Device Driver Interface Library

The T-Engine Forum has a number of specifications that can be downloaded from their website. One of these specifications is called the T-Engine Device Driver Interface Library Specification and provides the specification and explanation of concepts that can be used for creating device drivers.

Specifically, it introduces the concept of Simple Device Driver Interface (SDI) and General Device Driver Interface (GDI). These can be used to provide a generic interface for creating device drivers. The specification refers to source code files that are not available from the specifications page.

In case you are looking for the source files for the device driver interface library, don’t worry! I got in touch with the T-Engine Forum Secretariat and asked them about the source code. The necessary files are included as part of the Source Code of Sample Driver for T-Kernel/SE and can be accessed from the downloads page of the T-Engine Forum website.

T-News: Updated Specifications & Source Code

Thu, 13 Mar 2008 12:18:00 GMT

T-News: Updated Specifications & Source Code

The T-Engine Forum has updated their release of the source codes for the T-Kernel and the μT-Kernel and has also released a new version of the specification for the μT-Kernel.

As always, the specifications can be downloaded from the Specifications Page and the source code is available from the Downloads page on the T-Engine Forum’s website

With this release, the T-Kernel Source Code has been updated to Ver.1.02.04 and the µT-Kernel Source Code and specification has been updated to Ver.1.01.00.

CPU Support

According to the downloads page, the open source T-Kernel works with the following CPUs: SH7727, SH7751r, SH7760, ARM926, ARM920, ARM720, VR5500, VR4131 and M32104. Further, it is compatible with the following CPUs by applying the patches that can be downloaded from their page: SH7145, M32192 , SH7780, MB91403, SH7720, SH7211 and SH7619. The version of the µT-Kernel available from their page works with the AT91 and H8S/2212.

TE@Onghu RSS Feed

SDI Device Driver Guide - Part 2

SDI Device Driver Guide – Part 2

Compiling the Device Driver

Running the Device Driver

Sample Device Driver – Include File

Sample Application using the Device Driver

Building and Running the Application

HOWTO: Assembly Language Interrupt Service Routines

HOWTO: Assembly Language Interrupt Handlers

Background

Coding the Interrupt Handler

Entry into the Handler

Return from the Exception

Template for Low-level ISRs

Examples of Low-level ISRs

Registering/ defining a Low Level ISR

HOWTO: Load an Application at System Startup

HOWTO: Load an Application at System Startup

Step 1 – Finding your friends (the files)

Step 2 – Adding your Entry

SDI Device Driver Guide - Part 1

SDI Device Driver Guide – Part 1

Equipment and Tools

Background

Creating the Device Driver

Step 1 – Functions to open and close the Device

Step 2 – Functions to read and write

Step 3 – Event Function

Step 4 – Driver Registration Structure

Step 5 – Entry Routine for Device Driver

In Conclusion

Ubiquitous ID Technologies 2008

Ubiquitous ID Technologies 2008

μT-Kernel Patch Spotted

μT-Kernel Patch Spotted

HOWTO: Define your own Interrupt Handler

HOWTO: Define your own Interrupt Handler

Background

Coding the Interrupt Handler

Registering/ Defining your Interrupt Handler

What's the difference between ITRON and T-Engine?

What’s the difference between ITRON and T-Engine?

Software versus Platform

What’s the difference between ITRON and T-Kernel?

So, is ITRON dead?

Further Reading

Short Note: Source files for T-Engine Device Driver Interface Library

Short Note: Source files for T-Engine Device Driver Interface Library

T-News: Updated Specifications & Source Code

T-News: Updated Specifications & Source Code

CPU Support

Links