begriffs open source - cmsis-driver-validation/blob

1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

2 /**

3 \defgroup wifi_requirements Requirements

4 \ingroup dv_wifi

5

6 The WiFi driver validation requires the following hardware:

7 - WiFi Access Point connected to the local network

8 - Hardware running SockServer (can be \ref sockserver_pc "PC running Microsoft Windows" or an

9 \ref sockserver_embedded "embedded system")

10

11 The WiFi driver validation requires the following software:

12 - \ref wifi_sock_setup "SockServer" application running in the same network as WiFi Access Point used for testing

13 */

14

15

16 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

17 /**

18 \defgroup wifi_config Configuration

19 \ingroup dv_wifi

20

21 The WiFi driver validation settings are available in the DV_WiFi_Config.h configuration file.

22

23 Some settings depend on the test environment and need to be changed for proper operation of the WiFi driver validation.

24 These settings can be found under Configuration settings in the DV_WiFi_Config.h configuration file and need to

25 be set as follows:

26

27 \image html dv_wifi_config_h.png "DV_WiFi_Config.h configuration file in Configuration Wizard view mode"

28

29 Station related settings needed for WiFi module to connect to the WiFi Access Point in the local network:

30 - SSID

31 - Password

32 - Security Type

33 - Channel: use 0 for auto-detect channel

34 - WPS PIN: PIN used for WPS tests (the Access Point has to have the same PIN enabled and WPS service running)

35

36 Access Point related settings needed for testing Access Point functionality (network creation) of the WiFi module:

37 - SSID

38 - Password

39 - Security Type

40 - Channel: use 0 for auto-detect channel

41 - WPS PIN: PIN used for WPS tests (auxiliary station has to have the same PIN enabled)

42

43 Socket related setting needed for Socket API and Socket Operation tests:

44 - SockServer IP: IP address assigned to the SockServer on your local network

45 - Number of sockets: Number of sockets that the driver supports and that will be tested

46

47 \note IP address is displayed by the SockServer application (on the embedded board's LCD when using embedded SockServer).

48

49 Under Tests select testing functionality as required.

50 For details on tests performed by each test function please refer to \ref wifi_tests "WiFi Tests".

51

52 Control, Management and Socket API (requires SockServer) group of tests enable or disable

53 WiFi Driver API function tests respectively.

54

55 Management (requires user interaction) and Socket Operation (requires SockServer) group of tests

56 are used for more complex operational test of the WiFi driver.

57 A brief description of each test functionality can be viewed by using

58 <a href="https://developer.arm.com/documentation/101407/0537/Utilities/Configuration-Wizard" target="_blank">Configuration Wizard</a>

59 view of the DV_WiFi_Config.h file and clicking on the test or hovering a mouse pointer over it.

60

61 */

62

63

64 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

65 /**

66 \defgroup wifi_sock_setup SockServer

67 \ingroup dv_wifi

68

69 The \b SockServer is an application providing a set of services used by the WiFi CMSIS-Driver Validation suite to test the

70 Socket interface of the WiFi driver. It is located in the .\\Tools\\SockServer subdirectory of the pack root directory.

71 The SockServer is available for different target systems. It runs several standard network services.

72

73 The SockServer is available for following target systems:

74 - Personal Computer running Microsoft Windows (executable located in .\\Tools\\SockServer\\PC\\Win)

75 - Keil MCB4300 evaluation board (µVision project located in .\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCB4300)

76 - Keil MCBSTM32F400 evaluation board (µVision project located in .\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCBSTM32F400)

77

78 \note To run SockServer in an embedded system, you need a license for MDK-Professional (for the MDK-Middleware Network component).

79

80 The following services are available by SockServer:

81 - \b Echo service on port \token{7}, TCP and UDP

82 \n (two instances of TCP service, one instance of UDP service)

83 - \b Discard service on port \token{9}, TCP and UDP

84 \n (one instance of TCP service, one instance of UDP service)

85 - \b Chargen service on port \token{19}, TCP and UDP

86 \n (two instances of TCP service, one instance of UDP service)

87 - \b Assistant service on port \token{5000}

88 \n (helper service used to test WiFi sockets in server mode (socket accept functionality))

89 - \b Telnet service on port \token{23}

90 \n (SockServer status monitoring service)

91

92 \note SockServer provides the Telnet service only in embedded systems.

93

94 \section sockserver_pc SockServer for PC running Microsoft Windows

95

96 \b Requirements:

97 - Personal Computer running Microsoft Windows

98 - PC connection to local network

99

100 SockServer is already built and can be executed by running the SockServer.exe file in .\\Tools\\SockServer\\PC\\Win

101

102 If you need to change the functionality of SockServer, source files and a batch script for building the executable are

103 available in .\\Tools\\SockServer\\PC\\Win.

104

105 \note

106 - SockServer build process requires Minimalist GNU for Windows (MinGW).

107 - To build the SockServer executable for Windows, follow these steps:

108 - Download and install MinGW from https://osdn.net/projects/mingw/releases/

109 - Set environment path in Microsoft Windows as explained under Environment Settings heading on http://www.mingw.org/wiki/Getting_Started

110 - Run Build.bat located in .\\Tools\\SockServer\\PC\\Win which will result in an executable that is located in

111 .\\Tools\\SockServer\\PC\\Win

112

113 \subsection sockserver_pc_win_troubleshooting Troubleshooting

114

115 Problems and solutions:

116 1. SockServer not responding to requests

117 - Open Windows firewall -> Advanced settings

118 - select inbound rules

119 - create a new custom rule (New Rule...)

120 - Rule type: Program

121 - Program: This program path (select path to SockServer.exe)

122 - Action: Allow the connection

123 - Profile: Domain, Private (Public not advised)

124 - Name: SockServer

125 2. Test computer not responding to ping

126 - Open Windows firewall -> Advanced settings

127 - select inbound rules, enable rule

128 File and Printer sharing (Echo request - ICMPv4-In)

129

130 - If rule does not exist, create a new custom rule (New Rule...)

131 - Rule type: Custom

132 - Program: All programs

133 - Protocol type: ICMPv4

134 - ICMP Settings: Customize - Specific ICMP types: Echo Request

135 - Scope: Any IP address

136 - Action: Allow the connection

137 - Profile: Domain, Private (Public not advised)

138 - Name: Ping Echo

139

140

141 \section sockserver_embedded SockServer for embedded systems

142

143 \b Requirements:

144 - Keil MCB4300 or Keil MCBSTM32F400 evaluation board

145 - Wired Ethernet connection to local network

146

147 \subsection sockserver_embedded_telnet Using the Telnet service

148

149 The Telnet service provides information about received and sent data. This can help to resolve driver problems when WiFi

150 socket sending and receiving does not work. For example, when the transfer test fails, either \b SocketSend or

151 \b SocketRecv functions may have failed or both.

152

153 For the Telnet connection from the PC, open a CMD window. At the prompt, type the following command or use another Telnet

154 client application:

155 \code

156 c:\>telnet sockserver

157 \endcode

158

159 The initial page opens:

160 \image html SockServer.png "Initial telnet connection"

161

162 You can view the remote IP address, port number, receiving and transmitting counters with the \b stat command:

163 \image html SockMonitor.png "Status monitoring"

164

165 Status monitor constantly updates the SockServer status on the screen. To stop the screen update, press any

166 telnet client key.

167

168 \note You might need to enable the Telnet service in Windows 10 first. Here's a

169 <a href="https://www.technipages.com/windows-10-enable-telnet" target="_blank">tutorial</a> on how to do this.

170

171 \subsection sockserver_embedded_porting Porting SockServer to other targets

172

173 Currently, the \b SockServer application is available for the \b MCB4300 and \b MCBSTM32F400 evaluation boards.

174 To create SockServer application for a different target device, follow the steps below:

175 -# Create new network project in µVision

176 -# Select and configure the following software components:

177 - \b Network:Core and configure the host name and pool size in \b Net_Config.c

178 \code

179 #define NET_HOST_NAME "SockServer"

180 #define NET_MEM_POOL_SIZE 16384

181 \endcode

182 - \b Network:Interface:Ethernet and configure the MAC address in \b Net_Config_ETH0.h to avoid collisions

183 \code

184 #define ETH0_MAC_ADDR "1E-30-6C-A2-45-5A"

185 \endcode

186 - \b Network:Socket:BSD and configure number of sockets in \b Net_Config_BSD.h

187 \code

188 #define BSD_NUM_SOCKS 8

189 #define BSD_SERVER_SOCKS 4

190 \endcode

191 - \b Network:Socket:TCP and configure number of sockets in \b Net_Config_TCP.h

192 \code

193 #define TCP_NUM_SOCKS 9

194 \endcode

195 - \b Network:Socket:UDP and configure number of sockets in \b Net_Config_UDP.h

196 \code

197 #define UDP_NUM_SOCKS 10

198 \endcode

199 - \b Network:Service:Telnet server and disable authentication in \b Net_Config_Telnet_Server.h

200 \code

201 #define TELNET_SERVER_AUTH_ENABLE 0

202 \endcode

203 - \b CMSIS \b Driver:Ethernet/MAC/PHY(API) depending on your hardware

204 -# Configure device specific hardware:

205 - Configure the CMSIS-Driver for Ethernet and other device specific components (clock system, I/O, ...)

206 as required. Please consult your device's/board's documentation for more information.

207 -# Copy and add \b SockServer.c and \b SockServer.h files to the project

208 -# Copy and add \b Telnet_Server_UIF.c to the project

209 -# Add the code to start the services in \b main.c

210 \code

211 // Application main thread

212 static void app_main (void *argument) {

213

214 netInitialize ();

215 osDelay (500);

216

217 osThreadNew(DgramServer, NULL, NULL);

218 osThreadNew(StreamServer, NULL, NULL);

219 osThreadNew(TestAssistant, NULL, NULL);

220 }

221 \endcode

222 -# Increase the default RTX stack size to 400 bytes in RTX_Config.h

223 \code

224 #define OS_STACK_SIZE 400

225 \endcode

226 -# Set the default global stack to 1024 bytes and heap to 6144 bytes in your device's \b startup \b file

227 \code

228 Stack_Size EQU 0x00000400

229 Heap_Size EQU 0x00001800

230 \endcode

231

232 \subsection sockserver_embedded_troubleshooting Troubleshooting

233

234 Problems and solutions:

235 1. SockServer on multiple embedded systems on the same local network

236 - Set unique ETH0_MAC_ADDR in Net_Config_ETH0.h for each embedded system in embedded system project

237

238 */

239

240 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

241 /**

242 \defgroup wifi_sock_testing Socket testing

243 \ingroup dv_wifi

244

245 Due to limitations of WiFi modules and their Software Development Kits (SDK), often it is not possible to comply with

246 CMSIS-Driver BSD rules regarding function behavior or function return codes. Hence, the WiFi Driver tests accept alternative

247 error codes and report them as Warnings and considers certain error codes as acceptable for certain functions.

248 Exceptions to BSD-strict error codes and functionality are written below:

249

250 WiFi socket deviations from the BSD-strict specification

251 ========================================================

252

253 -# \b SocketBind

254 - bind socket to same address again

255 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

256

257 - bind another socket to used address

258 BSD-strict expected return code \b ARM_SOCKET_EADDRINUSE non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

259

260 - bind on closed socket

261 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

262

263 -# \b SocketListen

264 - listen on already listening socket

265 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

266

267 - listen on unbound socket

268 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

269

270 - listen on closed socket

271 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

272

273 - listen on datagram socket

274 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

275

276 -# \b SocketAccept

277 - receive on disconnected socket

278 BSD-strict expected return code \b ARM_SOCKET_ECONNRESET non BSD-strict accepted return codes: \token{ARM_SOCKET_EAGAIN} or \token{ARM_SOCKET_ERROR}

279

280 - accept on closed socket

281 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

282

283 - listen on datagram socket

284 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

285

286 - accept on datagram socket

287 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

288

289 -# \b SocketConnect

290 - connect socket to same address again

291 BSD-strict expected return code \b ARM_SOCKET_EISCONN non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

292

293 - bind on connected socket

294 BSD-strict expected return code \b ARM_SOCKET_EISCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

295

296 - connect on closed socket

297 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

298

299 - connect to non-existent port

300 BSD-strict expected return code \b ARM_SOCKET_ECONNREFUSED non BSD-strict accepted return codes: \token{ARM_SOCKET_ETIMEDOUT} or \token{ARM_SOCKET_ERROR}

301

302 - connect to non-existent stream server

303 BSD-strict expected return code \b ARM_SOCKET_ETIMEDOUT non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

304

305 - connect on listening socket

306 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

307

308 - connect datagram socket to unspecified address (0.0.0.0)

309 BSD-strict expected return code \b 0 non BSD-strict accepted return codes: \token{ARM_SOCKET_EINVAL} or \token{ARM_SOCKET_ERROR}

310 (special case that deletes the socket destination & filtering address)

311

312 -# \b SocketRecv

313 - recv on closed socket

314 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

315

316 - recv on created socket

317 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

318

319 - recv on bound socket

320 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

321

322 - recv on listening socket

323 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

324

325 -# \b SocketRecvFrom

326 - recvfrom on closed socket

327 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

328

329 -# \b SocketSend

330 - send on closed socket

331 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

332

333 - send on disconnected socket

334 BSD-strict expected return code \b ARM_SOCKET_ECONNRESET non BSD-strict accepted return codes: >\token{0} or \token{ARM_SOCKET_EAGAIN} or \token{ARM_SOCKET_ERROR}

335

336 - send on created socket

337 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

338

339 - send on bound socket

340 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

341

342 - send on listening socket

343 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

344

345 - send on closed socket

346 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

347

348 -# \b SocketSendTo

349 - sendto on closed socket

350 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

351

352 -# \b SocketGetSockName

353 - getsockname on closed socket

354 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

355

356 - getsockname on unbound socket

357 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

358

359 -# \b SocketGetPeerName

360 - getpeername on closed socket

361 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

362

363 - getpeername on created socket

364 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

365

366 - getpeername on bound socket

367 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

368

369 - getpeername on listening socket

370 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

371

372 -# \b SocketGetOpt

373 - getsockopt on closed socket

374 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

375

376 -# \b SocketSetOpt

377 - setsockopt on closed socket

378 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

379

380 -# \b SocketClose

381 - close already closed socket

382 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{0}

383

384 -# \b SocketGetHostByName

385 - gethostbyname for non-existing host

386 BSD-strict expected return code \b ARM_SOCKET_EHOSTNOTFOUND non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

387 */