e-soft Documentation

v1.2.1

SOFTWARE FOR EMBEDDED DEVICES V1.2.1

Contents

1 Introduction
2 Modules
2.1 Embedded Filesystem
2.2 Simple FTP demon
2.3 Simple HTTP demon
3 Demo Program
4 License
5 Contact Information

1 Introduction

This package contains two modules:

• A simple file system for embedded devices

• A simple but powerful FTP demon based on a standard BSD socket API and the embedded filesystem.

• A simple but powerful HTTP demon based on a standard BSD socket API and the embedded filesystem.

I developed this software package because I needed a FTP demon to be able to do software updates via ethernet to my embedded device. To save resources, the FTPD does only use one single task, and no further synchronization methods are required. For the TCP/IP stack I plan to use lightweight IP (project homepage: http://savannah.nongnu.org/projects/lwip). First I thought it would be sufficient to be able to store only a single file in the device' memory, but then I recognized the power of a real file system even in the embedded environment. With my file system you will be able to run a real HTTP server with either static html pages you have uploaded via FTP or dynamic pages that were created and stored to a file at runtime.

2 Modules

2.1 Embedded Filesystem

Source files: filesys.c, filesys.h, sys.h

The file system supports all usual methods, like opening / reading from / writing to a file, random accesses, renaming and deleting files, and searching for files to print directory listings.

Here is a list of some of the ANSI conform functions that are supported:

open, close, read, write, seek, tell, stat, findfirst, findnext

There is one small restriction: The file system does only support one physical directory. Sub-directories are not yet supported. But there is a bit 'cosmetic' implemented that simulates the presence of subdirectories. If the define FS_SUBDIRECTORIES is set to 1, some additional functions were exported to manage subdirectories, with knowledge that all files will still be stored in the root directory. Even when the filesystem behaves like it is capable of subdirectories, storing much files in the RAM drive will significantly decrease the file access time, since always all file entries must be searched.

The file system has one powerful feature: It handles up to two disk images. A disk image can be stored in RAM and thus is writable, or it can be stored in ROM and is then marked read-only. The combination of this two images would result in a powerful environment for a HTTP server: static web pages and pictures can be stored in ROM, and some writeable memory is used to store dynamically generated pages. The HTTP server will only need to access one directory in the filesystem, where all the files are stored.

The following steps must be performed to set up the file system:

• Call fsys_init (size, blocksize, maxFileNameLength). If 'size' is nonzero, a new RAM drive image is created with the given size (in bytes). 'blocksize' is the size of the smallest entity the filesystem can manage, and 'maxFileNameLength' is the maximum allowed length a filename can have. You should set 'maxFileNameLength' to a bigger value if you wish to use simulated subdirectories. If 'size' is zero, the file system will be initialized but no memory is assigned to it. In this case, 'blocksize' and 'maxFileNameLength' are don't cares.

• Optional: call fsys_addDriveImage to add a writeable drive image to the file system if fsys_init was called with size = 0, and/or:

• Optional: call fsys_addDriveImage to add a non-writeable drive image to the file system. The image may reside in a flash ROM or EPROM.

2.2 Simple FTP demon

Source files: ftpd.c, ftpd.h, sys.h

The FTP demon is socket based and single threaded. It allows multiple connections simultaneously. All necessary FTP commands for file up- and download are supported. But there is still a restriction: Only one username/password pair is supported (that means no rights-management is done).

The following steps must be performed to start the FTP demon:

• Call ftpd_start (username, password). This will start the demon and allows a user to log in with its 'username' and 'password'.

2.3 Simple HTTP demon

Source files: httpd.c, httpd.h, sys.h

The HTTP demon is socket based and single threaded. It allows multiple connections simultaneously. Currently the demon supports the HEAD and the GET method, which allows serving static and dynamic html pages. The http demon can be configured to support active content through a servlet mechanism (this is compareable to JAVA servlets, and works like cgi scripts).

The HTTP demon is conditionally compliant to HTTP/1.1 (RFC 2616).

The following steps must be performed to start the HTTP demon:

• Call the function httpd_start. This will configure and start the demon and allows http access to the directory given as parameter.

3 Demo Programs

The program 'ftpdrive.exe' (ftpdrive.c) demonstrates the usage of the file system, FTPD and HTTPD. It allows to load previously saved images to RAM, to create new RAM drive images and to store changed images to disk. Thus the program can also be used as tool to create ROM-able drive images to be used in an embedded HTTP server environment. Also the HTTP demon is included in this tool, so the RAM drive can also be accessed through a web browser.

The program 'servletdemo.exe' (sldemo.c and other files) demonstrate how to use the servlet mechansim. This demo program serves several dynamic html pages. The sourcecode of the servlets can be found in the demo subdirecty, the files are named from servlet1.c to servlet5.c.

The program 'httpserv.exe' (httpserv.c) is a small HTTP webserver for MS Windows. The program does not use the embedded filesystem; instead it does direct file access to the Windows filesystem. It allows you to set a root path at startup (command line parameter). The root is the directory where the file index.html is stored.

To build the demo programs, simply type 'make all' at the command prompt. The demo programs were tested with the MinGW compiler running under Windows 98 SE.

4 License

Copyright (c) 2004, Dennis Kuschel.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

5 Contact Information

Author:

Dennis Kuschel (dennis_k@freenet.de)
http://mycpu.mikrocontroller.net

---