Readme - Web Server Software Example

DESCRIPTION:	
A Web Server running from a file system in flash memory.

REQUIREMENTS:
This example will run on the following Nios II harware example designs:
- Standard
- Full Featured

In addition, one of the following Nios development boards is required:
- Nios II Development Board, Stratix II Edition
- Nios II Development Board, Cyclone II Edition
- Nios Development Board, Stratix Professional Edition
- Nios Development Board, Stratix Edition
- Nios Development Board, Cyclone Edition

PERIPHERALS USED:
This example exercises the following peripherals:
- Ethernet MAC (named "lan91c111" in SOPC Builder)
- STDOUT device (UART or JTAG UART)
- LCD Display (named "lcd_display" in SOPC Builder)

SOFTWARE SOURCE FILES:
This example includes the following software source files:

- web_server.c: Contains main() and LWIP callback to install tasks once LWIP 
  has been properly initialized.

- http.c: Implementation of an HTTP server including all necessary sockets
  calls to handle a multiple connections and parsing basic HTTP commands to 
  handle GET and POST requests. Requests for files via HTTP GET requests direct
  the server to fetch the file, if available, from the flash file system and 
  send it to the client requesting it.

- http.h: Header information defining HTTP server implementation and common
  HTTP server strings & constants.

- user.h: Definitions for the entire example application.

- network_utilities.c: Contains MAC address, IP address, and DHCP routines to
  manage addressing. These are used by LWIP during initialization, but are
  implementation-specific (for any implementation of this example not an Altera 
  Nios development board, Stratix, Stratix Professional, or Cyclone edition, 
  this file will need to be modified to control addressing in your system).

BOARD/HOST REQUIREMENTS:
This example requires an Ethernet cable connected to the development board's 
RJ-45 jack, and a JTAG connection with the development board. If the host 
communication settings are changed from JTAG UART (default) to use a
conventional UART, a serial cable between board DB-9 connector  and the host is
required. 

If DHCP is available, the application will attempt to obtain an IP
address from a DHCP server. Otherwise, a static IP address (defined in 
user.h) will be assigned after a 120-second timeout. The DHCP timeout can be 
adjusted in user.h. 

KNOWN ISSUES/LIMITATIONS
The read-only zip filesystem must be set to a flash memory device whose base
address is 0x0 (note that you may place read-only zip file system contents 
at any offset within the flash memory device). This limitation is scheduled
to be corrected in a future Nios development kit release.

ADDITIONAL INFORMATION:
This is an example HTTP server using LWIP on MicroC/OS-II. The server can 
process basic requests to serve HTML, JPEG, and GIF files from the Altera 
read-only zip file system. It is in no way a complete implementation of a 
full-featured HTTP server.

LWIP has two API's, a callback interface and "standard" sockets. This example
uses the sockets interface. A good introduction to sockets programming is the
book Unix Network Programming by Richard Stevens. Additionally, the text
"Sockets in C", by Donahoo & Calvert, is an concise & inexpensive text for
getting started with sockets programming.

To run the HTTP server, you must first program the file system using the Flash 
Programmer utility of the Nios II IDE. The read-only zip file system contents 
come from a .zip file ("ro_zipfs.zip" by default) in your application "syslib" 
library project by default. When the web-server application is built, the 
contents of this zip file are extracted and converted into a flash programming
file, "filesys.flash", located in the "<system library>/Release" folder of your
web-server. This file will be programmed into flash allowing the HTTP server
to fetch content at runtime. 

To build & run the web-server application, perform the following steps:

   === I.  BUILD PROJECT ===
1. After creating a new "Web Server" software example project and referring to 
   a Nios II "standard" or "full_featured" hardware example design .ptf file, 
   you may build it by choosing "Build All" from the Nios II IDE "Project" 
   menu.
  
2. Wait for the build process to complete. During the software build, the
   files necessary to run this example are generated.

   === II. PROGRAM FLASH === 
1. Select the web-server application project (the default project name is 
   "web_server_0" unless specified otherwise during project creation).
  
2. From the "Tools" menu, select "Flash Programmer".

2. Select "Flash Programmer" under the list of "Configurations:".

3. Press New.

4. Press Program Flash.

   Flash on your development board will now be programmed with the 
   web-server application, read-only zip file system contents, and a 
   boot-copier program. When your board is programmed with the standard
   or full_featured .sof file, the web-server application will boot and
   serve web content from flash in the read-only zip file system.

   === III. DEBUG ===
   The above instructions will allow you to run the web server when the FPGA
   has been configured. If you wish to manually download the web-server 
   application (for example, after making an edit and re-compiling), or if you
   wish to debug the web-server application, the following steps apply:

1. Program the standard or full_featured design (.sof file) into the FPGA 
   using the Quartus II Programmer.
   
2. In the Nios II IDE, again select the web server application project.

3. From the "Run" menu, select "Debug..." (to launch the debugger) or 
   "Run..." (to   download software to RAM and execute).

4. Select a "Nios II Hardware".

5. Press "New".

6. Press "Run" or "Debug" as appropriate.

Note: This example will not run on the Instruction Set Simulator (ISS).