os/boardsupport/emulator/emulatorbsp/documentation/wins_ether_drv_howto.txt
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
     1 /*
     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:
    15 *
    16 */
    17 HOWTO for Wins Ethernet Driver
    18 
    19 0. Pre-requisities
    20 The implementation of Wins Ethernet driver makes use of packet capturing library: 
    21 WinPcap, Release 2.2. This software sets the network card of the PC, on which Epoc 
    22 Emulator is working, into so called promiscuous mode. The user must be confident that 
    23 the environment she/he works in doesn’t forbid such settings. The quickest way 
    24 to ensure about it is to contact network administrator.
    25 
    26 
    27 1. Trouble Shooting
    28 The following problems may occur when attempting to use WINS version of Ethernet driver:
    29 * Network application doesn’t send nor receive any packets: two potential reasons:
    30   - bad settings in CommDB - refer to point 4
    31   - Wpcap not installed - refer to point 2
    32 
    33 * A panic is raised of category: 'D32ETHER' with one of the following reasons:
    34    1	meaning: bad MAC address in ini file or entry for it missing or ini file missing
    35    2	meaning: entry for network interface name missing in ini file or ini file missing
    36    3	meaning: Wpcap couldn't be initialised - potentially not installed or name 
    37 	of network interface in .ini file wrong
    38 Panics occur if system is not configured properly, remedy can be found in notes below.
    39 
    40 * Wpcap error may occur - refer to http://winpcap.polito.it/misc/changelog.htm 
    41   for advice how to fix the problem (this will require usually upgrading WinPcap 
    42   package on user'’ machine).
    43 
    44 
    45 2. Wpcap
    46 Wpcap must be installed on a machine that wishes to use driver. Installation is simple: 
    47 WinPcap.exe (located in: \epoc32\tools)
    48 should be run and then instructions should be followed. 
    49 If user has already Wpcap installed on his workstation then should try to use 
    50 Ethernet driver with this version. In case when it fails he must uninstall existing 
    51 Wpcap and install the one from Epoc directory mentioned above.
    52 
    53 
    54 3. Netcards
    55 When Wpcap is already installed, a program called Netcards.exe should be run. 
    56 It can be found in \epoc32\tools. 
    57 (Note: Netcards uses Wpcap so the latter must be installed first). 
    58 It will request user to select network card. Netcards writes a few entries 
    59 into \epoc32\data\ethernet.ini file which are read by Epoc Emulator at startup 
    60 (ensure that \epoc32\data directory exists). In particular MAC address value for use 
    61 by Emulator is determined by the entry named 'ETHER_MAC' (it is recommended that 
    62 network administrator was aware of the value of MAC address written there and authorise 
    63 it if necessary; according to local conditions any other value preferred 
    64 by administrator can be written manually instead of the value written by Netcards). 
    65 Ethernet driver for WINS was originally 
    66 designed for use in Techview environment which uses ethernet.ini file. Other environments 
    67 (like Quartz) may use different .ini file (e.g. \epoc32\data\quartz.ini). A user can 
    68 still run Ethernet module in these environments provided that .ini files appropriate 
    69 for these environments contain entries written by netcards.exe to ethernet.ini - user can 
    70 simply copy them - they are easy to recognise as they begin with ‘ETHER_‘ prefix .
    71 
    72 
    73 4. CommDB
    74 CommDB settings should indicate use of the NIF: ethint.nif and the agent: nullagt.agt. 
    75 In current release of Epoc Networking software, data in the database are written by program 
    76 called ced.exe, which takes wanted settings from text file: ced.cfg.
    77 Example settings to be put in this file are shown below. In the example it is assumed 
    78 that IP address and network mask will be acquired by DHCP protocol:
    79 
    80 ############################################################
    81 ## LANBearer
    82 ## 
    83 [LANBearer]
    84 ADD_SECTION
    85 # COMMDB_ID = 1
    86 	Name=Wins Ethernet
    87 	Agent=nullagt.agt
    88 	IfName=ethint
    89 	LDDFilename=enet
    90 	LDDName=Ethernet
    91 	PDDFilename=ethernet
    92 	PDDName=Ethernet.Wins
    93 	PacketDriverName=EtherPkt.drv
    94 	LastSocketActivityTimeout=-1
    95 	LastSessionClosedTimeout=-1
    96 	LastSocketClosedTimeout=-1
    97 	FIELD_COUNT=8
    98 END_ADD
    99 
   100 ADD_SECTION
   101 # COMMDB_ID = 2
   102 	Name=Assabet on-board Ethernet
   103 	Agent=nullagt.agt
   104 	IfName=ethint
   105 	LDDFilename=enet
   106 	LDDName=Ethernet
   107 	PDDFilename=ethernet
   108 	PDDName=Ethernet.Assabet
   109 	PacketDriverName=EtherPkt.drv
   110 	LastSocketActivityTimeout=-1
   111 	LastSessionClosedTimeout=-1
   112 	LastSocketClosedTimeout=-1
   113 	FIELD_COUNT=8
   114 END_ADD
   115 
   116 ############################################################
   117 ## LANService
   118 ## 
   119 [LANService]
   120 
   121 ADD_SECTION
   122 # COMMDB_ID = 1
   123 	Name=Ethernet
   124 	#IfNetworks=ip,ip6
   125 	IfNetworks=ip
   126 	IpNetMask=0.0.0.0
   127 	IpGateway=0.0.0.0
   128 	IpAddrFromServer=TRUE
   129 	IpAddr=0.0.0.0
   130 	IpDNSAddrFromServer=TRUE
   131 	IpNameServer1=0.0.0.0
   132 	IpNameServer2=0.0.0.0
   133 	FIELD_COUNT=9
   134 END_ADD
   135 
   136 
   137 ############################################################
   138 ## IAP
   139 ## 
   140 [IAP]
   141 ADD_SECTION
   142 # COMMDB_ID = 1
   143 	Name=Ethernet IAP
   144 	IAPService=1
   145 	IAPServiceType=LANService
   146 	IAPBearer=1
   147 	IAPBearerType=LANBearer
   148 	IAPNetwork=1
   149 	IAPNetworkWeighting=0
   150 	Location=2
   151 	FIELD_COUNT=8
   152 END_ADD
   153 
   154 ADD_SECTION
   155 # COMMDB_ID = 2
   156 	Name=NT RAS with Null Modem
   157 	IAPService=2
   158 	IAPServiceType=DialOutISP
   159 	IAPBearer=2
   160 	IAPBearerType=ModemBearer
   161 	IAPNetwork=1
   162 	IAPNetworkWeighting=0
   163 	Location=2
   164 	FIELD_COUNT=8
   165 END_ADD
   166 
   167 ############################################################
   168 ## ConnectionPreferences
   169 ## 
   170 [ConnectionPreferences]
   171 
   172 
   173 ADD_SECTION
   174 	Ranking=0
   175 	Direction=OUTGOING
   176 	DialogPref=PROMPT
   177 	BearerSet=LAN
   178 	#IAP=Ethernet IAP
   179 	IAP=1
   180 	FIELD_COUNT=5
   181 END_ADD
   182 
   183 ADD_SECTION
   184 	Ranking=1
   185 	Direction=OUTGOING
   186 	DialogPref=DONOTPROMPT
   187 	BearerSet=LAN
   188 #IAP=Ethernet IAP
   189 	IAP=1
   190 	FIELD_COUNT=5
   191 END_ADD
   192 
   193