iLLD_TC27xC  1.0
IfxHssl_Hssl.h
Go to the documentation of this file.
1 /**
2  * \file IfxHssl_Hssl.h
3  * \brief HSSL HSSL details
4  * \ingroup IfxLld_Hssl
5  *
6  * \version iLLD_0_1_0_10
7  * \copyright Copyright (c) 2013 Infineon Technologies AG. All rights reserved.
8  *
9  *
10  * IMPORTANT NOTICE
11  *
12  *
13  * Infineon Technologies AG (Infineon) is supplying this file for use
14  * exclusively with Infineon's microcontroller products. This file can be freely
15  * distributed within development tools that are supporting such microcontroller
16  * products.
17  *
18  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
19  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
21  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
22  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
23  *
24  *
25  * \defgroup IfxLld_Hssl_Hssl_Usage How to use the HSSL Interface driver?
26  * \ingroup IfxLld_Hssl
27  *
28  * The HSSL interface driver provides a default HSSL/HSCT configuration for point to point communication at two transfer speeds, 5MBaud (low speed) and 320MBaud (high speed).
29  * It also supports streaming transfers of data a memory block at both low and high speeds.
30  *
31  * In the following sections it will be described, how to integrate the driver into the application framework.
32  *
33  * \section IfxLld_Hssl_Hssl_Preparation Preparation
34  * \subsection IfxLld_Hssl_Hssl_Include Include Files
35  *
36  * Include following header file into your C code:
37  * \code
38  * #include <Hssl/Hssl/IfxHssl_Hssl.h>
39  * \endcode
40  *
41  * \subsection IfxLld_Hssl_Hssl_Variables Variables
42  *
43  * Declare the HSSL handle and channel array as global variables in your C code:
44  *
45  * \code
46  * // used globally
47  * static fxHssl_Hssl hssl;
48  * IfxHssl_Hssl_Channel hsslChannel[4];
49  * __attribute__ ((aligned(256))) uint32 txData[80]; // needs to be declared globally in case of streaming transfers
50  * \endcode
51  *
52  * \subsection IfxLld_Hssl_Hssl_InitModule Module Initialisation
53  *
54  * The module initialisation can be done as follows:
55  *
56  * \code
57  * // create module config
58  * IfxHssl_Hssl_Config hsslConfig;
59  * IfxHssl_Hssl_initModuleConfig(&hsslConfig, &MODULE_HSSL, &MODULE_HSCT);
60  *
61  * // select the interface mode (in case of slave)
62  * hsslConfig.interfaceMode = IfxHssl_InterfaceMode_slave;
63  *
64  * // select the high speed mode if required
65  * hsslConfig.highSpeedMode = TRUE;
66  *
67  * // initialize module
68  * //IfxHssl_Hssl hssl; // defined globally
69  * IfxHssl_Hssl_initModule(&hssl, &hsslConfig);
70  * \endcode
71  *
72  * \subsection IfxLld_Hssl_Hssl_InitChannel Channel Initialisation
73  *
74  * The Channel initialisation can be done as follows:
75  *
76  * \code
77  * // create HSSL channel config
78  * IfxHssl_Hssl_ChannelConfig hsslChannelConfig;
79  * IfxHssl_Hssl_initChannelConfig(&hsslChannelConfig, &hssl);
80  *
81  * // initialize the channels
82  * // IfxHssl_Hssl_Channel hsslChannel[4]; // defined globally
83  * for(int i=0; i<4; ++i)
84  * {
85  * hsslChannelConfig.channelId = (IfxHssl_ChannelId)i;
86  * IfxHssl_Hssl_initChannel(&hsslChannel[i], &hsslChannelConfig);
87  * }
88  * \endcode
89  *
90  * The HSSL is ready for use now!
91  *
92  *
93  * \section IfxLld_Hssl_Hssl_DataTransfers Data Transfers
94  * \subsection IfxLld_Hssl_Hssl_SimpleTransfers Simple Transfers
95  *
96  * The HSSL driver provides simple to use data transfer functions,
97  *
98  * It supports direct writing of 8/16/32 bit data from the initiator into a target's register, as well as reading a value from the target
99  *
100  * \code
101  * // write some data to remote location:
102  * IfxHssl_Hssl_write(&hsslChannel[0], 0x70000000, 0x12345678, IfxHssl_DataLength_32bit);
103  *
104  * // wait for the acknowledgement
105  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) != IfxHssl_Hssl_Status_ok )
106  * {
107  * if( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) == IfxHssl_Hssl_Status_error )
108  * {
109  * IfxHssl_Hssl_checkErrors(&hssl);
110  * break;
111  * }
112  * }
113  * \endcode
114  *
115  * A simple to use receive function is available as well.
116  *
117  * \code
118  * // read some data from remote location:
119  * IfxHssl_Hssl_read(&hsslChannel[0], 0x70000000, IfxHssl_DataLength_32bit);
120  *
121  * // wait for the acknowledgement
122  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) != IfxHssl_Hssl_Status_ok )
123  * {
124  * if( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) == IfxHssl_Hssl_Status_error )
125  * {
126  * IfxHssl_Hssl_checkErrors(&hssl);
127  * break;
128  * }
129  * }
130  *
131  * // read data from the register
132  * uint32 dataL = IfxHssl_Hssl_getReadData(&hsslChannel[0]);
133  * \endcode
134  *
135  * \subsection IfxLld_Hssl_Hssl_StreamingTransfers Streaming Transfers
136  *
137  * HSSL driver also supports streaming transfers of data as a memory block at both low and high speeds.
138  *
139  * Preparing the target for streaming with the desired memory location where the data needs to be transfered
140  *
141  * \code
142  * // choose a channel other than channel2 for register access //
143  * // prepare streaming of single memory block //
144  * IfxHssl_Hssl_prepareStream(&hsslChannel[0], 0x70000000, 10);
145  * \endcode
146  *
147  * Stream the memory block
148  *
149  * Usage Example:
150  * \code
151  * // __attribute__ ((aligned(256))) uint32 txData[80]; // expected to be declared globally
152  *
153  * // for single block streaming transfer //
154  * // change the txData address to global address before passing it the API
155  *
156  * // IfxHssl_Hssl_writeStream(&hssl, (uint32 *)IFXCPU_GLB_ADDR_DSPR(IfxCpu_getCoreId(), (uint32)txData), 10);
157  *
158  * IfxHssl_Hssl_writeStream(&hssl, txData, 10);
159  *
160  * // wait until the streaming is finished
161  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[2]) != IfxHssl_Hssl_Status_ok )
162  * {}
163  * \endcode
164  *
165  * \defgroup IfxLld_Hssl_Hssl Hssl
166  * \ingroup IfxLld_Hssl
167  * \defgroup IfxLld_Hssl_Hssl_DataStructures Data Structures
168  * \ingroup IfxLld_Hssl_Hssl
169  * \defgroup IfxLld_Hssl_Hssl_Enumerations Enumerations
170  * \ingroup IfxLld_Hssl_Hssl
171  * \defgroup IfxLld_Hssl_Hssl_ModuleFunctions Module Functions
172  * \ingroup IfxLld_Hssl_Hssl
173  * \defgroup IfxLld_Hssl_Hssl_ChannelFunctions Channel Functions
174  * \ingroup IfxLld_Hssl_Hssl
175  * \defgroup IfxLld_Hssl_Hssl_SimpleCom Simple Communication
176  * \ingroup IfxLld_Hssl_Hssl
177  * \defgroup IfxLld_Hssl_Hssl_ErrorHandling Error Handling
178  * \ingroup IfxLld_Hssl_Hssl
179  * \defgroup IfxLld_Hssl_Hssl_StreamingCom Streaming Communication
180  * \ingroup IfxLld_Hssl_Hssl
181  */
182 
183 #ifndef IFXHSSL_HSSL_H
184 #define IFXHSSL_HSSL_H 1
185 
186 /******************************************************************************/
187 /*----------------------------------Includes----------------------------------*/
188 /******************************************************************************/
189 
190 #include "Hssl/Std/IfxHssl.h"
191 #include "Port/Std/IfxPort.h"
192 #include "Scu/Std/IfxScuWdt.h"
193 
194 /******************************************************************************/
195 /*--------------------------------Enumerations--------------------------------*/
196 /******************************************************************************/
197 
198 /** \addtogroup IfxLld_Hssl_Hssl_Enumerations
199  * \{ */
200 /** \brief frame request selection
201  */
202 typedef enum
203 {
204  IfxHssl_Hssl_FrameRequest_readFrame = 1, /**< \brief read frame rquest */
205  IfxHssl_Hssl_FrameRequest_writeFrame = 2, /**< \brief write frame rquest */
206  IfxHssl_Hssl_FrameRequest_triggerFrame = 3, /**< \brief trigger frame rquest */
207  IfxHssl_Hssl_FrameRequest_readId = 4, /**< \brief read id request */
208  IfxHssl_Hssl_FrameRequest_noAction = 5 /**< \brief no action */
210 
211 /** \brief module status
212  */
213 typedef enum
214 {
215  IfxHssl_Hssl_Status_ok = 0, /**< \brief status ok */
216  IfxHssl_Hssl_Status_busy = 1, /**< \brief status busy */
217  IfxHssl_Hssl_Status_error = 2 /**< \brief status error */
219 
220 /** \} */
221 
222 /******************************************************************************/
223 /*-----------------------------Data Structures--------------------------------*/
224 /******************************************************************************/
225 
226 /** \addtogroup IfxLld_Hssl_Hssl_DataStructures
227  * \{ */
228 /** \brief structure for access windows
229  */
230 typedef struct
231 {
232  uint32 start; /**< \brief start of the access */
233  uint32 end; /**< \brief end of the access */
235 
236 /** \} */
237 
238 /** \brief structure for error flags
239  */
240 typedef struct
241 {
242  uint8 notAcknowledgeError : 1; /**< \brief not acknowledge error / tag error */
243  uint8 transactionTagError : 1; /**< \brief transaction tag error */
244  uint8 timeoutError : 1; /**< \brief timeout error */
245  uint8 unexpectedError : 1; /**< \brief unexpected type of frame error */
246  uint8 memoryAccessViolation : 1; /**< \brief memory access violation */
247  uint8 busAccessError : 1; /**< \brief SRI/SPB bus access error */
248  uint8 channelNumberCodeError : 1; /**< \brief PHY inconsistency error 1 (channel number code error) */
249  uint8 dataLengthError : 1; /**< \brief PHY inconsistency error 2 (data length error) */
250  uint8 crcError : 1; /**< \brief CRC error */
252 
253 /** \addtogroup IfxLld_Hssl_Hssl_DataStructures
254  * \{ */
255 /** \brief HSSL Handle
256  */
257 typedef struct
258 {
259  Ifx_HSSL *hssl; /**< \brief pointer to HSSL register */
260  Ifx_HSCT *hsct; /**< \brief pointer to HSCT registers */
261  IfxHssl_Hssl_errorFlags errorFlags; /**< \brief structure for error flags */
262  boolean loopBack; /**< \brief loopc back selection */
263 } IfxHssl_Hssl;
264 
265 /** \brief channel handle
266  */
267 typedef struct
268 {
269  Ifx_HSSL *hssl; /**< \brief pointer to HSSL registers */
270  Ifx_HSCT *hsct; /**< \brief pointer to HSCT registers */
271  IfxHssl_ChannelId channelId; /**< \brief channel number (id) */
272  IfxHssl_Hssl_FrameRequest currentFrameRequest; /**< \brief current frame request */
273  IfxHssl_StreamingMode streamingMode; /**< \brief streaming mode selection ( single / continuous ) */
274  boolean loopBack; /**< \brief loopback (enable / disable) for streaming transfers within the microcontroller */
275  boolean streamingModeOn; /**< \brief streaming mode or command mode */
277 
278 /** \brief configuration structure for channel
279  */
280 typedef struct
281 {
282  Ifx_HSSL *hssl; /**< \brief pointer to HSSL registers */
283  Ifx_HSCT *hsct; /**< \brief pointer to HSCT registers */
284  IfxHssl_ChannelId channelId; /**< \brief channel number (id) */
285  IfxHssl_StreamingMode streamingMode; /**< \brief streaming mode selection ( single / continuous ) */
286  boolean loopBack; /**< \brief loop back (enable / disable) for streaming transfers within the microcontroller */
288 
289 /** \brief configuration structure of the module
290  */
291 typedef struct
292 {
293  Ifx_HSSL *hssl; /**< \brief pointer to HSSL registers */
294  Ifx_HSCT *hsct; /**< \brief pointer to HSCT registers */
295  IfxHssl_Hssl_AccessWindow accessWindow0; /**< \brief access window of channel 0 */
296  IfxHssl_Hssl_AccessWindow accessWindow1; /**< \brief access window of channel 1 */
297  IfxHssl_Hssl_AccessWindow accessWindow2; /**< \brief access window of channel 2 */
298  IfxHssl_Hssl_AccessWindow accessWindow3; /**< \brief access window of channel 3 */
299  uint16 preDivider; /**< \brief Defines the down-scaled module clock to be used by all channel timeout timers */
300  IfxHssl_InterfaceMode interfaceMode; /**< \brief interface mode (master IF /slave IF) */
301  boolean highSpeedMode; /**< \brief high speed mode selection */
302  boolean loopBack; /**< \brief loopc back selection */
304 
305 /** \} */
306 
307 /** \addtogroup IfxLld_Hssl_Hssl_ModuleFunctions
308  * \{ */
309 
310 /******************************************************************************/
311 /*-------------------------Global Function Prototypes-------------------------*/
312 /******************************************************************************/
313 
314 /** \brief Initialises the module
315  * \param hssl HSSL handle
316  * \param config configuration structure of the module
317  * \return None
318  *
319  * Usage Example:
320  * \code
321  * // create module config
322  * IfxHssl_Hssl_Config hsslConfig;
323  * IfxHssl_Hssl_initModuleConfig(&hsslConfig, &MODULE_HSSL, &MODULE_HSCT);
324  *
325  * // select the interface mode (in case of slave)
326  * hsslConfig.interfaceMode = IfxHssl_InterfaceMode_slave;
327  *
328  * // select the high speed mode if required
329  * hsslConfig.highSpeedMode = TRUE;
330  *
331  * // initialize module
332  * IfxHssl_Hssl hssl;
333  * IfxHssl_Hssl_initModule(&hssl, &hsslConfig);
334  * \endcode
335  *
336  */
338 
339 /** \brief Fills the config structure with default values
340  * \param config configuration structure of the module
341  * \param hssl pointer to HSSL registers
342  * \param hsct pointer to HSCT register
343  * \return None
344  *
345  * Usage example: see \ref IfxHssl_Hssl_initModule
346  *
347  */
348 IFX_EXTERN void IfxHssl_Hssl_initModuleConfig(IfxHssl_Hssl_Config *config, Ifx_HSSL *hssl, Ifx_HSCT *hsct);
349 
350 /** \} */
351 
352 /** \addtogroup IfxLld_Hssl_Hssl_ChannelFunctions
353  * \{ */
354 
355 /******************************************************************************/
356 /*-------------------------Global Function Prototypes-------------------------*/
357 /******************************************************************************/
358 
359 /** \brief Initialises the channel
360  * \param channel channel handle
361  * \param channelConfig configuration structure for channel
362  * \return None
363  *
364  * Usage Example:
365  * \code
366  * // create HSSL channel config
367  * IfxHssl_Hssl_ChannelConfig hsslChannelConfig;
368  * IfxHssl_Hssl_initChannelConfig(&hsslChannelConfig, &hssl);
369  *
370  * // initialize the channels
371  * // IfxHssl_Hssl_Channel hsslChannel[4]; // defined globally
372  * for(int i=0; i<4; ++i) {
373  * hsslChannelConfig.channelId = (IfxHssl_ChannelId)i;
374  * IfxHssl_Hssl_initChannel(&hsslChannel[i], &hsslChannelConfig);
375  * }
376  * \endcode
377  *
378  */
380 
381 /** \brief Fills the channel config structure with default values
382  * \param channelConfig configuration structure for channel
383  * \param hssl HSSL Handle
384  * \return None
385  *
386  * Usage example: see \ref IfxHssl_Hssl_initChannel
387  *
388  */
390 
391 /** \} */
392 
393 /** \addtogroup IfxLld_Hssl_Hssl_SimpleCom
394  * \{ */
395 
396 /******************************************************************************/
397 /*-------------------------Inline Function Prototypes-------------------------*/
398 /******************************************************************************/
399 
400 /** \brief reads and returs the data
401  * \param channel channel handle
402  * \return data
403  *
404  * Usage Example:
405  * \code
406  * uint32 dataL = IfxHssl_Hssl_getReadData(&hsslChannel[0]);
407  * \endcode
408  *
409  */
411 
412 /******************************************************************************/
413 /*-------------------------Global Function Prototypes-------------------------*/
414 /******************************************************************************/
415 
416 /** \brief Initiates read request
417  * \param channel channel handle
418  * \param address address of the location from where the data is to be read
419  * \param dataLength length of the data
420  * \return module status (ok, busy, error)
421  *
422  * Usage Example:
423  * \code
424  * // read some data from remote location:
425  * IfxHssl_Hssl_read(&hsslChannel[0], 0x70000000, IfxHssl_DataLength_32bit);
426  * \endcode
427  *
428  */
430 
431 /** \brief sends a predefined command from master to slave
432  * \param hssl HSSL handle
433  * \param command command value
434  * \return None
435  *
436  * Usage Example:
437  * \code
438  * // enable slave Tx channel (Rx disable to Rx low peed) //
439  * IfxHssl_Hssl_sendControlCommand(&hssl, IfxHssl_ControlCommand_enableReception);
440  * \endcode
441  *
442  */
444 
445 /** \brief waits until the current transaction is done
446  * \param channel channel handle
447  * \return module status (ok, busy, error)
448  *
449  * Usage Example:
450  * \code
451  * // write some data to remote location:
452  * IfxHssl_Hssl_write(&hsslChannel[0], 0x70000000, 0x12345678, IfxHssl_DataLength_32bit);
453  *
454  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) != IfxHssl_Hssl_Status_ok )
455  * {
456  * if( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) == IfxHssl_Hssl_Status_error )
457  * {
458  * IfxHssl_Hssl_checkErrors(&hssl);
459  * break;
460  * }
461  * }
462  *
463  * // read some data from remote location:
464  * IfxHssl_Hssl_read(&hsslChannel[0], 0x70000000, IfxHssl_DataLength_32bit);
465  *
466  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) != IfxHssl_Hssl_Status_ok )
467  * {
468  * if( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[0]) == IfxHssl_Hssl_Status_error )
469  * {
470  * IfxHssl_Hssl_checkErrors(&hssl);
471  * break;
472  * }
473  * }
474  *
475  * uint32 dataL = IfxHssl_Hssl_getReadData(&hsslChannel[0]);
476  * \endcode
477  *
478  */
480 
481 /** \brief writes single frame of data into the specified address
482  * \param channel channel handle
483  * \param address address of the location where the data is to be written
484  * \param data data that needs to be written
485  * \param dataLength length of the data (8, 16, 32 bit)
486  * \return module status (ok, busy, error)
487  *
488  * Usage Example:
489  * \code
490  * // write some data to remote location:
491  * IfxHssl_Hssl_write(&hsslChannel[0], 0x70000000, 0x12345678, IfxHssl_DataLength_32bit);
492  * \endcode
493  *
494  */
496 
497 /** \} */
498 
499 /** \addtogroup IfxLld_Hssl_Hssl_ErrorHandling
500  * \{ */
501 
502 /******************************************************************************/
503 /*-------------------------Global Function Prototypes-------------------------*/
504 /******************************************************************************/
505 
506 /** \brief stores the status of errors in the respective members of the error flags structure
507  * \param hssl HSSL handle
508  * \param channel channel handle
509  * \return None
510  */
512 
513 /** \brief clears the status of members in the error flags structure
514  * \param hssl HSSL handle
515  * \return None
516  */
518 
519 /** \} */
520 
521 /** \addtogroup IfxLld_Hssl_Hssl_StreamingCom
522  * \{ */
523 
524 /******************************************************************************/
525 /*-------------------------Global Function Prototypes-------------------------*/
526 /******************************************************************************/
527 
528 /** \brief Prepares the target device for streaming
529  * \param channel channel handle
530  * \param slaveTargetAddress address of the location on target device where the data needs to be transfered
531  * \param count Frame count (length of the data in the memory as 256 bytes per frame)
532  * \return module status (ok, busy, error)
533  *
534  * Usage Example:
535  * \code
536  * // choose a channel other than channel2 for register access //
537  * // prepare streaming of single memory block //
538  * IfxHssl_Hssl_prepareStream(&hsslChannel[0], 0x70000000, 10);
539  * \endcode
540  *
541  */
543 
544 /** \brief transfers one memory block of data
545  * useful for transfering huge data from one location to another and between devices
546  * \param hssl HSSL handle
547  * \param data starting address of the location to be read from (memory block 0 / HSSL_ISSA0)
548  * \param count Frame count (length of the data in the memory as 256 bytes per frame)
549  * \return module status (ok, busy, error)
550  *
551  * Usage Example:
552  * \code
553  * // __attribute__ ((aligned(256))) uint32 txData[80]; // expected to be declared globally
554  *
555  * // for single block streaming transfer //
556  * // change the txData address to global address before passing it the API
557  *
558  * // IfxHssl_Hssl_writeStream(&hssl, (uint32 *)IFXCPU_GLB_ADDR_DSPR(IfxCpu_getCoreId(), (uint32)txData), 10);
559  *
560  * IfxHssl_Hssl_writeStream(&hssl, txData, 10);
561  *
562  * // wait until the streaming is finished
563  * while( IfxHssl_Hssl_waitAcknowledge(&hsslChannel[2]) != IfxHssl_Hssl_Status_ok )
564  * {}
565  * \endcode
566  *
567  */
569 
570 /** \} */
571 
572 /******************************************************************************/
573 /*---------------------Inline Function Implementations------------------------*/
574 /******************************************************************************/
575 
577 {
578  Ifx_HSSL_I *hsslI = (Ifx_HSSL_I *)&channel->hssl->I[channel->channelId];
579  return hsslI->IRD.U; // retutn the data read from the data register
580 }
581 
582 
583 #endif /* IFXHSSL_HSSL_H */