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.
- Source Code Organisation
- The Demo Application
- 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
- 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.
- 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.
- 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.
- 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:
- Open a web browser on the connected computer.
- 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.
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 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:
- 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
The assembly file wrapper
- 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 C portion of the interrupt handler
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 ... */
Making use of the xPortUsesFloatingPoint() function to tell the RTOS kernel
which tasks need to maintain a complete floating point context
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.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
|
