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