SH7216 SuperH Demo
Including an Embedded Web Server Example
[Embedded Ethernet Examples]

This page presents the SuperH SH2A-FPU FreeRTOS port and demo application. The demo application is configured to run on the RSK+SH7216 evaluation board from Renesas, and uses the Renesas compiler and HEW IDE.

Included in the demo is an example web server that is implemented using a modified version of Adam Dunkels open source uIP embedded TCP/IP stack. The web server provides a basic CGI scripting facility which is used to display both RTOS and TCP/IP run time information. uIP is licensed separately from FreeRTOS. Users must familiarise themselves with the uIP licence, which is included at the top of each uIP source file.

IMPORTANT! Notes on using the Renesas SH7216 port and Web Server Demo

Please read all the following points before using this RTOS port.

1. Source Code Organisation
2. The Demo Application
3. RTOS Configuration and Usage Details

See also the FAQ My application does not run, what could be wrong?

Source Code Organisation

The HEW workspace for the SH7216 demo is called RTOSDemo.hws and is located in the FreeRTOS/Demo/SuperH_SH7216_Renesas directory of the main FreeRTOS download.

The FreeRTOS zip file download contains the implementation of all the FreeRTOS ports and every demo application project. It therefore contains many more files than used by this demo. See the Source Code Organization section for a description of the downloaded files and information on creating a new project.

SH7216 Demo Application

web server configuration

Connect the RSK+SH7216 evaluation board to a computer running a web browser either directly using a point to point (crossover) cable, or using a standard Ethernet cable through a hub or switch.

The IP address used by the SH7216 is set by the constants configIP_ADDR0 to configIP_ADDR3 which are defined at the bottom of the FreeRTOS/Demo/SuperH_SH7216_Renesas/RTOSDemo/FreeRTOSConfig.h header file. Constants that define the MAC address and the NET mask can be found in the same file.

The IP addresses used by the web browser and the RSK+SH7216 must be compatible. This can be ensured by making the first three octets of both IP addresses the same. For example, if the web browser computer uses IP address 10.10.10.1, then the RSK+SH7216 evaluation board can be given any address in the range 10.10.10.2 to 10.10.10.254, other than any addresses that already exist on the same network.

The MAC address assigned to the RSK+SH7216 must be unique on the network to which it is being attached.

Building and executing the demo application

1. Before opening the project - connect the RSK+SH7216 to the host computer using an E10A JTAG interface. The HEW will attempt to connect to the E10A as the project is opened.

    

2. Open the FreeRTOS/Demo/SuperH_SH7216_Renesas/RTOSDemo.hws workspace from within the HEW IDE - following the instructions to connect to the E10A interface as the project opens.

    

3. Select "Build" from the HEW "Build" menu - the demo application should build without errors although some [inexplicable] dependency errors and some [incorrect] warnings are produced.

    

4. Select "Reset go" from the debug menu to download the binary to the SH7216 and start the application executing.

    

Functionality

The application creates more than 40 demo tasks before starting the RTOS scheduler, then continuously dynamically creates and deletes another two tasks as the application executes. The tasks consist mainly of the standard demo tasks - which don't perform any particular functionality other than testing the port and demonstrating how the FreeRTOS API can be used.

The following tasks and tests are also created from within main():

• Check task

  This only executes every five seconds but has the highest priority to ensure it gets processing time. Its main function is to check that all the standard demo tasks are still operational. The check function maintains a status string that can be viewed at the very bottom of the "Task Stats" page served by the uIP TCP/IP web server. It also toggles LED5, with the toggle frequency being used to indicate the system status. A frequency of one toggle every 5 seconds means all the standard demo tasks are executing without error - if the toggle rate increases to 200ms then an error has been detected in at least one task.

   

• uIP task

  This is the task that executes the TCP/IP stack. All network processing is performed in this task.

   

• Reg test tasks

  These fill all the registers with known values, then check that each register still contains its expected value. Two reg test tasks are created, each of which uses different known values. The tasks run with very low priority so get preempted very frequently. A register containing an unexpected value is indicative of an error in the context switching mechanism. Both standard and floating point registers are checked. The nature of the reg test tasks necessitates that they are written in assembly code. They are implemented in regtest.src.

   

When executing correctly the demo application will behave as follows:

• LEDs LED0, LED1 and LED2 are under the control of the standard 'flash' tasks. Each will toggle at a fixed but different frequency.

   

• LED5 is under control of the 'check' task and will toggle every 5 seconds provided no errors are present.

   

• LED4 can be controlled (turned on and off) through the web server.

   

• The target hardware will serve the web pages described below to a standard web browser. To connect to the target:
  1. Open a web browser on the connected computer.
  2. Type "HTTP://" followed by the target IP address into the browsers address bar.
     
     Entering the IP address into the web browser
     (obviously use the correct IP address for your system)

Note that some RSK+SH7216 evaluation boards are fitted with an LCD while others are not. For this reason the LCD is not used by the demo.

Served Web Pages

The top of each served page includes a menu containing a link to every other page.

The RTOS stats page served by the SuperH web server
showing status information on each task in the system.

The run time stats page served by the SuperH web
server showing the processor utilisation of each task.

The served IO page

The IO page provides a simple interface to permit LED4 to be turned on and off via the web server. Changes are sent to the evaluation board when the "Update IO" button is clicked.

Other pages served include TCP/IP statistics and a large JPG image.

RTOS Configuration and Usage Details

SH7216 RTOS port specific configuration

Configuration items specific to this demo are contained in FreeRTOS/Demo/SuperH_SH7216_Renesas/RTOSDemo/FreeRTOSConfig.h. The constants defined in this file can be edited to suit your application. In particular -

• configTICK_RATE_HZ

  This sets the frequency of the RTOS tick. The supplied value of 1000Hz is useful for testing the RTOS kernel functionality but is faster than most applications need. Lowering this frequency will improve efficiency.

   

• BaseType_t

  Each port #defines 'BaseType_t' to equal the most efficient data type for that processor. The SuperH port defines BaseType_t to be of type long.

Interrupt priorities, registers and stacks

The current version of the FreeRTOS SuperH port requires any interrupt that makes use of the FreeRTOS API to use interrupt priority 1. Interrupts that do not make use of the FreeRTOS API can execute at any priority. Only API functions that end in "FromISR" or "FROM_ISR" can be called from an interrupt service routine.

Priority 1 interrupts must save their context to the stack, rather than a register bank.

Writing interrupt service routines (ISRs)

Often it is desirable for an ISR to perform a context switch - so the ISR returns to a different task to the one it originally interrupted. For example, if executing an interrupt caused a task to unblock and the unblocked task had a priority that was higher than the originally interrupted task, then the interrupt handler should return directly to the (higher priority) unblocked task.

ISRs that don't use the FreeRTOS API and cannot cause a context switch have no special requirements and can be written as per the compiler documentation. See the MTU interrupt handler called MTU_Match() and defined within main.c for an example.

Interrupts that do perform a context switch require an assembly wrapper. The assembly wrapper would normally call a standard C function handler, although the entire interrupt handler could be written in assembler if that was preferable. An example interrupt handler implementation is provided below.

To write an interrupt that can cause a context switch:

1. First create a wrapper within an assembly file exactly as demonstrated below. The only change that needs to be made from this example code is the name of the handler function that the wrapper calls - which in this example is _ISRHandler but in your code should be the real name of the interrupt handler C function. It is the assembler wrapper, not the C function it calls, that is used to populate the interrupt vector table.

    ; Import the C handler so it can be called from this file.  _pxCurrentTCB
    ; is also required.
    .import _ISRHandler
    .import _pxCurrentTCB
	
    ; Export the wrapper so it can be used to populate the vector table.
    .export _ISRWrapper

    ; This header file contains the portSAVE_CONTEXT and portRESTORE_CONTEXT
    ; macros.
    .INCLUDE "ISR_Support.inc"

    ; This wrapper goes into the program section.
    .section    P

;-----------------------------------------------------------
; The start of the assembly wrapper function.  This is what is used to 
; populate the vector table.
_ISRWrapper:

    ; portSAVE_CONTEXT must be called first!
    portSAVE_CONTEXT

    ; Next call the C handler function, although the whole interrupt handler
    ; could be written in assembly if that is preferred.
    mov.l    #_ISRHandler, r0
    jsr      @r0
    nop

    ; portRESTORE_CONTEXT must be called last!  This handles the exit from the
    ; interrupt.
    portRESTORE_CONTEXT

2. Next write the C portion of the ISR. This is just a standard C function that is called from the assembly file wrapper.

void ISRHandler( void )
{
long lHigherPriorityTaskWoken = pdFALSE;

    /* Perform the actual interrupt processing here - not forgetting to clear
    the interrupt source. */
	
    /* In this example, a semaphore is given from the ISR, and it is possible
    that giving the semaphore unblocks a task.  The semaphore has already
    been declared and created. */
    xSemaphoreGiveFromISR( xSem, &lHigherPriorityTaskWoken );
	
    /* If giving the semaphore did cause a task to unblock, and the unblocked
    task has a priority equal to or higher than the currently executing task
    (the interrupted task), then lHigherPriorityTaskWoken will have been set to
    pdTRUE.  Passing pdTRUE to portYIELD_FROM_ISR() will cause the required
    context switch. */
    portYIELD_FROM_ISR( lHigherPriorityTaskWoken );
}

The implementation of the Ethernet controller in the demo project can be used as a complete example. The wrapper for the Ethernet driver is define in EMAC_ISR.src, and the C portion of the handler in EMAC.c.

TRAPA vectors used by FreeRTOS

FreeRTOS makes use of both TRAPA 32 and TRAPA 33 instructions, meaning these two vectors are not available for use by the application.

Using the floating point registers

A task must be configured to maintain a floating point context if it either makes use of floating point variables directly or it calls library functions that might use floating point registers.

To tell the RTOS kernel that a task requires a floating point context pass the task handle into the xPortUsesFloatingPoint(xHandle) API function. xPortUsesFloatingPoint() must be called after the task is created but before the task first executes.

As an example, the following code can be found in main() of the SuperH demo application:

void main(void)
{
/* Declare a variable of type TaskHandle_t to temporarily hold the handle of 
the task being created. */
TaskHandle_t xCreatedTask;

    /* Create the task, storing the handle of the task in xCreatedTask. */
    xTaskCreate( vRegTest1Task, "RegTst1", configMINIMAL_STACK_SIZE, NULL, 
                 tskIDLE_PRIORITY, &xCreatedTask );
	
    /* The task uses floating point registers, so tell the RTOS kernel that it
    requires a floating point context. */
    xPortUsesFloatingPoint( xCreatedTask );
	
    /* ... rest of main() goes here ... */

Switching between the pre-emptive and co-operative RTOS kernels

Set the definition configUSE_PREEMPTION within FreeRTOS/Demo/SuperH_SH7216_Renesas/RTOSDemo/FreeRTOSConfig.h to 1 to use pre-emption or 0 to use co-operative.

Compiler options

As with all the ports, it is essential that the correct compiler options are used. The best way to ensure this is to base your application on the provided demo application files.

Memory allocation

Source/Portable/MemMang/heap_2.c is included in the SuperH demo application project to provide the memory allocation required by the RTOS kernel. Please refer to the Memory Management section of the API documentation for full information.

Miscellaneous

Note that vPortEndScheduler() has not been implemented.