begriffs open source - cmsis-driver-validation/blob

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

2 /**

3 \defgroup spi_config Configuration

4 \ingroup dv_spi

5

6 The SPI driver validation settings are available in the DV_SPI_Config.h configuration file.

7

8 \image html dv_spi_config_h.png "DV_SPI_Config.h configuration file in Configuration Wizard view mode"

9

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

11

12 \section spi_config_detail Configuration settings

13

14 Driver_SPI# selects the driver instance that will be tested.

15 For example if we want to test <c>Driver_SPI2</c> then this setting would be set to <c>2</c>.

16

17 Configuration section contains configuration of: Test Mode, SPI Server and Tests settings:

18 - Test Mode can be set to Loopback or SPI Server.

19 Loopback mode should be used for initial validation.

20 Loopback mode requires that MOSI and MISO pins are connected together thus driver validation can test basic

21 functionality in the Master mode.

22 For full compliance of the SPI driver with the CMSIS-Driver SPI specification the SPI Server Test Mode has to be used.

23 - SPI Server settings are relevant if Test Mode: SPI Server is selected.

24 These settings specify communication settings at which Driver Validation communicates with the SPI Server

25 and must be same as configured on the SPI Server.

26 - Some settings are fixed and cannot be changed, these are the following ones:

27 - Clock / Frame Format: Clock Polarity 0/ Clock Phase 0

28 - Data Bits: 8

29 - Bit Order: MSB to LSB

30 - Settings configurable for the SPI Server are:

31 - Slave Select setting specifies the way that Slave Select line will be handled by the driver under test.

32 SPI Server requires that commands are exchanged with Slave Select line used, so driver being tested must support

33 Slave Select line handling.

34 Software Controlled selection means that driver will use software controlled driving of the Slave Select line by

35 calling driver <c>Control</c> function with <c>ARM_SPI_CONTROL_SS</c> control code to activate Slave Select Line

36 before the transfer and deactivate it after the transfer.

37 Hardware Controlled selection means that driver will use hardware controlled driving of the Slave Select line.

38 - Bus Speed setting specifies the nominal bus speed used to exchange commands with the SPI Server.

39 This setting should be set to a speed guaranteeing reliable command exchange with the SPI Server.

40 - Tests settings specify tests configuration:

41 - Default settings specifies the default settings used in the data exchange tests.

42 Usually, one feature is tested by executing the data exchange while all other parameters are used as default.

43 For details on which parameters are used as default in each test function please refer to \ref spi_tests_data_xchg

44 functions documentation.

45 - Bus Speed settings specifies minimum and maximum bus speeds at which data transfer will be executed.

46 These settings are used by the \ref SPI_Bus_Speed_Min and \ref SPI_Bus_Speed_Max test functions.

47 - Number of Items settings specifies a few different number of items to be tested.

48 These settings are used by the \ref SPI_Number_Of_Items test function which tests that odd and unusual number of items

49 are transferred correctly according to the CMSIS-Driver specification.

50

51 Tests section contains selection of tests to be executed:

52 - Driver Management allows enabling or disabling of the whole driver management group of test functions.

53 Each test function in this group can be enabled or disabled individually, for details on tests performed

54 by each test function please refer to \ref spi_tests_drv_mgmt documentation.

55 - Data Exchange allows enabling or disabling of the whole data exchange group of test functions.

56 Each test function in this group can be enabled or disabled individually, for details on tests performed

57 by each test function please refer to \ref spi_tests_data_xchg documentation.

58 - Event allows enabling or disabling of the whole event group of test functions.

59 Each test function in this group can be enabled or disabled individually, for details on tests performed

60 by each test function please refer to \ref spi_tests_evt documentation.

61 */

62

63

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

65 /**

66 \defgroup spi_server SPI Server

67 \ingroup dv_spi

68

69 The SPI Server is an application providing a set of features used by the CMSIS-Driver Validation suite to test the

70 physical operation of the SPI driver.

71 It is located in the <c>\<pack root directory\></c>\\Tools\\SPI_Server directory.

72

73 The SPI Server offers the following features:

74 - read of the version information

75 - read of the capabilities information

76 - set and read of the data buffers content

77 - read of the last transfer count

78 - transfer in Slave or Master mode

79

80 \section spi_server_oper Operation

81

82 The SPI Server is continuously waiting on a command from the SPI Client (Driver Validation),

83 after the command is received it is executed, and the process repeats.

84 Most commands do not have any additional related data phase, but some do have additional input or output

85 data exchange phase following the command.

86

87 The SPI Server behaves as an SPI Slave except when command for Master transfer was requested, in which case it

88 executes the requested Master transfer and reverts to Slave mode.

89

90 \section spi_server_config Configuration

91

92 Communication interface settings used during command exchange are set in the SPI_Server_Config.h configuration file.

93 \image html spi_server_config_h.png "SPI_Server_Config.h configuration file in Configuration Wizard view mode"

94

95 \subsection spi_server_config_detail Configuration settings

96

97 Driver_SPI# selects the driver instance used by the SPI Server.

98 Communication settings used for command exchange with the SPI Client are fixed to:

99 - Mode: Slave with Slave Select Hardware monitored

100 - Clock / Frame Format: Clock Polarity 0/ Clock Phase 0

101 - Data Bits: 8

102 - Bit Order: MSB to LSB

103

104 \note The SPI Server is receiving commands operating in SPI Slave mode with usage of the Slave Select line

105 \note The SPI driver used by the SPI Server must support Hardware monitored Slave Select functionality

106

107 \section spi_server_commands Commands

108

109 Commands are encoded in human readable format (ASCII strings) so they can be viewed by the SPI bus analyzer

110 and analyzed more easily.

111

112 Supported commands:

113 - GET VER: used to retrieve version of the SPI Server application

114 - GET CAP: used to retrieve capabilities of the SPI Server

115 (the Server auto-detects capabilities upon reception of this command)

116 - SET BUF: used to initialize receive or transmit buffer content of the SPI Server

117 - GET BUF: used to retrieve receive or transmit buffer content of the SPI Server

118 - SET COM: used to specify transfer configuration for the next transfer

119 - XFER: used to trigger a transfer

120 - GET CNT: used to retrieve number of transferred items in the last transfer

121

122 \note For details about commands please refer to Abstract.txt file in the

123 <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Board\\MCBSTM32F400 directory.

124

125 Picture below shows a capture of SPI Driver Validation validating functionality of the Master transfer with Slave Select

126 line not used \image html spi_bus_master_ss_hw_ctrl_out.png

127

128 \section spi_server_porting Porting SPI Server to other targets

129

130 To create SPI Server application for a different target device, follow the steps below:

131 -# Create a new project in µVision for your target device

132 -# In the RTE window enable and configure the following software components:

133 - CMSIS: CORE

134 - CMSIS: RTOS2 (API): Keil RTX5 any variant

135 - CMSIS Driver: SPI (API)

136 - CMSIS Driver: VIO (API) select Virtual implementation if implementation for your target system is not available

137 - Generic device specific components (startup, clock system, I/O, ...) as required

138 (please consult device's documentation for more information)

139 - Resolve any unresolved dependencies between components

140 -# Copy the SPI_Server.c file from the <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Source directory

141 to the project root and add it to µVision project

142 -# Copy the SPI_Server.h file from the <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Include

143 directory to the project root

144 -# Copy the SPI_Server_Config.h file from the <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Config

145 directory to the project root and adapt this file as required by your device

146 -# Add root of the project to include path (Options for Target -> C/C++ -> Include Paths: .\\)

147 -# Add the main.c file from a template

148 (Right-click Source Group 1... and select Add New Item to Group, select User Code Template and choose the

149 CMSIS-RTOS2 'main' function file from CMSIS: RTOS2:Keil RTX5)

150 and update with code snippet below (replace <c>app_main</c> function):

151 \code

152 #include "SPI_Server.h"

153

154 /*----------------------------------------------------------------------------

155 * Application main thread

156 *---------------------------------------------------------------------------*/

157 __NO_RETURN static void app_main (void *argument) {

158 (void)argument;

159 SPI_Server_Start();

160 for (;;) {}

161 }

162 \endcode

163 -# Ensure that system has at least 10kB of heap available for the transfer buffers

164 (this is usually set in the startup file of the device)

165 -# Build and download the ported SPI Server application to the target device

166

167 \section spi_server_troubleshooting Troubleshooting

168

169 Problems and solutions:

170 1. SPI Server is not responding to commands

171 - reset the SPI Server

172 - check that correct driver instance is selected in the SPI_Server_Config.h file

173 - reduce bus speed used for communication with the SPI Server (in the DV_SPI_Config.h file)

174 2. SPI Server is not responding to commands it reports "Server Start failed!" message

175 if debug variant is used

176 - check heap settings

177 (it has to be larger than 2 * SPI_SERVER_BUF_SIZE specified in the SPI_Server_Config.h file)

178 - check that RTOS allows allocation of at least 512 bytes for the SPI Server main thread

179 (Global Dynamic Memory size [bytes] setting in RTX_Config.h file if RTX5 is used)

180 3. tests report data mismatch

181 - check that Slave Select line has a pull-up to Vcc line

182 - check that wires are separate and short as possible

183 - insure if possible that SCK and GND wires are a twisted pair

184 - insure that SPI driver in inactive mode does not drive Slave Select line

185

186 \section spi_server_MCBSTM32F400 SPI Server on the Keil MCBSTM32F400 board

187

188 µVision project and source files for the MCBSTM32F400 board are available in the <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Board\\MCBSTM32F400 directory.

189

190 On the Keil MCBSTM32F400 board the SPI2 interface is used, with the following pinout:

191

192 | SPI function | Pin |

193 | :------------------------------- | :----: |

194 | SPI Clock | PB10 |

195 | Master Output Slave Input (MOSI) | PB15 |

196 | Master Input Slave Output (MISO) | PB14 |

197 | Slave Select | PI0 |

198

199 \note IMPORTANT: Ground must be connected between SPI Server and Device (Driver) Under Test

200 so that SPI signals have same ground potential.

201

202 For more information please consult Abstract.txt file in the project root.

203

204 \note SPI Server on the Keil MCBSTM32F400 does not support National Semiconductor Microwire Frame Format.

205

206

207 \section spi_server_STM32F429I_DISC1 SPI Server on the STMicroelectronics STM32F429I-DISC1 (32F429IDISCOVERY) board

208

209 µVision project and source files for the STM32F429I-DISC1 board are available in the <c>\<pack root directory\></c>\\Tools\\SPI_Server\\Board\\STM32F429I-DISC1 directory.

210

211 On the STMicroelectronics STM32F429I-DISC1 board the SPI1 interface is used, with the following pinout:

212

213 | SPI function | Pin |

214 | :------------------------------- | :----: |

215 | SPI Clock | PA5 |

216 | Master Output Slave Input (MOSI) | PA7 |

217 | Master Input Slave Output (MISO) | PB4 |

218 | Slave Select | PA15 |

219

220 \note IMPORTANT: Ground must be connected between SPI Server and Device (Driver) Under Test

221 so that SPI signals have same ground potential.

222

223 For more information please consult Abstract.txt file in the project root.

224

225 \note SPI Server on the STMicroelectronics STM32F429I-DISC1 does not support National Semiconductor Microwire Frame Format.

226

227 */