git.sur5r.net Git - freertos/blob - Demo/CORTEX_A2F200_IAR_and_Keil/MicroSemi_Code/drivers/mss_spi/mss_spi.h

   1 /***************************************************************************//**\r
   2  * (c) Copyright 2008 Actel Corporation.  All rights reserved.\r
   3  * \r
   4  * SmartFusion microcontroller subsystem SPI bare metal software driver public API.\r
   5  *\r
   6  * The microcontroller subsystem SPI driver provides functions for implementing\r
   7  * SPI master or SPI slave operations. These operations can be one of two\r
   8  * classes: SPI frame operation or block transfer operations.\r
   9  * Frame operations allow transferring SPI frames from 4 to 32 bits long. Block\r
  10  * operations allow transferring blocks of data organized as 8 bit bytes. \r
  11  *\r
  12  * SVN $Revision: 2189 $\r
  13  * SVN $Date: 2010-02-16 22:02:32 +0000 (Tue, 16 Feb 2010) $\r
  14  */\r
  15 /*=========================================================================*//**\r
  16   @mainpage SmartFusion MSS SPI Bare Metal Driver.\r
  17 \r
  18   @section intro_sec Introduction\r
  19   The SmartFusion\99 microcontroller subsystem (MSS) includes two serial\r
  20   peripheral interface SPI peripherals for serial communication. This driver\r
  21   provides a set of functions for controlling the MSS SPIs as part of a bare\r
  22   metal system where no operating system is available. These drivers can be\r
  23   adapted for use as part of an operating system, but the implementation of the\r
  24   adaptation layer between this driver and the operating system's driver model\r
  25   is outside the scope of this driver.\r
  26   \r
  27   @section hw_dependencies Hardware Flow Dependencies\r
  28   The configuration of all features of the MSS SPIs is covered by this driver\r
  29   with the exception of the SmartFusion IOMUX configuration. SmartFusion allows\r
  30   multiple non-concurrent uses of some external pins through IOMUX configuration.\r
  31   This feature allows optimization of external pin usage by assigning external\r
  32   pins for use by either the microcontroller subsystem or the FPGA fabric. The\r
  33   MSS SPIs serial signals are routed through IOMUXes to the SmartFusion device\r
  34   external pins. These IOMUXes are automatically configured correctly by the MSS\r
  35   configurator tool in the hardware flow when the MSS SPIs are enabled in that\r
  36   tool. You must ensure that the MSS SPIs are enabled by the MSS configurator\r
  37   tool in the hardware flow; otherwise the serial inputs and outputs will not be\r
  38   connected to the chip's external pins. For more information on IOMUX, refer to\r
  39   the IOMUX section of the SmartFusion Datasheet.\r
  40   The base address, register addresses and interrupt number assignment for the\r
  41   MSS SPI blocks are defined as constants in the SmartFusion CMSIS-PAL. You must\r
  42   ensure that the SmartFusion CMSIS-PAL is either included in the software tool\r
  43   chain used to build your project or is included in your project.\r
  44   \r
  45   @section theory_op Theory of Operation\r
  46   The MSS SPI driver functions are grouped into the following categories:\r
  47     \95 Initialization\r
  48     \95 Configuration for either master or slave operations\r
  49     \95 SPI master frame transfer control\r
  50     \95 SPI master block transfer control\r
  51     \95 SPI slave frame transfer control\r
  52     \95 SPI slave block transfer control\r
  53     \95 DMA block transfer\r
  54   Frame transfers allow the MSS SPI to write or read up to 32 bits of data in a\r
  55   SPI transaction. For example, a frame transfer of 12 bits might be used to\r
  56   read the result of an ADC conversion from a SPI analog to digital converter.\r
  57   Block transfers allow the MSS SPI to write or read a number of bytes in a SPI\r
  58   transaction. Block transfer transactions allow data transfers in multiples of\r
  59   8 bits (8, 16, 24, 32, 40\85). Block transfers are typically used with byte\r
  60   oriented devices like SPI FLASH devices.\r
  61 \r
  62   Initialization \r
  63     The MSS SPI driver is initialized through a call to the MSS_SPI_init()\r
  64     function. The MSS_SPI_init() function takes only one parameter, a pointer\r
  65     to one of two global data structures used by the driver to store state\r
  66     information for each MSS SPI. A pointer to these data structures is also\r
  67     used as first parameter to any of the driver functions to identify which MSS\r
  68     SPI will be used by the called function. The names of these two data\r
  69     structures are g_mss_spi0 and g_mss_spi1. Therefore any call to an MSS SPI\r
  70     driver function should be of the form MSS_SPI_function_name( &g_mss_spi0, ... )\r
  71     or MSS_SPI_function_name( &g_mss_spi1, ... ).\r
  72     The MSS_SPI_init() function resets the specified MSS SPI hardware block and\r
  73     clears any pending interrupts from that MSS SPI in the Cortex-M3 NVIC.\r
  74     The MSS_SPI_init() function must be called before any other MSS SPI driver\r
  75     functions can be called.\r
  76 \r
  77   Configuration\r
  78     A MSS SPI block can operate either as a master or slave SPI device. There\r
  79     are two distinct functions for configuring a MSS SPI block for master or\r
  80     slave operations.\r
  81 \r
  82     Master configuration\r
  83     The MSS_SPI_configure_master_mode() function configures the specified MSS\r
  84     SPI block for operations as a SPI master. It must be called once for each\r
  85     remote SPI slave device the MSS SPI block will communicate with. It is used\r
  86     to provide the following information about each SPI slave\92s communication\r
  87     characteristics:\r
  88         \95 The SPI protocol mode\r
  89         \95 The SPI clock speed\r
  90         \95 The frame bit length\r
  91     This information is held by the driver and will be used to alter the\r
  92     configuration of the MSS SPI block each time a slave is selected through a\r
  93     call to MSS_SPI_set_slave_select(). The SPI protocol mode defines the\r
  94     initial state of the clock signal at the start of a transaction and which\r
  95     clock edge will be used to sample the data signal, or it defines whether the\r
  96     SPI block will operate in TI synchronous serial mode or in NSC MICROWIRE mode.\r
  97 \r
  98     Slave configuration\r
  99     The MSS_SPI_configure_slave_mode() function configures the specified MSS SPI\r
 100     block for operations as a SPI slave. It configures the following SPI\r
 101     communication characteristics:\r
 102         \95 The SPI protocol mode \r
 103         \95 The SPI clock speed\r
 104         \95 The frame bit length\r
 105     The SPI protocol mode defines the initial state of the clock signal at the\r
 106     start of a transaction and which clock edge will be used to sample the data\r
 107     signal, or it defines whether the SPI block will operate in TI synchronous\r
 108     serial mode or in NSC MICROWIRE mode.\r
 109 \r
 110   SPI master frame transfer control\r
 111     The following functions are used as part of SPI master frame transfers:\r
 112         \95 MSS_SPI_set_slave_select()\r
 113         \95 MSS_SPI_transfer_frame()\r
 114         \95 MSS_SPI_clear_slave_select()\r
 115     The master must first select the target slave through a call to\r
 116     MSS_SPI_set_slave_select(). This causes the relevant slave select line to\r
 117     become asserted while data is clocked out onto the SPI data line.\r
 118     A call to is then made to function MSS_SPI_transfer_frame() specifying and\r
 119     the value of the data frame to be sent.\r
 120     The function MSS_SPI_clear_slave_select() can be used after the transfer is\r
 121     complete to prevent this slave select line from being asserted during\r
 122     subsequent SPI transactions. A call to this function is only required if the\r
 123     master is communicating with multiple slave devices.\r
 124 \r
 125   SPI master block transfer control\r
 126     The following functions are used as part of SPI master block transfers:\r
 127         \95 MSS_SPI_set_slave_select()\r
 128         \95 MSS_SPI_clear_slave_select()\r
 129         \95 MSS_SPI_transfer_block()\r
 130     The master must first select the target slave through a call to\r
 131     MSS_SPI_set_slave_select(). This causes the relevant slave select line to\r
 132     become asserted while data is clocked out onto the SPI data line.\r
 133     Alternatively a GPIO can be used to control the state of the target slave\r
 134     device\92s chip select signal.\r
 135     A call to is then made to function MSS_SPI_transfer_block (). The\r
 136     parameters of this function specify:\r
 137         \95 the number of bytes to be transmitted\r
 138         \95 a pointer to the buffer containing the data to be transmitted\r
 139         \95 the number of bytes to be received\r
 140         \95 a pointer to the buffer where received data will be stored\r
 141     The number of bytes to be transmitted can be set to zero to indicate that\r
 142     the transfer is purely a block read transfer. The number of bytes to be\r
 143     received can be set to zero to specify that the transfer is purely a block\r
 144     write transfer.\r
 145     The function MSS_SPI_clear_slave_select() can be used after the transfer is\r
 146     complete to prevent this slave select line from being asserted during\r
 147     subsequent SPI transactions. A call to this function is only required if the\r
 148     master is communicating with multiple slave devices.\r
 149  \r
 150   SPI slave frame transfer control\r
 151     The following functions are used as part of SPI slave frame transfers:\r
 152         \95 MSS_SPI_set_slave_tx_frame()\r
 153         \95 MSS_SPI_set_frame_rx_handler()\r
 154     The MSS_SPI_set_slave_tx_frame() function specifies the frame data that will\r
 155     be returned to the SPI master. The frame data specified through this\r
 156     function is the value that will be read over the SPI bus by the remote SPI\r
 157     master when it initiates a transaction. A call to MSS_SPI_set_slave_tx_frame()\r
 158     is only required if the MSS SPI slave is the target of SPI  read transactions,\r
 159     i.e. if data is meant to be read from the SmartFusion device over SPI.\r
 160     The MSS_SPI_set_frame_rx_handler() function specifies the receive handler\r
 161     function that will called when a frame of data has been received by the MSS\r
 162     SPI when it is configured as a slave. The receive handler function specified\r
 163     through this call will process the frame data written, over the SPI bus, to\r
 164     the MSS SPI slave by the remote SPI master. The receive handler function must\r
 165     be implemented as part of the application. It is only required if the MSS SPI\r
 166     slave is the target of SPI frame write transactions.\r
 167 \r
 168   SPI slave block transfer control\r
 169     The following functions are used as part of SPI slave block transfers:\r
 170         \95 MSS_SPI_set_slave_block_buffers()\r
 171     The MSS_SPI_set_slave_block_buffers() function is used to configure a MSS SPI\r
 172     slave for block transfer operations. It specifies:\r
 173         \95 The buffer containing the data that will be returned to the remote SPI master\r
 174         \95 The buffer where data received from the remote SPI master will be stored\r
 175         \95 The handler function that will be called after the receive buffer is filled\r
 176 \r
 177   DMA block transfer control\r
 178     The following functions are used as part of MSS SPI DMA transfers:\r
 179         \95 MSS_SPI_disable()\r
 180         \95 MSS_SPI_set_transfer_byte_count()\r
 181         \95 MSS_SPI_enable()\r
 182         \95 MSS_SPI_tx_done()\r
 183     The MSS SPI must first be disabled through a call to function MSS_SPI_disable().\r
 184     The number of bytes to be transferred is then set through a call to function\r
 185     MSS_SPI_set_transfer_byte_count(). The DMA transfer is then initiated by a call\r
 186     to the MSS_PDMA_start() function provided by the MSS PDMA driver. The actual\r
 187     DMA transfer will only start once the MSS SPI block has been re-enabled through\r
 188     a call to  MSS_SPI_enable(). The completion of the DMA driven SPI transfer can\r
 189     be detected through a call to MSS_SPI_tx_done(). The direction of the SPI\r
 190     transfer, write or read, depends on the DMA channel configuration. A SPI write\r
 191     transfer occurs when the DMA channel is configured to write data to the MSS SPI\r
 192     block. A SPI read transfer occurs when the DMA channel is configured to read data\r
 193     from the MSS SPI block.\r
 194 \r
 195  *//*=========================================================================*/\r
 196 #ifndef MSS_SPI_H_\r
 197 #define MSS_SPI_H_\r
 198 \r
 199 #include "../../CMSIS/a2fxxxm3.h"\r
 200 \r
 201 #ifdef __cplusplus\r
 202 extern "C" {\r
 203 #endif \r
 204 \r
 205 /***************************************************************************//**\r
 206   This defines the function prototype that must be followed by MSS SPI slave\r
 207   frame receive handler functions. These functions are registered with the MSS\r
 208   SPI driver through the MSS_SPI_set_frame_rx_handler () function.\r
 209   \r
 210   Declaring and Implementing Slave Frame Receive Handler Functions:\r
 211     Slave frame receive handler functions should follow the following prototype:\r
 212         void slave_frame_receive_handler ( uint32_t rx_frame );\r
 213     The actual name of the receive handler is unimportant. You can use any name\r
 214     of your choice for the receive frame handler. The rx_frame parameter will\r
 215     contain the value of the received frame.\r
 216  */\r
 217 typedef void (*mss_spi_frame_rx_handler_t)( uint32_t rx_frame );\r
 218 \r
 219 /***************************************************************************//**\r
 220   This defines the function prototype that must be followed by MSS SPI slave\r
 221   block receive handler functions. These functions are registered with the MSS\r
 222   SPI driver through the MSS_SPI_set_slave_block_buffers() function.\r
 223   \r
 224   Declaring and Implementing Slave Block Receive Handler Functions\r
 225     Slave block receive handler functions should follow the following prototype:\r
 226         void mss_spi_block_rx_handler ( uint8_t * rx_buff, uint16_t rx_size );\r
 227     The actual name of the receive handler is unimportant. You can use any name\r
 228     of your choice for the receive frame handler. The rx_buff parameter will\r
 229     contain a pointer to the start of the received block. The rx_size parameter\r
 230     will contain the number of bytes of the received block.\r
 231 \r
 232  */\r
 233 typedef void (*mss_spi_block_rx_handler_t)( uint8_t * rx_buff, uint32_t rx_size );\r
 234 \r
 235 /***************************************************************************//**\r
 236   This enumeration is used to define the settings for the SPI protocol mode\r
 237   bits, CPHA and CPOL. It is used as a parameter to the MSS_SPI_configure_master_mode()\r
 238   and MSS_SPI_configure_slave_mode() functions.\r
 239   \r
 240   - MSS_SPI_MODE0:\r
 241         Clock starts low, data read on clock's rising edge, data changes on\r
 242         falling edge.\r
 243         \r
 244   - MSS_SPI_MODE1:\r
 245         Clock starts low, data read on clock's falling edge, data changes on\r
 246         rising edge.\r
 247         \r
 248   - MSS_SPI_MODE2:\r
 249         Clock starts high, data read on clock's falling edge, data changes on\r
 250         rising edge.\r
 251         \r
 252   - MSS_SPI_MODE3:\r
 253         Clock starts high, data read on clock's rising edge, data changes on\r
 254         falling edge.\r
 255         \r
 256   - MSS_TI_MODE:  \r
 257         TI syncronous serial mode. Slave select is pulsed at start of transfer.\r
 258         \r
 259   - MSS_NSC_MODE:\r
 260         NSC Microwire mode.\r
 261  */\r
 262 typedef enum __mss_spi_protocol_mode_t\r
 263 {\r
 264     MSS_SPI_MODE0    = 0x00000000,\r
 265     MSS_SPI_TI_MODE  = 0x00000004,\r
 266     MSS_SPI_NSC_MODE = 0x00000008,\r
 267     MSS_SPI_MODE2    = 0x01000000,\r
 268     MSS_SPI_MODE1    = 0x02000000,\r
 269     MSS_SPI_MODE3    = 0x03000000\r
 270 } mss_spi_protocol_mode_t;\r
 271 \r
 272 /***************************************************************************//**\r
 273  This enumeration specifies the divider to be applied to the the APB bus clock\r
 274  in order to generate the SPI clock. It is used as parameter to the\r
 275  MSS_SPI_configure_master_mode() and MSS_SPI_configure_slave_mode()functions.\r
 276  */\r
 277  typedef enum __mss_spi_pclk_div_t\r
 278  {\r
 279         MSS_SPI_PCLK_DIV_2              = 0,\r
 280         MSS_SPI_PCLK_DIV_4              = 1,\r
 281         MSS_SPI_PCLK_DIV_8              = 2,\r
 282         MSS_SPI_PCLK_DIV_16             = 3,\r
 283         MSS_SPI_PCLK_DIV_32             = 4,\r
 284         MSS_SPI_PCLK_DIV_64             = 5,\r
 285         MSS_SPI_PCLK_DIV_128    = 6,\r
 286         MSS_SPI_PCLK_DIV_256    = 7\r
 287 } mss_spi_pclk_div_t;\r
 288 \r
 289 /***************************************************************************//**\r
 290  This enumeration is used to select a specific SPI slave device (0 to 7). It is\r
 291  used as a parameter to the MSS_SPI_configure_master_mode(),\r
 292  MSS_SPI_set_slave_select() and MSS_SPI_clear_slave_select () functions.\r
 293  */\r
 294  typedef enum __mss_spi_slave_t\r
 295  {\r
 296         MSS_SPI_SLAVE_0         = 0,\r
 297         MSS_SPI_SLAVE_1         = 1,\r
 298         MSS_SPI_SLAVE_2         = 2,\r
 299         MSS_SPI_SLAVE_3         = 3,\r
 300         MSS_SPI_SLAVE_4         = 4,\r
 301         MSS_SPI_SLAVE_5         = 5,\r
 302         MSS_SPI_SLAVE_6         = 6,\r
 303         MSS_SPI_SLAVE_7         = 7,\r
 304     MSS_SPI_MAX_NB_OF_SLAVES = 8\r
 305 } mss_spi_slave_t;\r
 306 \r
 307 /***************************************************************************//**\r
 308   This constant defines a frame size of 8 bits when configuring an MSS SPI to\r
 309   perform block transfer data transactions.\r
 310   It must be used as the value for the frame_bit_length parameter of function\r
 311   MSS_SPI_configure_master_mode() when performing block transfers between the\r
 312   MSS SPI master and the target SPI slave.\r
 313   It must also be used as the value for the frame_bit_length parameter of\r
 314   function MSS_SPI_configure_slave_mode() when performing block transfers\r
 315   between the MSS SPI slave and the remote SPI master.\r
 316  */\r
 317 #define MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE   8\r
 318 \r
 319 /***************************************************************************//**\r
 320   The mss_spi_slave_cfg_t holds the MSS SPI configuration that must be used to\r
 321   communicate with a specific SPI slave.\r
 322  */\r
 323 typedef struct __mss_spi_slave_cfg_t\r
 324 {\r
 325     uint32_t ctrl_reg;\r
 326     uint8_t txrxdf_size_reg;\r
 327     uint8_t clk_gen;\r
 328 } mss_spi_slave_cfg_t;\r
 329 \r
 330 /***************************************************************************//**\r
 331   There is one instance of this structure for each of the microcontroller\r
 332   subsystem's SPIs. Instances of this structure are used to identify a specific\r
 333   SPI. A pointer to an instance of the mss_spi_instance_t structure is passed as\r
 334   the first parameter to MSS SPI driver functions to identify which SPI should\r
 335   perform the requested operation.\r
 336  */\r
 337 typedef struct __mss_spi_instance_t\r
 338 {\r
 339     /* CMSIS related defines identifying the SPI hardware. */\r
 340     SPI_TypeDef *          hw_reg;     /*!< Pointer to SPI registers. */\r
 341     SPI_BitBand_TypeDef *  hw_reg_bit; /*!< Pointer to SPI registers bit band area. */\r
 342     IRQn_Type               irqn;       /*!< SPI's Cortex-M3 NVIC interrupt number. */\r
 343     \r
 344         /* Internal transmit state: */\r
 345         const uint8_t * slave_tx_buffer;    /*!< Pointer to slave transmit buffer. */\r
 346         uint32_t slave_tx_size;             /*!< Size of slave transmit buffer. */\r
 347         uint32_t slave_tx_idx;              /*!< Current index into slave transmit buffer. */\r
 348         \r
 349         /* Internal receive state: */\r
 350         uint8_t * slave_rx_buffer;          /*!< Pointer to buffer where data received by a slave will be stored. */\r
 351         uint32_t slave_rx_size;             /*!< Slave receive buffer size. */\r
 352         uint32_t slave_rx_idx;              /*!< Current index into slave receive buffer. */\r
 353     \r
 354     /* Configuration for each target slave. */\r
 355     mss_spi_slave_cfg_t slaves_cfg[MSS_SPI_MAX_NB_OF_SLAVES];\r
 356     \r
 357     /** Slave received frame handler: */\r
 358     mss_spi_frame_rx_handler_t frame_rx_handler;    /*!< Pointer to function that will be called when a frame is received when the SPI block is configured as slave. */\r
 359     \r
 360     uint32_t slave_tx_frame;                /*!< Value of the data frame that will be transmited when the SPI block is configured as slave. */\r
 361     \r
 362     /* Slave block rx handler: */\r
 363     mss_spi_block_rx_handler_t block_rx_handler;    /*!< Pointer to the function that will be called when a data block has been received. */\r
 364 \r
 365 } mss_spi_instance_t;\r
 366 \r
 367 /***************************************************************************//**\r
 368   This instance of mss_spi_instance_t holds all data related to the operations\r
 369   performed by MSS SPI 0. A pointer to g_mss_spi0 is passed as the first\r
 370   parameter to MSS SPI driver functions to indicate that MSS SPI 0 should\r
 371   perform the requested operation.\r
 372  */\r
 373 extern mss_spi_instance_t g_mss_spi0;\r
 374 \r
 375 /***************************************************************************//**\r
 376   This instance of mss_spi_instance_t holds all data related to the operations\r
 377   performed by MSS SPI 1. A pointer to g_mss_spi1 is passed as the first\r
 378   parameter to MSS SPI driver functions to indicate that MSS SPI 1 should\r
 379   perform the requested operation.\r
 380  */\r
 381 extern mss_spi_instance_t g_mss_spi1;\r
 382 \r
 383 /***************************************************************************//**\r
 384   The MSS_SPI_init() function initializes and hardware and data structures of\r
 385   one of the SmartFusion MSS SPIs. The MSS_SPI_init() function must be called\r
 386   before any other MSS SPI driver functions can be called.\r
 387   \r
 388   @param this_spi\r
 389     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 390     identifying the MSS SPI hardware block to be initialized. There are two such\r
 391     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 392     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 393     or g_mss_spi1 global data structure defined within the SPI driver.\r
 394     \r
 395   Example:\r
 396   @code\r
 397   MSS_SPI_init( &g_mss_spi0 );\r
 398   @endcode\r
 399  */\r
 400 void MSS_SPI_init\r
 401 (\r
 402         mss_spi_instance_t * this_spi\r
 403 );\r
 404 \r
 405 /***************************************************************************//**\r
 406   The MSS_SPI_configure_slave_mode() function configure a MSS SPI block for\r
 407   operations as a slave SPI device. It configures the SPI hardware with the\r
 408   selected SPI protocol mode and clock speed.\r
 409     \r
 410   @param this_spi\r
 411     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 412     identifying the MSS SPI hardware block to be initialized. There are two such\r
 413     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 414     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 415     or g_mss_spi1 global data structure defined within the SPI driver.\r
 416     \r
 417   @param protocol_mode\r
 418     Serial peripheral interface operating mode. Allowed values are:\r
 419         - MSS_SPI_MODE0\r
 420         - MSS_SPI_MODE1\r
 421         - MSS_SPI_MODE2\r
 422         - MSS_SPI_MODE3\r
 423         - MSS_TI_MODE\r
 424         - MSS_NSC_MODE\r
 425  \r
 426   @param clk_rate\r
 427     Divider value used to generate serial interface clock signal from PCLK.\r
 428     Allowed values are:\r
 429         - MSS_SPI_PCLK_DIV_2\r
 430         - MSS_SPI_PCLK_DIV_4\r
 431         - MSS_SPI_PCLK_DIV_8\r
 432         - MSS_SPI_PCLK_DIV_16\r
 433         - MSS_SPI_PCLK_DIV_32\r
 434         - MSS_SPI_PCLK_DIV_64\r
 435         - MSS_SPI_PCLK_DIV_128\r
 436         - MSS_SPI_PCLK_DIV_256\r
 437        \r
 438   @param frame_bit_length\r
 439     Number of bits making up the frame. The maximum frame length is 32 bits. You\r
 440     must use the MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE constant as the value for\r
 441     frame_bit_length when configuring the MSS SPI master for block transfer\r
 442     transactions with the target SPI slave.\r
 443   \r
 444   Example:\r
 445   @code\r
 446   MSS_SPI_init( &g_mss_spi0 );\r
 447   MSS_SPI_configure_slave_mode\r
 448     (\r
 449         &g_mss_spi0,\r
 450         MSS_SPI_MODE2,\r
 451         MSS_SPI_PCLK_DIV_64,\r
 452         MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
 453     );\r
 454   @endcode\r
 455   \r
 456  */ \r
 457 void MSS_SPI_configure_slave_mode\r
 458 (\r
 459         mss_spi_instance_t * this_spi,\r
 460     mss_spi_protocol_mode_t protocol_mode,\r
 461     mss_spi_pclk_div_t clk_rate,\r
 462     uint8_t frame_bit_length\r
 463 );\r
 464 \r
 465 /***************************************************************************//**\r
 466   The MSS_SPI_configure_master_mode() function configures the protocol mode,\r
 467   serial clock speed and frame size for a specific target SPI slave device. It\r
 468   is used when the MSS SPI hardware block is used as a SPI master. This function\r
 469   must be called once for each target SPI slave the SPI master is going to\r
 470   communicate with. The SPI master hardware will be configured with the\r
 471   configuration specified by this function during calls to\r
 472   MSS_SPI_set_slave_select().\r
 473   \r
 474   @param this_spi\r
 475     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 476     identifying the MSS SPI hardware block to be initialized. There are two such\r
 477     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 478     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 479     or g_mss_spi1 global data structure defined within the SPI driver.\r
 480     \r
 481     \r
 482   @param slave\r
 483     The slave parameter is used to identify a target SPI slave. The driver will\r
 484     hold the MSS SPI master configuration required to communicate with this\r
 485     slave, as specified by the other function parameters. Allowed values are:\r
 486         \95 MSS_SPI_SLAVE_0\r
 487         \95 MSS_SPI_SLAVE_1\r
 488         \95 MSS_SPI_SLAVE_2\r
 489         \95 MSS_SPI_SLAVE_3\r
 490         \95 MSS_SPI_SLAVE_4\r
 491         \95 MSS_SPI_SLAVE_5\r
 492         \95 MSS_SPI_SLAVE_6\r
 493         \95 MSS_SPI_SLAVE_7\r
 494     \r
 495   @param protocol_mode\r
 496     Serial peripheral interface operating mode. Allowed values are:\r
 497         \95 MSS_SPI_MODE0\r
 498         \95 MSS_SPI_MODE1\r
 499         \95 MSS_SPI_MODE2\r
 500         \95 MSS_SPI_MODE3\r
 501         \95 MSS_SPI_TI_MODE\r
 502         \95 MSS_SPI_NSC_MODE\r
 503  \r
 504   @param clk_rate\r
 505     Divider value used to generate serial interface clock signal from PCLK.\r
 506     Allowed values are:\r
 507         \95 MSS_SPI_PCLK_DIV_2\r
 508         \95 MSS_SPI_PCLK_DIV_4\r
 509         \95 MSS_SPI_PCLK_DIV_8\r
 510         \95 MSS_SPI_PCLK_DIV_16\r
 511         \95 MSS_SPI_PCLK_DIV_32\r
 512         \95 MSS_SPI_PCLK_DIV_64\r
 513         \95 MSS_SPI_PCLK_DIV_128\r
 514         \95 MSS_SPI_PCLK_DIV_256\r
 515         \r
 516   @param frame_bit_length\r
 517     Number of bits making up the frame. The maximum frame length is 32 bits. You\r
 518     must use the MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE constant as the value for\r
 519     frame_bit_length when configuring the MSS SPI master for block transfer\r
 520     transactions with the target SPI slave.\r
 521     \r
 522   Example:\r
 523   @code\r
 524   MSS_SPI_init( &g_mss_spi0 );\r
 525 \r
 526   MSS_SPI_configure_master_mode\r
 527     (\r
 528         &g_mss_spi0,\r
 529         MSS_SPI_SLAVE_0,\r
 530         MSS_SPI_MODE2,\r
 531         MSS_SPI_PCLK_DIV_64,\r
 532         12\r
 533      );\r
 534 \r
 535   MSS_SPI_configure_master_mode\r
 536     (\r
 537         &g_mss_spi0,\r
 538         MSS_SPI_SLAVE_1,\r
 539         MSS_SPI_TI_MODE,\r
 540         MSS_SPI_PCLK_DIV_128,\r
 541         MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
 542      );\r
 543   @endcode\r
 544  */ \r
 545 void MSS_SPI_configure_master_mode\r
 546 (\r
 547         mss_spi_instance_t *    this_spi,\r
 548         mss_spi_slave_t         slave,\r
 549     mss_spi_protocol_mode_t protocol_mode,\r
 550     mss_spi_pclk_div_t      clk_rate,\r
 551     uint8_t                 frame_bit_length\r
 552 );\r
 553 \r
 554 /*==============================================================================\r
 555  * Master functions\r
 556  *============================================================================*/\r
 557 \r
 558 /***************************************************************************//**\r
 559   The MSS_SPI_slave_select() function is used by a MSS SPI master to select a\r
 560   specific slave. This function causes the relevant slave select signal to be\r
 561   asserted.\r
 562  \r
 563   @param this_spi\r
 564     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 565     identifying the MSS SPI hardware block to be initialized. There are two such\r
 566     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 567     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 568     or g_mss_spi1 global data structure defined within the SPI driver.\r
 569     \r
 570  \r
 571   @param slave\r
 572     The slave parameter is one of mss_spi_slave_t enumerated constants\r
 573     identifying a slave.\r
 574   \r
 575   Example:\r
 576   @code\r
 577   const uint8_t frame_size = 25;\r
 578   const uint32_t master_tx_frame = 0x0100A0E1;\r
 579 \r
 580   MSS_SPI_init( &g_mss_spi0 );\r
 581   MSS_SPI_configure_master_mode\r
 582     (\r
 583         &g_mss_spi0,\r
 584         MSS_SPI_SLAVE_0,\r
 585         MSS_SPI_MODE1,\r
 586         MSS_SPI_PCLK_DIV_256,\r
 587         frame_size\r
 588      );\r
 589 \r
 590   MSS_SPI_set_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 591   MSS_SPI_transfer_frame( &g_mss_spi0, master_tx_frame );\r
 592   MSS_SPI_clear_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 593   @endcode\r
 594  */\r
 595 void MSS_SPI_set_slave_select\r
 596 (\r
 597         mss_spi_instance_t * this_spi,\r
 598         mss_spi_slave_t slave\r
 599 );\r
 600 \r
 601 /***************************************************************************//**\r
 602   The MSS_SPI_clear_slave_select() function is used by a MSS SPI Master to\r
 603   deselect a specific slave. This function causes the relevant slave select\r
 604   signal to be de-asserted.\r
 605  \r
 606   @param this_spi\r
 607     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 608     identifying the MSS SPI hardware block to be initialized. There are two such\r
 609     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 610     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 611     or g_mss_spi1 global data structure defined within the SPI driver.\r
 612     \r
 613  \r
 614   @param slave\r
 615     The slave parameter is one of mss_spi_slave_t enumerated constants\r
 616     identifying a slave.\r
 617   \r
 618   Example:\r
 619   @code\r
 620   const uint8_t frame_size = 25;\r
 621   const uint32_t master_tx_frame = 0x0100A0E1;\r
 622 \r
 623   MSS_SPI_init( &g_mss_spi0 );\r
 624   MSS_SPI_configure_master_mode\r
 625     (\r
 626         &g_mss_spi0,\r
 627         MSS_SPI_SLAVE_0,\r
 628         MSS_SPI_MODE1,\r
 629         MSS_SPI_PCLK_DIV_256,\r
 630         frame_size\r
 631      );\r
 632   MSS_SPI_set_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 633   MSS_SPI_transfer_frame( &g_mss_spi0, master_tx_frame );\r
 634   MSS_SPI_clear_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 635   @endcode\r
 636  */\r
 637 void MSS_SPI_clear_slave_select\r
 638 (\r
 639         mss_spi_instance_t * this_spi,\r
 640         mss_spi_slave_t slave\r
 641 );\r
 642 \r
 643 /***************************************************************************//**\r
 644   The MSS_SPI_disable() function is used to temporarily disable a MSS SPI\r
 645   hardware block. This function is typically used in conjunction with the\r
 646   SPI_set_transfer_byte_count() function to setup a DMA controlled SPI transmit\r
 647   transaction as the SPI_set_transfer_byte_count() function must only be used\r
 648   when the MSS SPI hardware is disabled.\r
 649  \r
 650   @param this_spi\r
 651     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 652     identifying the MSS SPI hardware block to be initialized. There are two such\r
 653     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 654     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 655     or g_mss_spi1 global data structure defined within the SPI driver.\r
 656   \r
 657   Example:\r
 658   @code\r
 659   uint32_t transfer_size;\r
 660   uint8_t tx_buffer[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };\r
 661   \r
 662   transfer_size = sizeof(tx_buffer);\r
 663   \r
 664   MSS_SPI_disable( &g_mss_spi0 );\r
 665   MSS_SPI_set_transfer_byte_count( &g_mss_spi0, transfer_size );\r
 666   PDMA_start\r
 667     (\r
 668         PDMA_CHANNEL_0,\r
 669         (uint32_t)tx_buffer,\r
 670         PDMA_SPI1_TX_REGISTER,\r
 671         transfer_size\r
 672     );\r
 673   MSS_SPI_enable( &g_mss_spi0 );\r
 674   \r
 675   while ( !MSS_SPI_tx_done( &g_mss_spi0 ) )\r
 676   {\r
 677       ;\r
 678   }\r
 679   @endcode\r
 680  */\r
 681 static __INLINE void MSS_SPI_disable\r
 682 (\r
 683     mss_spi_instance_t * this_spi\r
 684 )\r
 685 {\r
 686     this_spi->hw_reg_bit->CTRL_ENABLE = 0;\r
 687 }\r
 688 \r
 689 /***************************************************************************//**\r
 690   The MSS_SPI_enable() function is used to re-enable a MSS SPI hardware block\r
 691   after it was disabled using the SPI_disable() function.\r
 692  \r
 693   @param this_spi\r
 694     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 695     identifying the MSS SPI hardware block to be initialized. There are two such\r
 696     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 697     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 698     or g_mss_spi1 global data structure defined within the SPI driver.\r
 699     \r
 700   Example:\r
 701   @code\r
 702   uint32_t transfer_size;\r
 703   uint8_t tx_buffer[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };\r
 704   \r
 705   transfer_size = sizeof(tx_buffer);\r
 706   \r
 707   MSS_SPI_disable( &g_mss_spi0 );\r
 708   MSS_SPI_set_transfer_byte_count( &g_mss_spi0, transfer_size );\r
 709   PDMA_start\r
 710     (\r
 711         PDMA_CHANNEL_0,\r
 712         (uint32_t)tx_buffer,\r
 713         PDMA_SPI1_TX_REGISTER,\r
 714         transfer_size\r
 715     );\r
 716   MSS_SPI_enable( &g_mss_spi0 );\r
 717   \r
 718   while ( !MSS_SPI_tx_done( &g_mss_spi0 ) )\r
 719   {\r
 720       ;\r
 721   }\r
 722   @endcode\r
 723  */\r
 724 static __INLINE void MSS_SPI_enable\r
 725 (\r
 726     mss_spi_instance_t * this_spi\r
 727 )\r
 728 {\r
 729     this_spi->hw_reg_bit->CTRL_ENABLE = 1;\r
 730 }\r
 731 \r
 732 /***************************************************************************//**\r
 733   The MSS_SPI_set_transfer_byte_count() function is used as part of setting up\r
 734   a SPI transfer using DMA. It specifies the number of bytes that must be\r
 735   transferred before MSS_SPI_tx_done() indicates that the transfer is complete.\r
 736  \r
 737   @param this_spi\r
 738     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 739     identifying the MSS SPI hardware block to be initialized. There are two such\r
 740     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 741     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 742     or g_mss_spi1 global data structure defined within the SPI driver.\r
 743     \r
 744  \r
 745   @param byte_count\r
 746     The byte_count parameter specifies the number of bytes that must be\r
 747     transferred by the SPI hardware block considering that a transaction has\r
 748     been completed.\r
 749   \r
 750   Example:\r
 751   @code\r
 752   uint32_t transfer_size;\r
 753   uint8_t tx_buffer[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };\r
 754   \r
 755   transfer_size = sizeof(tx_buffer);\r
 756   \r
 757   MSS_SPI_disable( &g_mss_spi0 );\r
 758   \r
 759   MSS_SPI_set_transfer_byte_count( &g_mss_spi0, transfer_size );\r
 760   \r
 761   PDMA_start( PDMA_CHANNEL_0, (uint32_t)tx_buffer, 0x40011014, transfer_size );\r
 762   \r
 763   MSS_SPI_enable( &g_mss_spi0 );\r
 764   \r
 765   while ( !MSS_SPI_tx_done( &g_mss_spi0) )\r
 766   {\r
 767       ;\r
 768   }\r
 769   @endcode\r
 770  */\r
 771 static __INLINE void MSS_SPI_set_transfer_byte_count\r
 772 (\r
 773     mss_spi_instance_t * this_spi,\r
 774     uint16_t byte_count\r
 775 )\r
 776 {\r
 777     const uint32_t TXRXDFCOUNT_SHIFT = 8U;\r
 778     const uint32_t TXRXDFCOUNT_MASK = 0x00FFFF00U;\r
 779     \r
 780     this_spi->hw_reg->CONTROL = (this_spi->hw_reg->CONTROL & ~TXRXDFCOUNT_MASK) | ( (byte_count << TXRXDFCOUNT_SHIFT) & TXRXDFCOUNT_MASK);\r
 781     this_spi->hw_reg->TXRXDF_SIZE = 8U;\r
 782 }\r
 783 \r
 784 /***************************************************************************//**\r
 785   The MSS_SPI_tx_done() function is used to find out if a DMA controlled transfer\r
 786   has completed.\r
 787  \r
 788   @param this_spi\r
 789     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 790     identifying the MSS SPI hardware block to be initialized. There are two such\r
 791     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 792     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 793     or g_mss_spi1 global data structure defined within the SPI driver.\r
 794   \r
 795   Example:\r
 796   @code\r
 797       uint32_t transfer_size;\r
 798       uint8_t tx_buffer[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };\r
 799       \r
 800       transfer_size = sizeof(tx_buffer);\r
 801       \r
 802       MSS_SPI_disable( &g_mss_spi0 );\r
 803       \r
 804       MSS_SPI_set_transfer_byte_count( &g_mss_spi0, transfer_size );\r
 805       \r
 806       PDMA_start\r
 807         (\r
 808             PDMA_CHANNEL_0,\r
 809             (uint32_t)tx_buffer,\r
 810             PDMA_SPI1_TX_REGISTER,\r
 811             transfer_size\r
 812         );\r
 813       \r
 814       MSS_SPI_enable( &g_mss_spi0 );\r
 815       \r
 816       while ( !MSS_SPI_tx_done(&g_mss_spi0) )\r
 817       {\r
 818           ;\r
 819       }\r
 820   @endcode\r
 821  */\r
 822 static __INLINE uint32_t MSS_SPI_tx_done\r
 823 (\r
 824     mss_spi_instance_t * this_spi\r
 825 )\r
 826 {\r
 827     return this_spi->hw_reg_bit->STATUS_TX_DONE;\r
 828 }\r
 829 \r
 830 /***************************************************************************//**\r
 831   The MSS_SPI_transfer_frame() function is used by a MSS SPI master to transmit\r
 832   and receive a frame up to 32 bits long. This function is typically used for\r
 833   transactions with a SPI slave where the number of transmit and receive bits is\r
 834   not divisible by 8.\r
 835  \r
 836   @param this_spi\r
 837     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 838     identifying the MSS SPI hardware block to be initialized. There are two such\r
 839     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 840     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 841     or g_mss_spi1 global data structure defined within the SPI driver.\r
 842     \r
 843  \r
 844   @param tx_bits\r
 845     The tx_bits parameter is a 32 bits word containing the value that will be\r
 846     transmitted.\r
 847     Note:   The bit length of the value to be transmitted to the slave must be\r
 848             specified as the frame_bit_length parameter in a previous call to\r
 849             the MSS_SPI_configure_master() function.\r
 850 \r
 851   @return\r
 852     This function returns a 32 bits word containing the value that is received\r
 853     from the slave.\r
 854  \r
 855   Example:\r
 856   @code\r
 857       const uint8_t frame_size = 25;\r
 858       const uint32_t master_tx_frame = 0x0100A0E1;\r
 859       uint32_t master_rx;\r
 860       \r
 861       MSS_SPI_init( &g_mss_spi0 );\r
 862       MSS_SPI_configure_master_mode\r
 863         (\r
 864             &g_mss_spi0,\r
 865             MSS_SPI_SLAVE_0,\r
 866             MSS_SPI_MODE1,\r
 867             MSS_SPI_PCLK_DIV_256,\r
 868             frame_size\r
 869          );\r
 870      \r
 871       MSS_SPI_set_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 872       master_rx = MSS_SPI_transfer_frame( &g_mss_spi0, master_tx_frame );\r
 873       MSS_SPI_clear_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 874   @endcode\r
 875  */\r
 876 uint32_t MSS_SPI_transfer_frame\r
 877 (\r
 878     mss_spi_instance_t * this_spi,\r
 879     uint32_t tx_bits\r
 880 );\r
 881 \r
 882 /***************************************************************************//**\r
 883   The MSS_SPI_transfer_block() function is used by MSS SPI masters to transmit\r
 884   and receive blocks of data organized as a specified number of bytes. It can be\r
 885   used for:\r
 886     \95 Writing a data block to a slave\r
 887     \95 Reading a data block from a slave\r
 888     \95 Sending a command to a slave followed by reading the outcome of the\r
 889       command in a single SPI transaction. This function can be used alongside\r
 890       Peripheral DMA functions to perform the actual moving to and from the SPI\r
 891       hardware block using Peripheral DMA.\r
 892  \r
 893   @param this_spi\r
 894     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
 895     identifying the MSS SPI hardware block to be initialized. There are two such\r
 896     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
 897     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
 898     or g_mss_spi1 global data structure defined within the SPI driver.\r
 899     \r
 900  \r
 901   @param cmd_buffer\r
 902     The cmd_buffer parameter is a pointer to the buffer containing the data that\r
 903     will be sent by the master from the beginning of the transfer. This pointer\r
 904     can be null (0) if the master does not need to send a command before reading\r
 905     data or if the command part of the transfer is written to the SPI hardware\r
 906     block using DMA.\r
 907  \r
 908   @param cmd_byte_size\r
 909     The cmd_byte_size parameter specifies the number of bytes contained in\r
 910     cmd_buffer that will be sent. A value of 0 indicates that no data needs to\r
 911     be sent to the slave. A non-zero value while the cmd_buffer pointer is 0 is\r
 912     used to indicate that the command data will be written to the SPI hardware\r
 913     block using DMA.\r
 914  \r
 915   @param rd_buffer\r
 916     The rd_buffer parameter is a pointer to the buffer where the data received\r
 917     from the slave after the command has been sent will be stored.\r
 918  \r
 919   @param rd_byte_size\r
 920     The rd_byte_size parameter specifies the number of bytes to be received from\r
 921     the slave and stored in the rd_buffer. A value of 0 indicates that no data\r
 922     is to be read from the slave. A non-zero value while the rd_buffer pointer\r
 923     is null (0) is used to specify the receive size when using DMA to read from\r
 924     the slave. \r
 925     Note:   All bytes received from the slave, including the bytes received\r
 926             while the command is sent, will be read through DMA.\r
 927   \r
 928   Polled write transfer example:\r
 929   @code\r
 930       uint8_t master_tx_buffer[MASTER_TX_BUFFER] = \r
 931       {\r
 932           0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A\r
 933       };\r
 934       MSS_SPI_init( &g_mss_spi0 );\r
 935       MSS_SPI_configure_master_mode\r
 936         (\r
 937             &g_mss_spi0,\r
 938             MSS_SPI_SLAVE_0,\r
 939             MSS_SPI_MODE1,\r
 940             MSS_SPI_PCLK_DIV_256,\r
 941             MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
 942          );\r
 943      \r
 944       MSS_SPI_set_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 945       MSS_SPI_transfer_block\r
 946         (\r
 947             &g_mss_spi0,\r
 948             master_tx_buffer,\r
 949             sizeof(master_tx_buffer),\r
 950             0,\r
 951             0\r
 952         );\r
 953       MSS_SPI_clear_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 954   @endcode\r
 955  \r
 956   DMA transfer example:\r
 957   In this example the transmit and receive buffers are not specified as part of\r
 958   the call to MSS_SPI_transfer_block(). MSS_SPI_transfer_block() will only\r
 959   prepare the MSS SPI hardware for a transfer. The MSS SPI transmit hardware\r
 960   FIFO is filled using one DMA channel and a second DMA channel is used to read\r
 961   the content of the MSS SPI receive hardware FIFO. The transmit and receive\r
 962   buffers are specified by two separate calls to PDMA_start() to initiate DMA\r
 963   transfers on the channel used for transmit data and the channel used for\r
 964   receive data. \r
 965   @code\r
 966       uint8_t master_tx_buffer[MASTER_RX_BUFFER] =\r
 967       {\r
 968           0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA\r
 969       };\r
 970       uint8_t slave_rx_buffer[MASTER_RX_BUFFER] = \r
 971       {\r
 972           0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A\r
 973       };\r
 974       MSS_SPI_init( &g_mss_spi0 );\r
 975 \r
 976       MSS_SPI_configure_master_mode\r
 977           (\r
 978             &g_mss_spi0,\r
 979             MSS_SPI_SLAVE_0,\r
 980             MSS_SPI_MODE1,\r
 981             MSS_SPI_PCLK_DIV_256,\r
 982             MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
 983          );\r
 984       MSS_SPI_set_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
 985       MSS_SPI_transfer_block( &g_mss_spi0, 0, 0, 0, 0 );\r
 986       PDMA_start\r
 987         (\r
 988             PDMA_CHANNEL_1,\r
 989             PDMA_SPI0_RX_REGISTER,\r
 990             (uint32_t)master_rx_buffer,\r
 991             sizeof(master_rx_buffer)\r
 992         ); \r
 993       PDMA_start\r
 994         (\r
 995             PDMA_CHANNEL_2,\r
 996             (uint32_t)master_tx_buffer,\r
 997             PDMA_SPI0_TX_REGISTER,\r
 998             sizeof(master_tx_buffer)\r
 999         ); \r
1000       while( PDMA_status(PDMA_CHANNEL_1) == 0 )\r
1001       {\r
1002           ;\r
1003       }\r
1004       MSS_SPI_clear_slave_select( &g_mss_spi0, MSS_SPI_SLAVE_0 );\r
1005   @endcode\r
1006  */\r
1007 void MSS_SPI_transfer_block\r
1008 (\r
1009     mss_spi_instance_t * this_spi,\r
1010     const uint8_t * cmd_buffer,\r
1011     uint16_t cmd_byte_size,\r
1012     uint8_t * rd_buffer,\r
1013     uint16_t rd_byte_size\r
1014 );\r
1015 \r
1016 /*==============================================================================\r
1017  * Slave functions\r
1018  *============================================================================*/\r
1019 \r
1020 /***************************************************************************//**\r
1021   The MSS_SPI_set_frame_rx_handler() function is used by MSS SPI slaves to\r
1022   specify the receive handler function that will be called by the MSS SPI driver\r
1023   interrupt handler when a a frame of data is received by the MSS SPI slave.\r
1024   \r
1025   @param this_spi\r
1026     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
1027     identifying the MSS SPI hardware block to be initialized. There are two such\r
1028     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
1029     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
1030     or g_mss_spi1 global data structure defined within the SPI driver.\r
1031     \r
1032  \r
1033   @param rx_handler\r
1034     The rx_handler parameter is a pointer to the frame receive handler that must\r
1035     be called when a frame is received by the MSS SPI slave.\r
1036  \r
1037   Example:\r
1038   @code\r
1039       uint32_t g_slave_rx_frame = 0;\r
1040 \r
1041       void slave_frame_handler( uint32_t rx_frame )\r
1042       {\r
1043           g_slave_rx_frame = rx_frame;\r
1044       }\r
1045 \r
1046       int setup_slave( void )\r
1047       {\r
1048           const uint16_t frame_size = 25;\r
1049           MSS_SPI_init( &g_mss_spi1 );\r
1050           MSS_SPI_configure_slave_mode\r
1051             (\r
1052                 &g_mss_spi0,\r
1053                 MSS_SPI_MODE2,\r
1054                 MSS_SPI_PCLK_DIV_64,\r
1055                 frame_size\r
1056             );\r
1057           MSS_SPI_set_frame_rx_handler( &g_mss_spi1, slave_frame_handler );\r
1058       }\r
1059   @endcode\r
1060  */\r
1061 void MSS_SPI_set_frame_rx_handler\r
1062 (\r
1063     mss_spi_instance_t * this_spi,\r
1064     mss_spi_frame_rx_handler_t rx_handler\r
1065 );\r
1066 \r
1067 /***************************************************************************//**\r
1068   The MSS_SPI_set_slave_tx_frame() function is used by MSS SPI slaves to specify\r
1069   the frame that will be transmitted when a transaction is initiated by the SPI\r
1070   master.\r
1071   \r
1072   @param this_spi\r
1073     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
1074     identifying the MSS SPI hardware block to be initialized. There are two such\r
1075     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
1076     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
1077     or g_mss_spi1 global data structure defined within the SPI driver.\r
1078     \r
1079  \r
1080   @param frame_value\r
1081     The frame_value parameter contains the value of the frame to be sent to the\r
1082     master.\r
1083     Note:   The bit length of the value to be transmitted to the master must be\r
1084             specified as the frame_bit_length parameter in a previous call to\r
1085             the MSS_SPI_configure_slave() function.\r
1086 \r
1087   Example:\r
1088   @code\r
1089       const uint16_t frame_size = 25;\r
1090       const uint32_t slave_tx_frame = 0x0110F761;\r
1091       uint32_t master_rx;\r
1092 \r
1093       MSS_SPI_init( &g_mss_spi1 );\r
1094       MSS_SPI_configure_slave_mode\r
1095         (\r
1096             &g_mss_spi0,\r
1097             MSS_SPI_MODE2,\r
1098             MSS_SPI_PCLK_DIV_64,\r
1099             frame_size\r
1100         );\r
1101       MSS_SPI_set_slave_tx_frame( &g_mss_spi1, slave_tx_frame );\r
1102   @endcode\r
1103  */\r
1104 void MSS_SPI_set_slave_tx_frame\r
1105 (\r
1106     mss_spi_instance_t * this_spi,\r
1107     uint32_t frame_value\r
1108 );\r
1109 \r
1110 /***************************************************************************//**\r
1111   The MSS_SPI_set_slave_block_buffers() function is used to configure an MSS\r
1112   SPI slave for block transfer operations. It specifies one or more of the\r
1113   following:\r
1114     \95 The data that will be transmitted when accessed by a master.\r
1115     \95 The buffer where data received from a master will be stored.\r
1116     \95 The handler function that must be called after the receive buffer has been\r
1117       filled.\r
1118     \95 The number of bytes that must be received from the master before the receive\r
1119       handler function is called.\r
1120   These parameters allow the following use cases:\r
1121     \95 Slave performing an action after receiving a block of data from a master\r
1122       containing a command. The action will be performed by the receive handling\r
1123       based on the content of the receive data buffer.\r
1124     \95 Slave returning a block of data to the master. The type of information is\r
1125       always the same but the actual values change over time. For example,\r
1126       returning the voltage of a predefined set of analog inputs.\r
1127     \95 Slave returning data based on a command contained in the first part of the\r
1128       SPI transaction. For example, reading the voltage of the analog input\r
1129       specified by the first data byte by the master. This is achieved by setting\r
1130       the rx_buff_size parameter to the number of received bytes making up the\r
1131       command.\r
1132   \r
1133   @param this_spi\r
1134     The this_spi parameter is a pointer to an mss_spi_instance_t structure\r
1135     identifying the MSS SPI hardware block to be initialized. There are two such\r
1136     data structures, g_mss_spi0 and g_mss_spi1, associated with MSS SPI 0 and\r
1137     MSS SPI 1 respectively. This parameter must point to either the g_mss_spi0\r
1138     or g_mss_spi1 global data structure defined within the SPI driver.\r
1139     \r
1140  \r
1141   @param tx_buffer\r
1142     The tx_buffer parameter is a pointer to a buffer containing the data that\r
1143     will be sent to the master. This parameter can be set to 0 if the MSS SPI\r
1144     slave is not intended to be the target of SPI read transactions or if DMA\r
1145     is used to transfer SPI read data into the MSS SPI slave.\r
1146  \r
1147   @param tx_buff_size\r
1148     The tx_buff_size parameter specifies the number of bytes contained in the\r
1149     tx_buffer. This parameter can be set to 0 if the MSS SPI slave is not\r
1150     intended to be the target of SPI read transactions or if DMA is used to\r
1151     transfer SPI read data into the MSS SPI slave.\r
1152  \r
1153   @param rx_buffer\r
1154     The rx_buffer parameter is a pointer to the buffer where data received from\r
1155     the master will be stored. This parameter can be set to 0 if the MSS SPI\r
1156     slave is not intended to be the target of SPI write or write-read\r
1157     transactions. It can also set to 0 if the MSS SPI slave uses DMA to handle\r
1158     data written to it.\r
1159  \r
1160   @param rx_buff_size\r
1161     The rx_buff_size parameter specifies the size of the receive buffer. It is\r
1162     also the number of bytes that must be received before the receive handler\r
1163     is called, if a receive handler is specified using the block_rx_handler\r
1164     parameter. This parameter can be set to 0 if the MSS SPI slave is not\r
1165     intended to be the target of SPI write or write-read transactions. It can\r
1166     also set to 0 if the MSS SPI slave uses DMA to handle data written to it.\r
1167  \r
1168   @param block_rx_handler\r
1169     The block_rx_handler parameter is a pointer to a function that will be\r
1170     called when the receive buffer has been filled. This parameter can be set\r
1171     to 0 if the MSS SPI slave is not intended to be the target of SPI write or\r
1172     write-read transactions. It can also set to 0 if the MSS SPI slave uses DMA\r
1173     to handle data written to it.\r
1174  \r
1175   Slave performing operation based on master command:\r
1176   In this example the SPI slave is configured to receive 10 bytes of data or\r
1177   command from the SPI slave and process the data received from the master.\r
1178   @code\r
1179      uint32_t nb_of_rx_handler_calls = 0;\r
1180      \r
1181      void spi1_block_rx_handler_b\r
1182      (\r
1183          uint8_t * rx_buff,\r
1184          uint16_t rx_size\r
1185      )\r
1186      {\r
1187          ++nb_of_rx_handler_calls;\r
1188      }\r
1189      \r
1190      void setup_slave( void )\r
1191      {\r
1192          uint8_t slave_rx_buffer[10] = \r
1193          {\r
1194              0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00\r
1195          };\r
1196          \r
1197          MSS_SPI_init( &g_mss_spi1 );\r
1198          MSS_SPI_configure_slave_mode\r
1199             ( \r
1200                 &g_mss_spi0,\r
1201                 MSS_SPI_MODE2,\r
1202                 MSS_SPI_PCLK_DIV_64,\r
1203                 MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
1204             );\r
1205          \r
1206          MSS_SPI_set_slave_block_buffers\r
1207              (\r
1208                  &g_mss_spi1,\r
1209                  0,\r
1210                  0,\r
1211                  slave_rx_buffer,\r
1212                  sizeof(master_tx_buffer),\r
1213                  spi1_block_rx_handler_b\r
1214              );\r
1215      }\r
1216   @endcode\r
1217   \r
1218   Slave responding to command example:\r
1219   In this example the slave will return data based on a command sent by the\r
1220   master. The first part of the transaction is handled using polled mode where\r
1221   each byte returned to the master is written as part of the interrupt service\r
1222   routine. The second part of the transaction, where the slave returns data\r
1223   based on the command value, is sent using a DMA transfer initiated by the\r
1224   receive handler. \r
1225   @code\r
1226      static uint8_t g_spi1_tx_buffer_b[SLAVE_TX_BUFFER_SIZE] =\r
1227      {\r
1228          5, 6, 7, 8, 0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5\r
1229      };\r
1230      \r
1231      void spi1_block_rx_handler\r
1232      (\r
1233          uint8_t * rx_buff,\r
1234          uint16_t rx_size\r
1235      )\r
1236      {\r
1237          if ( rx_buff[2] == 0x99 )\r
1238          {\r
1239              PDMA_start\r
1240              (\r
1241                  PDMA_CHANNEL_0,\r
1242                  (uint32_t)g_spi1_tx_buffer_b,\r
1243                  0x40011014,\r
1244                  sizeof(g_spi1_tx_buffer_b)\r
1245              );      \r
1246          }\r
1247      }\r
1248      \r
1249      void setup_slave( void )\r
1250      {\r
1251          uint8_t slave_preamble[8] = { 9, 10, 11, 12, 13, 14, 16, 16 };\r
1252 \r
1253          MSS_SPI_init( &g_mss_spi1 );\r
1254          MSS_SPI_configure_slave_mode\r
1255             (\r
1256                 &g_mss_spi0,\r
1257                 MSS_SPI_MODE2,\r
1258                 MSS_SPI_PCLK_DIV_64,\r
1259                 MSS_SPI_BLOCK_TRANSFER_FRAME_SIZE\r
1260         );\r
1261          \r
1262          PDMA_init();\r
1263          PDMA_configure\r
1264               (\r
1265                   PDMA_CHANNEL_0, \r
1266                   TO_SPI_1,\r
1267                   LOW_PRIORITY | BYTE_TRANSFER | INC_SRC_ONE_BYTE\r
1268               );\r
1269      \r
1270          MSS_SPI_set_slave_block_buffers\r
1271              (\r
1272                  &g_mss_spi1,\r
1273                  slave_preamble,\r
1274                  4,\r
1275                  g_spi1_rx_buffer,\r
1276                  sizeof(g_spi1_rx_buffer),\r
1277                  spi1_block_rx_handler\r
1278              );\r
1279      }\r
1280   @endcode\r
1281  */\r
1282 void MSS_SPI_set_slave_block_buffers\r
1283 (\r
1284     mss_spi_instance_t * this_spi,\r
1285     const uint8_t * tx_buffer,\r
1286     uint32_t tx_buff_size,\r
1287     uint8_t * rx_buffer,\r
1288     uint32_t rx_buff_size,\r
1289     mss_spi_block_rx_handler_t block_rx_handler\r
1290 );\r
1291 \r
1292 #ifdef __cplusplus\r
1293 }\r
1294 #endif\r
1295 \r
1296 #endif /* MSS_SPI_H_*/\r