Visit us at www.hitex.de, www.hitex.co.uk
or www.hitex.com
Hitex Germany
(Head Quarters)
Greschbachstr. 12
D-76229 Karlsruhe
Fax
+049-721-9628-0
+049-721-9628-149
Sales@hitex.de
Fax
800-45-HITEX
+1-949-863-0320
+1-949-863-0331
Info@hitex.com
Hitex USA
Hitex UK
Warwick University
Science Park
GB Coventry CV47EZ
Fax
+44-24-7669-2066
+44-24-7669-2131
Info@hitex.co.uk
Fax
+65-6566-7919
+65-6563-7539
Sales@hitexasia.com.sg
Hitex Asia
2062 Business Center
Drive, Suite 230
Irvine, CA 92612
25 International
Business Park, #04-62A
German Centre
Singapore 609916
Application Example
for
LPC2378
MCB2300 / FreeRTOS and WEB Server (GCC)
This documentation describes the example port of
the GPL FreeRTOS and UIP stack for LPC23xx from
NXP with WEB server function.
Architecture:
ARM
Device:
LPC2378
Chip Manufacturer:
NXP
Peripherals:
Ethernet Phy, LEDs, Speaker, LCD
Compiler:
GNU GCC ARM-elf v.4.0.3
Author:
Stefan Grohmann /Hitex Germany
Contact:
applications@hitex.de
Revision:
03/2007 - 002
ApplicationExample.dot - 09/2006 - 001
© Copyright 2007 - Hitex Development Tools GmbH
All rights reserved. No part of this document may be copied or reproduced in any form or by any means without prior written consent of Hitex Development Tools. Hitex Development Tools retains
the right to make changes to these specifications at any time, without notice. Hitex Development Tools makes no commitment to update nor to keep current the information contained in this
document. Hitex Development Tools makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular
purpose. Hitex Development Tools assumes no responsibility for any errors that may appear in this document. DProbe, Hitex, HiTOP, Tanto, and Tantino are trademarks of Hitex Development
Tools. All trademarks of other companies used in this document refer exclusively to the products of these companies.
Application Example
Preface
In order to support you when working with our products, we provide documents containing specific
examples, additional topics, special hints, detailed procedures etc.
This document explains features and functions of an application example to run with the HiTOP user
interface.
For more information on the current software and hardware revisions, as well as our update service,
please contact www.hitex.de, www.hitex.co.uk or www.hitex.com.
Contents
1
Scope and Disclaimer
3
2
Original Software and Documentation
4
3
3.1
3.1.1
3.1.2
3.1.3
3.1.4
3.1.5
3.1.6
3.1.7
3.1.8
3.1.9
3.1.10
3.1.11
3.1.12
3.1.13
3.1.14
3.1.15
Used Modules
C Sources
Low-Level Driver and Hardware-Related Modules
main.c
startup.s
portISR.c
port.c
lcd_mcb23xx.c
uIP_Task.c
uip.c
uip_arp.c
uip_arch.c
cgi.c
fs.c
fsdata.c
httpd.c
ethernet_lpc23xx.c
5
5
5
5
7
7
7
7
7
7
7
8
8
8
8
8
8
4
Header Files
9
5
5.1
5.2
Memory
Stack
Heap
10
10
10
6
API Usage
10
7
7.1
7.2
Customizing
FreeRTOS
uIP Stack
11
11
11
8
Board Configuration
13
9
9.1
9.2
Compiler-Specific Keys and Options
__attribute__((naked))
__attribute__((interrupt(IRQ)))
13
13
13
© Copyright 2007 Hitex Development Tools GmbH
Page 2/13
Application Example
1
Scope and Disclaimer
This software is a port of the current version of the FreeRTOS operating system for the ARM-based
LPC23xx controller by NXP (Philips Semiconductors). The port includes the hardware-related driver
and definitions as well as the standard tasks of the demo applications. Also included is an easy
implementation of an Ethernet communication on the LPC2378 controller.
Subject Matter
The design is made to show the implementation and configuration of the real time operating system on
the Keil MCB2300 board populated with the LPC2378 device and the basic functionality of the
Ethernet adapter on the board with the provided PHY device.
Basic software is the GPL licensing model, laid open on www.freertos.org. The implementation is 'as it
is' and no warranties are made. The use and the change of the code is free and not under control of
the originators
Requirements
•
•
•
•
•
•
Hitex HiTOP5.2 ARM Development System with Tanto or Tantino
Keil MBC2300 board
LPC2378 controller
System tool provided by MS-Windows OS or alternate
Ethernet connection for the LPC board
WEB browser
Features and Components
•
•
•
•
•
•
•
Platform: LPC2378 ARM core with Ethernet phy
Keil MCB2300 board or equivalent
GNU ARM compiler GCC-hitex-elf version 4.0.3
LIBs (Interwork / GNU ARM compiler)
LCD, LED, Speaker peripherals are used
Featured IP stack functions: icmp, arp, Ethernet protocol, Ethernet peripheral is used
WEB server application with basic CGI capabilities
© Copyright 2007 Hitex Development Tools GmbH
Page 3/13
Application Example
Procedure
Installing
1. Step:
2. Step:
3. Step:
4. Step:
Install HiTOP 52 ARM.
Configure the Keil evaluation board.
Supply power to the evaluation board.
Connect the Ethernet connector (RJ45) to an existing physical network.
Starting
1. Step: Copy the project data to the working directory.
2. Step: Load the project with the HiTOP 5 user interface.
3. Step: When running a project in HiTOP, select the appropriate Tanto/Tantino device connected to
the evaluation board.
4. Step: Perform a target reset and run the project with the preconfigured settings.
Customizing
1. Step: Enable or disable selected tasks in the main.c file by commenting them according to your
individual needs.
2. Step: Adjust the Ethernet MAC address to a free and valid address in the network (file
peripherals_config.h).
3. Step: Adjust the TCP/IP address to a free and valid address in the network (file uIP_Task.c)
4. Step: Adjust the stack size to the enabled tasks in the file startup.s section “Stack size definitions”.
5. Step: Adjust the heap size if necessary in the file FreeRTOSConfig.h
(see configTOTAL_HEAP_SIZE definition).
6. Step: Recompile the project, download to the target hardware, perform a target reset and run.
7. Step: Run PING or other network tool to the specified address or MAC.
8. Step: Run a WEB browser tool and open the WEB server entering: http://<IP Address>
2
Original Software and Documentation
For more information on the FreeRTOS operating system see the related documents on
www.freertos.org.
The current version 4.0.3 and the port to the LPC23xx hardware offer basic functions of real-time
handling, task management and memory management based on the original codes. Other
applicational functions can be applied on this basic software.
The software contains also demo applications running in different OS modes.
For information on the UIP stack, see the related document provided by Mr. Adam Dunkels
(www.sics.se).
The current port to the hardware offers basic functions on the Ethernet protocol. Especially the ARP
protocol is implemented in the higher layer as they are provided by the original uIP software. Other
high-layered protocol functions can be applied on this basic software. The WEB server application
including all stack issues is running as a privileged task on the uIP RTOS system.
© Copyright 2007 Hitex Development Tools GmbH
Page 4/13
Application Example
3
Used Modules
This chapter describes source files changed or adapted for the FreeRTOS demonstration project. For
information on all other files not described here, refer to www.freertos.org.
3.1
C Sources
All sources are written in pure C following the ANSI rules nearly strictly. For all sources originated by
the GPL code of the original FreeRTOS implementation the originator is responsible.
Main.c
Main routine invoking the hardware setup and RTOS
Startup.s
inthandler.s
ethernet_lpc23xx.c
lcd_mcb2300.c
port.c
portISR.c
ASM file for setup routines
ASM for interrupt handler
Hardware-specific routines for the Ethernet module (low-level driver)
Task- and hardware-specific routines for the LCD module
Controller-specific routines for basic RTOS functions
Controller-specific routines for interrupt processing
croutine.c
heap_2.c
list.c
queue.c
tasks.c
Cooperative routines
Memory management
Task list functions
Queue management
Kernel control
flash.c
ParTest.c
print.c
semtest.c
klick.c
etherlink.c
Task: Demo to flash LEDs
Help routines to access IO
Task: Demo for queuing task
Task: Demo for semaphore task
Klick task
Ethernet connection control task
uip.c
uip_arp.c
uip_arch.c
UIP stack core
ARP protocol handler
Architecture-specific routines (CRC calculation)
cgi.c
fs.c
fsdata.c
httpd.c
CGI script routines
File system emulation
WEB content
WEB server
3.1.1
Low-Level Driver and Hardware-Related Modules
For information on the files Startup.s , inthandler.s , lcd_mcb2300.c and ethernet_lpc23xx.c, see the
related documentation of the Low-Level Driver from Hitex Development Tools (LowLevelDriverAPI_12.pdf).
3.1.2
main.c
The main program (main.c) provides the following routines:
© Copyright 2007 Hitex Development Tools GmbH
Page 5/13
Application Example
prvLCDOutHitexLogo()
Prints out an example text to the LCD module.
Lprintf()
Should be used to print single line messages to the LCD.
Main()
The main routine contains a call for all related hardware setup routines (prvSetupHardware()). The
startup code in file startup.s initializes hardware components like PLL and clock. After LCD
initialization and primary LCD output, the uIP task is created with highest applications priority. In
addition, some of the demo tasks are created with their selected priority. As last execution, the
Ethernet phy and the according peripheral unit with DMA are initialized.
As the first and special task, the uIP task is created. This task sets up all applicational functions and
runs the stack for Ethernet communication and the WEB server function. After all applicational tasks
the highest prioritized task vErrorChecks is started. At this point the operating system is ready to run.
All tasks are created, i.e. initial routines are done and memory is allocated. Now the IDLE task has to
be created and the timer has to be started. This is done in the function vTaskStartScheduler(). Note
that the routine is not written as an endless loop, because the operating system is invoked and the
routine is left.
Another additional task is the EtherCheck task which runs with lowest priority and low rate to check the
connectivity of the phy device and reinitialize it if re-connected after disconnection. This task enables
autonegotiation which is supported by the phy device.
vErrorChecks()
This routine is the highest priority task calling the routine prvCheckOtherTasksAreStillRunning().
prvSetupHardware
This routine is called at the entry of the main function to configure the controller’s peripherals if they
are not configured with the task creation process.
prvToggleOnBoardLED()
This routine is not used.
prvCheckOtherTasksAreStillRunning()
This routine checks for all the applications if they are still running or if an error occurred.
vMemCheckTask()
This dynamic task routine is created and deleted during each cycle of the vErrorChecks() task to
check the operation of the memory locator.
© Copyright 2007 Hitex Development Tools GmbH
Page 6/13
Application Example
3.1.3
startup.s
One of the main aspects on ARM controllers is the usage of appropriate startup code. The basic
initialization and memory allocation is done via this file.
3.1.4
portISR.c
This module includes the routine to initialize and handle the VIC interrupt of the timer 0 unit. Also the
disabling and enabling of the interrupts is handled.
3.1.5
port.c
This module contains the controller-specific implementation of the VIC and timer 0 initialization and
stack initialization routine
3.1.6
lcd_mcb23xx.c
This source provides simple setup routines for the LCD module attached to the MCB2300 board. Use
the routine “vLCDInit(void)” to initialize the LCD module. With the routine "vLCDGoto (uint32_t x,
uint32_t y)" an individual position on the LCD can be accessed. Routines as "vLCDPutc (int8_t c)",
"vLCDPuts(int8_t *sp)" and "vLCDBargraph (uint32_t val, uint32_t size)" can be accessed by the user
to write data to the LCD module or create a progress bar using user-defined fonts.
Also a task handler is realized to provide a progress bar and a running text into the second line of the
LCD display.
3.1.7
uIP_Task.c
Initialization of the UIP stack with its basic ARP functionality. This initialization also includes the start of
the WEB server via the httpd_init() function call. In an endless loop, the protocol is handled. The first
call (uip_len = (unsigned int)ulReadFrame(uip_buf);) checks the status of the input buffer. If some data
are received the return value should be greater than zero. In the following, the protocol is checked for
its type and the appropriate function is called. The stack uses only one main buffer for incoming and
outgoing data. If there is something to send, the global variable “uip_len” is greater than zero and the
sending routine (eEthSendFrame((uint32_t) uip_len, (uint8_t*) uip_buf);) is called with a pointer to the
related output buffer where the data is stored.
3.1.8
uip.c
This module contains the main part of the UiP stack written by Adam Dunkels. Here, the basics of the
TCP/IP handling and other protocol stuff like checksum etc. are implemented. For detailed information
see the documentation of the UiP stack.
3.1.9
uip_arp.c
This module (written by Adam Dunkels) contains all the functions required for address resolution
protocol functionality.
© Copyright 2007 Hitex Development Tools GmbH
Page 7/13
Application Example
3.1.10 uip_arch.c
This module provides the necessary CRC routines for high-level protocol layers written by Adam
Dunkels. The ARM architecture of the LPC2378 supports MAC function with its building hardware. The
routines are designed to support a compilation for this hardware-specific feature.
3.1.11 cgi.c
The CGI module provides script-like routines for CGI functionality. The call of a script on the browser
invokes the corresponding function in the CGITAB and the function delivers answering strings with
formatted “sprintf” calls to the applications data register “uip_appdata”. This register is added to the
Ethernet and TCP/IP header in the uiP task routine by giving them to the low-level driver. The module
also serves the statistic output on the Ethernet stack. To enable this the pre-processing option
“UIP_CONF_STATISTICS” is set to 1 in the uip-conf.h file. To have proper usage of the uIP statistical
functions, the stats struct have to be attributed as packed to provide correct alignment.
3.1.12 fs.c
This module provides basic file system functions to the WEB server. Parts of the file system functions
are also called via CGI script. The main routine “fsopen()” enables the WEB server to open the correct
file required by the browser. The routine simply gives back a pointer to the according character set in
the flash memory. The file “fsdata.c” is included to this file and must not be included or linked explicitly.
3.1.13 fsdata.c
This file holds the content of the WEB server application. All HTML sites, cgi files or pictures are coded
here in the form of character arrays. These arrays are part of a struct encoding name, address and
length of the files. The data are build with a separate tool from Adam Dunkels.
3.1.14 httpd.c
This module contains all handling routines to the WEB server subset. The basic functions for
interpreting CGI scripts are located here, too. The initialization is done by calling “httpd_init()” from the
main task routine.
3.1.15 ethernet_lpc23xx.c
See the document "LowLevelDriverAPI_1-2.pdf". The call of the routine “eEthSendFrame()” is
changed to provide two string addresses with according length. This feature releases from adding the
strings separately and serving them as one big string to the routine. In this way execution time is
shortened.
© Copyright 2007 Hitex Development Tools GmbH
Page 8/13
Application Example
4
Header Files
Main.h
Main routine
Defines.h
Peripherals_lpc23xx.h
ethernet_lpc23xx.h
peripherals_config.h
lcd_mcb2300.h
portmacro.h
portable.h
General definitions and types
Hardware related stuff
Low-level driver stuff
Low-level driver stuff
LCD routine stuff
Routines to switch context
Memory allocation
croutine.h
FreeRTOS.h
FreeRTOSConfig.h
list.h
projdefs.h
queue.h
semphr.h
task.h
Cooperative task stuff
Main include for FreeRTOS
Configuration file
Structs and macro for list stuff
Project definitions
Queue stuff
Semaphore stuff
Type definitions and macros for the kernel
flash.h
partest.h
print.h
semtest.h
etherlink.h
klick.h
Task pre-declaration and const for the flashing task
Task pre-declaration and const for the parallel port task
Pre-declaration and const
Task pre-declaration and const for a semaphore task
Task pre-declaration and const for Ethernet reconnection task
Task pre-declaration and const for click task
uip.h
uip_arch.h
uip_arp.h
uip-conf.h
uipopt.h
uIP core prototypes and configuration
uIP architectural stuff and prototypes
uIP ARP related stuff and prototypes
uIP basic configuration and prototypes
uIP configuration and prototypes
cgi.h
fs.h
fsdata.h
httpd.h
Declaration and configuration for the CGI script module
Declarations for file system of the WEB server
Declaration of the fsdata file structures
Declares the WEB server as application of the uIP stack
© Copyright 2007 Hitex Development Tools GmbH
Page 9/13
Application Example
5
Memory
In general the amount of RAM on embedded systems is limited and/or they have different timing
restrictions if external RAM is used. The Free RTOS port offers a single scheme to handle the
allocation algorithm. Several schemes are available but the HEAP_2 is chosen. Since uIP is optimized
for small controller resources, the memory usage is not excessive.
5.1
Stack
The overall size of the reserved stack memory is declared in the startup.s file. The ARM architecture
enables to define stack for several processor modes. It is recommended (even for good coding style)
to allocate the stack in the appropriate modes. The timer of the RTOS uses IRQ especially by using
the VIC unit. In this case, the stack should be allocated on IRQ mode section. If the stack is accessed
and there is no special routine for checking the processor mode, the stack is treated as a linear
memory area with descending addressing. The amount of stack to allocate is depending strictly on the
count of tasks and the individual configured stack sizes in the tasks. The uIP core takes some
additional stack. This should not be caused by the receive and transmit buffer.
5.2
Heap
The size of allocated heap memory is defined in the file FreeRTOSconfig.h with the definition of
configTOTAL_HEAP_SIZE. This memory block takes quite a lot of the controller resources.
In general, it is application-specific how many heap should be allocated. In detail, the kernel control
task uses the highest amount of heap memory.
6
API Usage
The usage of the implemented co-routines is set off with the option "configUSE_CO_ROUTINES 0" in
the file FreeRTOSConfig.h. The co-routines provide a set of prioritized cooperative routines. They
come along with reduced RAM usage. Otherwise tasks are fully preemptive and are similar to the socalled traditional scheduling model. The FreeRTOS API allows general task creation, control, queuing
and semaphores as well as kernel control and some task utilities. Further documentation is provided
on www.freertos.org.
© Copyright 2007 Hitex Development Tools GmbH
Page 10/13
Application Example
7
Customizing
7.1
FreeRTOS
The OS is roughly configurable. The configurations and options are described in the related
documents on www.freertos.org. In this document, only the options used are described. All these
options have strong effects on the behavior of the OS and should be changed carefully. All the
following options are set in the file FreeRTOSConfig.h. The options used are the following:
•
•
•
•
•
•
•
•
•
configUSE_PREEMPTION
1
Needed if preemptive tasking is used.
configUSE_IDLE_HOOK
0
Set to zero since the predefined prototype vApplicationIdleHook() is not used. Instead of
implementing tasks with the “IDLE priority”, the definition is used.
configUSE_TICK_HOOK
0
Used for executing intermediate code in the tick interrupt. The option is set to zero.
configCPU_CLOCK_HZ
( ( unsigned portLONG ) 48000000 )
The PLL and Clock configuration is set to 48 MHz. Since the USB peripheral unit device is used,
the frequence should be adjusted to 48 MHz. The APB divider is set to the system clock frequency.
configTICK_RATE_HZ
( ( portTickType ) 1000 )
Causes a minimal tick of 1 ms on the timer interrupt.
configMAX_PRIORITIES
( ( unsigned portBASE_TYPE ) 5 )
Sets the maximum priority to the given value.
configTOTAL_HEAP_SIZE
( ( size_t ) ( 10 * 1024 ) )
Affects the memory consumption of the OS enormously. If the size is set too small, the RTOS does
not work correctly. If set too high a 'run out of memory' may occur.
configUSE_TRACE_FACILITY
0
Allows additional so-called debugging features on the OS. The trace can be used to log a specified
time of the task management. The data can be given to a tool and converted to spread sheet
format.
configIDLE_SHOULD_YIELD
1
Has only effects if the preemptive scheduling is used. A setting prevents the scheduler from ending
a task before the time slice is run out.
7.2
uIP Stack
Most of the uIP configurations can be done by editing the file uip-conf.h. The most important points of
interest are mentioned here.
•
•
•
UIP_CONF_MAX_CONNECTIONS 40
Allows multiple connections but takes RAM.
UIP_CONF_BUFFER_SIZE
1536
Defines the size of the receive/send buffer which is treated by the uIP stack. Since only one buffer
is used for in and out, the size should be adjusted to the performance of the low-level driver.
UIP_CONF_LOGGING
0
Enables logging features implemented in the original uIP stack. For small applications like WEB
server or ICMP messages, the logging feature is disabled for performance reasons.
© Copyright 2007 Hitex Development Tools GmbH
Page 11/13
Application Example
•
•
UIP_CONF_BYTE_ORDER
LITTLE_ENDIAN
Essential for the CPU architecture.
UIP_CONF_STATISTICS
1
This option enables the statistical functions of the WEB server for use with the stats CGI script
Some more low-level options are available in the file peripherals_config.h:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
SA0, SA1, SA2, SA3, SA4, SA5
Represent the MAC address of the Ethernet port.
NUMBER_REC_FRAGMENTS
12
MAXLENGTH_REC_FRAGMENT 600
Define the DMA memory structure is used by the Ethernet peripheral unit. The memory is limited to
16k. The product of (NUMBER_REC_FRAGMENTS-1) times (MAXLENGTH_REC_FRAGMENT)
should not exceed this limit. The bigger the fragment sizes are set the more memory is used for
receiving data with smaller frame size, as each new frame must be stored in one record fragment.
This option has no effects on the possible packet or frame length.
MAXLENGTH_REC_FRAME
1536
Defines the maximum size of an inbound frame.
NUMBER_TX_FRAGMENTS
2
Defines the output buffer of the low-level driver.
MAXLENGTH_TX_FRAGMENT
1536
Defines the output buffer of the low-level driver. The maximum length should be the same as the
inbound frame length and the buffer length uIP stack is working with.
PHYSPEED
AUTONEGOTIATION
If set to AUTONEGOTIATION, the phy is enabled and scanned for connection speed.
ACCEPTUNICAST
If enabled (TRUE), all unicast frames are accepted.
ACCEPTBROADCAST
If enabled (TRUE), all broadcast frames are accepted.
ACCEPTMULTICAST
If enabled (TRUE), all multicast frames are accepted.
ACCEPTUNICASTHASH
If enabled (TRUE), those unicast frames are accepted which pass the imperfect hash filter.
ACCEPTMULTICASTHASH
If enabled (TRUE), those multicast frames are accepted which pass the imperfect hash filter.
ACCEPTPERFECT
If enabled (TRUE), frames with a destination address identical to the station address are accepted.
MAGICPACKETWOL
If enabled (TRUE), the magic packet filter will generate a WoL (Wake-up on LAN) interrupt when
there is a match.
RXFILTERWOL
If enabled (TRUE), the result of the perfect address matching filter and the imperfect hash filter will
generate a WoL (Wake-up on LAN) interrupt when there is a match.
© Copyright 2007 Hitex Development Tools GmbH
Page 12/13
Application Example
8
Board Configuration
The Keil evaluation board MCB2300 must be configured for using a JTAG wiggler like Tanto or
Tantino. To enable the port2 function, remove the jumper J13 (labeled as 'JTAG'). This jumper
enables the trace port of the LPC23xx device. If the jumper is closed, the port2 is occupied by the
control function of the trace module and no access to the onboard LED is possible.
9
Compiler-Specific Keys and Options
This chapter describes the compiler related, specific keys and options to handle the code with the
GCC compiler.
9.1
__attribute__((naked))
The attribute “naked” prevents the compiler from using prolog and epilog. This attribute is to use for
interrupt handling without access to the stack. Stack handling must be performed by the software.
9.2
__attribute__((interrupt(IRQ)))
This attribute forces the compiler to generate an interrupt function with entry and exit routine. This
routines affecting the stack can only be used for normal interrupt handling with stack operation. The
OS requires to add the attribute “naked” to this attribute. In this case, the compiler will not create
prolog and epilog causing the stack and link register contents remaining unchanged. At this point of
the program the task switching can be done. Allowed values for this parameter are: IRQ, FIQ, SWI,
ABORT and UNDEF.
„
© Copyright 2007 Hitex Development Tools GmbH
Page 13/13