Introduction

To use KwikNet with the Analog Devices, Inc. VisualDSP++ IDDE and VDK kernel there are a number project settings which must be made. These include, but are not limited to, header file include paths, library search paths, predefined thread types and Link Description File options.

KwikNet for Blackfin includes VisualDSP++ 4.0 project files configured for an ADSP-BF537 processor. You can easily build and run any of the KwikNet Sample Programs for a target like the ADSP-BF537 EZ-KIT Lite. If you are using a prior version of the VisualDSP++ tools or if your target processor is not an ADSP-BF537, please refer to Creating a Project from Scratch.

As a prerequisite, you must install both KwikNet and the Treck TCP/IP stack before proceeding. Prior to launching the IDDE, you must set environment variable TRKPATH to contain the location of your Treck installation directory. The prebuilt KwikNet Sample Program project files have been configured with the Treck files installed in directory \TRECK on the same drive as the KwikNet installation. If your Treck files are installed in a different location, you will have to modify the prebuilt sample projects or create your own projects.

The KwikNet TCP/IP Sample Program in installation directory ...\KNT743\TOOLAD\SAM_TCP will serve as a good starting point when you are ready to create your own project. Note that the project provided by KADAK uses relative file and directory paths so that as long as the KwikNet directory structure is retained, the project directory SAM_TCP can be easily duplicated (and presumably renamed) within subdirectory TOOLAD.

 The KwikNet Sample Program

A VisualDSP++ project for the KwikNet TCP/IP Sample Program is installed in your KwikNet installation directory. If you have installed KwikNet in directory C:\KNT743, the KwikNet TCP/IP Sample Program project file will be C:\KNT743\TOOLAD\SAM_TCP\KNSAMPLE.DPJ. Assuming that you have already installed VisualDSP++ 4.0, KwikNet for Blackfin and the Treck TCP/IP stack, begin by launching the VisualDSP++ IDDE.

Make sure that you have selected an ADSP-BF537 target as your debug target and platform as shown below.

 

 

Open the project file for the KwikNet Sample Program as shown below.

 

 

The project consists of the following files:

KN_BOARD.C	KwikNet board support for the Blackfin VDK board
KNCONSOL.C	KwikNet console I/O services
KNRECORD.C	KwikNet message logging services
KNSAMOS.C	KwikNet Sample Program OS interface for the Blackfin VDK
KNBF5XXS.C	Blackfin ADSP-BF5xx UART I/O support
KNBF5XX.ASM	Exception Handler Function UserExceptionHandler() in this module is invoked by the kernel to notify the application of an exception. As delivered, function UserExceptionHandler() only services EXCPT 1 software generated exceptions in order to enter supervisor mode. You may wish to extend function UserExceptionHandler() to handle other software or hardware generated exceptions. Add your code at the point indicated by the comments included in the function. Be sure to save and restore any registers that you modify.
KNSAMPLE.C	TCP/IP client/server sample program
KNSAMPLE.LDF	Link Description File The size and location of all memory segments have been specified to accommodate the memory requirements of the KwikNet sample programs.
KNSAMPLE.VDK	VDK configuration parameters
VDK.CPP	VDK configuration module
VDK.H	VDK configuration definitions

 
The KwikNet Sample Program project has a basic VDK configuration consisting of three predefined thread types, as shown below.

Kn_ostmain is the KwikNet Task thread which initializes and services the TCP/IP stack. The thread priority may be adjusted. However, all application threads which use KwikNet services must have a lower priority than this thread. Thread kn_osttick provides a timing signal to the kn_ostmain thread for periodic stack service. This thread must be of higher priority than the kn_ostmain thread. The apptask thread is a thread template used to spawn application threads in the KwikNet sample programs. The actual thread priority and stack size are assigned when the thread is created.

The KwikNet samples have a single boot thread, kn_ostboot. This boot thread is the actual KwikNet Task thread kn_ostmain. The kn_ostmain initialization code prepares KwikNet for use, launches the sample program application (i.e. spawns one or more apptask threads) and then waits for the application to start KwikNet with a call to kn_enter().

KwikNet creates three semaphores at startup and will create a semaphore for each thread that needs to block pending completion of a KwikNet operation. As shown below, the VDK configuration must accommodate the dynamic creation of semaphores.

 Building the KwikNet Library

Prior to building the KwikNet TCP/IP Sample Program, you must build the KwikNet Library. The library and the features to be included in it are specified in the KwikNet Network Parameter File which you can edit using the KwikNet Configuration Manager. The TCP/IP Sample Program Network Parameter File KNSAMLIB.UP is located in directory TOOLAD\SAM_TCP.

A make file is used to build the KwikNet Library. The make file is generated from the KwikNet Network Parameter File. To allow the KwikNet Library to be built without having to leave the IDDE environment, KADAK has provided script file KNMKLIB.TCL which resides in the same directory as the VisualDSP++ project file. The script generates the make file and invokes the Microsoft NMAKE utility to use it to build the KwikNet Library. You will have to modify the script file KNMKLIB.TCL if you wish to use a different make utility. Run the script from the IDDE as shown below.

Notes:

• KNMKLIB.TCL requires that environment variable TRKPATH be set to point to your Treck installation directory.
• KNMKLIB.TCL contains relative file path information. The script may need to be modified if it is not run from one of the KwikNet Sample Program directories.
• To build the KwikNet Library without using the script, read the section below, Creating a Project from Scratch.

 

 

When the script for the TCP/IP Sample Program completes, there will be one library file, KN743IP.DLB, in the TOOLAD\LIB directory. If you edit your Network Parameter File, you must run the KNMKLIB.TCL script again to regenerate your KwikNet Library.

 Building the KwikNet Sample Program

The KwikNet Sample Program requires access to the INCLUDE directory of your Treck installation. The VisualDSP++ IDDE project for the KwikNet Sample Program has been configured to search directory \TRECK\INCLUDE of the current drive for the required header files. If your Treck installation is on a different drive or has a different path, you will have to adjust the include path setting of the KwikNet Sample Program project before building the sample.

Build the sample program as shown below. A notification message may pop up indicating that the project settings have changed. To acknowledge the message, if and when it pops up, click on the Yes button. The output window will display progress messages as the various sample program modules are compiled, assembled and linked. The output window will appear as illustrated below once the sample program has been successfully built.

 

 

 

The program may or may not be automatically loaded by the simulator, depending on your VisualDSP++ preference settings.

 Creating a Project from Scratch

To create a VisualDSP++ project to use KwikNet with the Analog Devices VDK, proceed as described in this section. It is recommended that you start with an existing project such as that used to build the KwikNet TCP/IP Sample Program. It will be assumed, for purposes of illustration, that KwikNet for Blackfin is installed in directory C:\KNT743 and that the Treck TCP/IP stack is installed in directory C:\TRECK.

Before creating your VisualDSP++ project, use the KwikNet Configuration Builder to create your KwikNet Network Parameter File as described in Chapter 2 of the KwikNet TCP/IP Stack User's Guide. Alternatively, use the builder to edit the Network Parameter File KNSAMLIB.UP provided with the KwikNet TCP/IP Sample Program. If you are creating a new Network Parameter File, be sure to select the Blackfin ADSP-BF5xx target and the Analog Devices VDK operating system as shown in the following snapshots. Selecting Standard C as the Memory Allocation scheme will direct KwikNet to allocate memory from the program heap using standard calls to the C runtime library. Refer to the KwikNet TCP/IP Stack User's Guide for the memory allocation requirements of KwikNet.

 

 

The Network Parameter File KNSAMLIB.UP is used to generate the Network Library Make File KNSAMLIB.MAK. If your Network Parameter File changes, you must regenerate the Network Library Make File, rebuild the KwikNet Library and rebuild your application.

The KwikNet Library cannot be built until the VDK header file VDK.H is available. File VDK.H is created by the VisualDSP++ IDDE.

Create a new project as shown below.

 

 

 

Open the Project Options window as shown below. Specify your target processor (in this case, the ADSP-BF537) and enter the path to the INCLUDE directory of your Treck installation. If necessary, specify directory paths for other KwikNet options used by your application.

 

 

 

The following table outlines the locations of the various header files relative to the installation directory. If you are creating your project in a subdirectory of the KwikNet installation directory (e.g. C:\KNT743\TOOLAD\MYSAMPLE), it is best to specify paths relative to the project directory. By doing so, the entire KwikNet installation directory can be copied or moved to another directory without having to revise all of the path information in the project settings. You may also need to specify the current working directory "." in your list of includes. The table below also lists the KwikNet runtime libraries which must be added to your link options if the indicated services are used by your application.

Directory	Library	Services
\TRECK\INCLUDE	..\LIB\KN743IP.DLB	IP related header files; TCP, UDP sockets interface; SLIP, PPP, PING, DNS, DHCP, FTP, TFTP, Telnet, SMTP. This path must be specified. An up-to-date copy of file VDK.H (produced by the IDDE) must be copied to this directory before you build the KwikNet Library.
	..\LIB\KN743IPS.DLB	IPsec support.
	..\LIB\KN743IP6.DLB	IPv6 support.
\TRECK\SNMPD	..\LIB\KN743SNM.DLB	Simple Network Management Protocol (SNMP) agent and services.
..\TOOLAD\DRIVERS		Board and device driver definitions. Must be included to use any of the standard KwikNet board support modules or Ethernet or serial device drivers.
..\TOOLAD\SAM_COMN		Console and sample program O/S interface. Not needed if you have created your own equivalents.

 
Link options must also be entered. From the table above, determine which KwikNet runtime libraries your application will require and specify the library names in the Additional options field. All KwikNet sample programs are designed to execute from SDRAM. Define linker symbol USE_SDRAM, as shown, to permit the Link Discription File to locate code and data in SDRAM. You may also wish to enable the Generate symbol map option to aid in the positioning and sizing of memory sections. Note that the L1 Memory Usage has been configured for Cache.

 

 

 

To guard against the possibility of invalid address faults caused by speculative load execution, set the CSYNC compiler option as shown below.

 

Set the maximum number of running threads to a value that is reasonable for your application. Specify the predefined thread types required by KwikNet and create a boot thread as shown below.

 

Set the maximum number of active semaphores to values that are reasonable for your application. KwikNet requires, at most, three semaphores for its own use plus one semaphore for every application task that can be blocked waiting for access to or service by KwikNet. Set all other VDK system parameters to values that are reasonable for your application.

Note that the Tick Period is set to 1 ms. This period should be adequate for most systems without too much burden imposed by servicing clock interrupts. If you set the tick period to a value other than 1 ms, you must modify the definition of symbol CLKFREQ in file KN_OSIF.C and rebuild your KwikNet Library.

 

At this point, you may add other VDK objects needed for your application. Once your VDK setup is complete, you must force an update of the VDK kernel source by right-clicking on Kernel in the Project pane and selecting Update Kernel Source from the pop-up menu, as shown below. Your VDK edits will be saved in file VDK.H. Remember that file VDK.H must be copied to directory C:\TRECK\INCLUDE prior to building the KwikNet Library.

 

Add the necessary KwikNet source files (or your equivalents) to the project as shown below. Replace file ExceptionHandler-BF537.asm generated by VisualDSP++ with the KwikNet equivalent KNBF5XX.ASM. Note that Link Description File VDK-BF537.ldf and all of the Kernel Files are created automatically by VisualDSP++.

 

 

When you create a project from scratch, the VisualDSP++ IDDE will select one of the default Link Description Files from directory BLACKFIN\LDF in your VisualDSP++ installation directory. The heap storage provided by the default Link Description Files is not sufficient for the KwikNet sample programs. Use one of the KwikNet sample Link Description Files, like KNSAMPLE.LDF, as a guide.

KwikNet for Blackfin provides function kn_syscall() which permits a function coded in C to execute in supervisor mode in order to perform privileged I/O operations. The function generates a software exception which causes the switch to supervisor mode. The application C function is called with the two parameters provided by the kn_syscall() caller. Function kn_iouart() in module KNBF5XXS.C provides an example of the proper use of function kn_syscall().

If you are not building for an ADSP-BF537 target, edit file C:\KNT743\TOOLAD\KNZZZCC.INC. Change all the -proc ADSP-BF537 compiler options to match your processor.

In preparation for building the KwikNet Library, copy header file VDK.H from the project directory to directory C:\TRECK\INCLUDE. Make directory C:\KNT743\MAKE the current directory. Run the Microsoft NMAKE utility, or your equivalent, using the KwikNet Network Library Make File generated earlier. Define symbols TOOLSET and KPF to identify the Analog Devices toolset mnemonic (AD) and provide the path to the KwikNet Network Parameter File.

          NMAKE /f..\toolad\sam_tcp\knsamlib.mak TOOLSET=AD TRKPATH=C:\treck
                   KPF=..\toolad\sam_tcp\knsamlib.up
        

When generating the library for the KwikNet TCP/IP Sample Program, KwikNet Library KN743IP.DLB will be produced in directory C:\KNT743\TOOLAD\LIB.

Finally, build your application as described in the section titled Building the KwikNet Sample Program.