os/boardsupport/emulator/emulatorbsp/documentation/wins_ether_drv_howto.txt
changeset 0 bde4ae8d615e
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/boardsupport/emulator/emulatorbsp/documentation/wins_ether_drv_howto.txt	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,193 @@
     1.4 +/*
     1.5 +* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
     1.6 +* All rights reserved.
     1.7 +* This component and the accompanying materials are made available
     1.8 +* under the terms of "Eclipse Public License v1.0"
     1.9 +* which accompanies this distribution, and is available
    1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.11 +*
    1.12 +* Initial Contributors:
    1.13 +* Nokia Corporation - initial contribution.
    1.14 +*
    1.15 +* Contributors:
    1.16 +*
    1.17 +* Description:
    1.18 +*
    1.19 +*/
    1.20 +HOWTO for Wins Ethernet Driver
    1.21 +
    1.22 +0. Pre-requisities
    1.23 +The implementation of Wins Ethernet driver makes use of packet capturing library: 
    1.24 +WinPcap, Release 2.2. This software sets the network card of the PC, on which Epoc 
    1.25 +Emulator is working, into so called promiscuous mode. The user must be confident that 
    1.26 +the environment she/he works in doesn’t forbid such settings. The quickest way 
    1.27 +to ensure about it is to contact network administrator.
    1.28 +
    1.29 +
    1.30 +1. Trouble Shooting
    1.31 +The following problems may occur when attempting to use WINS version of Ethernet driver:
    1.32 +* Network application doesn’t send nor receive any packets: two potential reasons:
    1.33 +  - bad settings in CommDB - refer to point 4
    1.34 +  - Wpcap not installed - refer to point 2
    1.35 +
    1.36 +* A panic is raised of category: 'D32ETHER' with one of the following reasons:
    1.37 +   1	meaning: bad MAC address in ini file or entry for it missing or ini file missing
    1.38 +   2	meaning: entry for network interface name missing in ini file or ini file missing
    1.39 +   3	meaning: Wpcap couldn't be initialised - potentially not installed or name 
    1.40 +	of network interface in .ini file wrong
    1.41 +Panics occur if system is not configured properly, remedy can be found in notes below.
    1.42 +
    1.43 +* Wpcap error may occur - refer to http://winpcap.polito.it/misc/changelog.htm 
    1.44 +  for advice how to fix the problem (this will require usually upgrading WinPcap 
    1.45 +  package on user'’ machine).
    1.46 +
    1.47 +
    1.48 +2. Wpcap
    1.49 +Wpcap must be installed on a machine that wishes to use driver. Installation is simple: 
    1.50 +WinPcap.exe (located in: \epoc32\tools)
    1.51 +should be run and then instructions should be followed. 
    1.52 +If user has already Wpcap installed on his workstation then should try to use 
    1.53 +Ethernet driver with this version. In case when it fails he must uninstall existing 
    1.54 +Wpcap and install the one from Epoc directory mentioned above.
    1.55 +
    1.56 +
    1.57 +3. Netcards
    1.58 +When Wpcap is already installed, a program called Netcards.exe should be run. 
    1.59 +It can be found in \epoc32\tools. 
    1.60 +(Note: Netcards uses Wpcap so the latter must be installed first). 
    1.61 +It will request user to select network card. Netcards writes a few entries 
    1.62 +into \epoc32\data\ethernet.ini file which are read by Epoc Emulator at startup 
    1.63 +(ensure that \epoc32\data directory exists). In particular MAC address value for use 
    1.64 +by Emulator is determined by the entry named 'ETHER_MAC' (it is recommended that 
    1.65 +network administrator was aware of the value of MAC address written there and authorise 
    1.66 +it if necessary; according to local conditions any other value preferred 
    1.67 +by administrator can be written manually instead of the value written by Netcards). 
    1.68 +Ethernet driver for WINS was originally 
    1.69 +designed for use in Techview environment which uses ethernet.ini file. Other environments 
    1.70 +(like Quartz) may use different .ini file (e.g. \epoc32\data\quartz.ini). A user can 
    1.71 +still run Ethernet module in these environments provided that .ini files appropriate 
    1.72 +for these environments contain entries written by netcards.exe to ethernet.ini - user can 
    1.73 +simply copy them - they are easy to recognise as they begin with ‘ETHER_‘ prefix .
    1.74 +
    1.75 +
    1.76 +4. CommDB
    1.77 +CommDB settings should indicate use of the NIF: ethint.nif and the agent: nullagt.agt. 
    1.78 +In current release of Epoc Networking software, data in the database are written by program 
    1.79 +called ced.exe, which takes wanted settings from text file: ced.cfg.
    1.80 +Example settings to be put in this file are shown below. In the example it is assumed 
    1.81 +that IP address and network mask will be acquired by DHCP protocol:
    1.82 +
    1.83 +############################################################
    1.84 +## LANBearer
    1.85 +## 
    1.86 +[LANBearer]
    1.87 +ADD_SECTION
    1.88 +# COMMDB_ID = 1
    1.89 +	Name=Wins Ethernet
    1.90 +	Agent=nullagt.agt
    1.91 +	IfName=ethint
    1.92 +	LDDFilename=enet
    1.93 +	LDDName=Ethernet
    1.94 +	PDDFilename=ethernet
    1.95 +	PDDName=Ethernet.Wins
    1.96 +	PacketDriverName=EtherPkt.drv
    1.97 +	LastSocketActivityTimeout=-1
    1.98 +	LastSessionClosedTimeout=-1
    1.99 +	LastSocketClosedTimeout=-1
   1.100 +	FIELD_COUNT=8
   1.101 +END_ADD
   1.102 +
   1.103 +ADD_SECTION
   1.104 +# COMMDB_ID = 2
   1.105 +	Name=Assabet on-board Ethernet
   1.106 +	Agent=nullagt.agt
   1.107 +	IfName=ethint
   1.108 +	LDDFilename=enet
   1.109 +	LDDName=Ethernet
   1.110 +	PDDFilename=ethernet
   1.111 +	PDDName=Ethernet.Assabet
   1.112 +	PacketDriverName=EtherPkt.drv
   1.113 +	LastSocketActivityTimeout=-1
   1.114 +	LastSessionClosedTimeout=-1
   1.115 +	LastSocketClosedTimeout=-1
   1.116 +	FIELD_COUNT=8
   1.117 +END_ADD
   1.118 +
   1.119 +############################################################
   1.120 +## LANService
   1.121 +## 
   1.122 +[LANService]
   1.123 +
   1.124 +ADD_SECTION
   1.125 +# COMMDB_ID = 1
   1.126 +	Name=Ethernet
   1.127 +	#IfNetworks=ip,ip6
   1.128 +	IfNetworks=ip
   1.129 +	IpNetMask=0.0.0.0
   1.130 +	IpGateway=0.0.0.0
   1.131 +	IpAddrFromServer=TRUE
   1.132 +	IpAddr=0.0.0.0
   1.133 +	IpDNSAddrFromServer=TRUE
   1.134 +	IpNameServer1=0.0.0.0
   1.135 +	IpNameServer2=0.0.0.0
   1.136 +	FIELD_COUNT=9
   1.137 +END_ADD
   1.138 +
   1.139 +
   1.140 +############################################################
   1.141 +## IAP
   1.142 +## 
   1.143 +[IAP]
   1.144 +ADD_SECTION
   1.145 +# COMMDB_ID = 1
   1.146 +	Name=Ethernet IAP
   1.147 +	IAPService=1
   1.148 +	IAPServiceType=LANService
   1.149 +	IAPBearer=1
   1.150 +	IAPBearerType=LANBearer
   1.151 +	IAPNetwork=1
   1.152 +	IAPNetworkWeighting=0
   1.153 +	Location=2
   1.154 +	FIELD_COUNT=8
   1.155 +END_ADD
   1.156 +
   1.157 +ADD_SECTION
   1.158 +# COMMDB_ID = 2
   1.159 +	Name=NT RAS with Null Modem
   1.160 +	IAPService=2
   1.161 +	IAPServiceType=DialOutISP
   1.162 +	IAPBearer=2
   1.163 +	IAPBearerType=ModemBearer
   1.164 +	IAPNetwork=1
   1.165 +	IAPNetworkWeighting=0
   1.166 +	Location=2
   1.167 +	FIELD_COUNT=8
   1.168 +END_ADD
   1.169 +
   1.170 +############################################################
   1.171 +## ConnectionPreferences
   1.172 +## 
   1.173 +[ConnectionPreferences]
   1.174 +
   1.175 +
   1.176 +ADD_SECTION
   1.177 +	Ranking=0
   1.178 +	Direction=OUTGOING
   1.179 +	DialogPref=PROMPT
   1.180 +	BearerSet=LAN
   1.181 +	#IAP=Ethernet IAP
   1.182 +	IAP=1
   1.183 +	FIELD_COUNT=5
   1.184 +END_ADD
   1.185 +
   1.186 +ADD_SECTION
   1.187 +	Ranking=1
   1.188 +	Direction=OUTGOING
   1.189 +	DialogPref=DONOTPROMPT
   1.190 +	BearerSet=LAN
   1.191 +#IAP=Ethernet IAP
   1.192 +	IAP=1
   1.193 +	FIELD_COUNT=5
   1.194 +END_ADD
   1.195 +
   1.196 +