include/Spi.h

   1 /* -------------------------------- Arctic Core ------------------------------\r
   2  * Arctic Core - the open source AUTOSAR platform http://arccore.com\r
   3  *\r
   4  * Copyright (C) 2009  ArcCore AB <contact@arccore.com>\r
   5  *\r
   6  * This source code is free software; you can redistribute it and/or modify it\r
   7  * under the terms of the GNU General Public License version 2 as published by the\r
   8  * Free Software Foundation; See <http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt>.\r
   9  *\r
  10  * This program is distributed in the hope that it will be useful, but\r
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY\r
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License\r
  13  * for more details.\r
  14  * -------------------------------- Arctic Core ------------------------------*/\r
  15 \r
  16 #ifndef SPI_H_\r
  17 #define SPI_H_\r
  18 \r
  19 #include "Std_Types.h"\r
  20 \r
  21 \r
  22 /* STD container : SpiGeneral\r
  23  * SPI_CANCEL_API                                       1         Bool\r
  24  * SPI_CHANNEL_BUFFERS_ALLOWED          1         Int 0..2\r
  25  * SPI_DEV_ERROR_DETECT                         1         Bool\r
  26  * SPI_HW_STATUS_API                            1         Bool\r
  27  * SPI_INTERRUPTABLE_SEQ_ALLOWED        1         Bool\r
  28  * SPI_LEVEL_DELIVERED                          1     Int 0..2\r
  29  * SPI_VERSION_INFO_API                         1     Bool\r
  30  */\r
  31 \r
  32 /* SPI container: SpiSequence\r
  33  * SpiInterruptableSequence                     1     Bool\r
  34  * SpiSeqEndNotification                        1     Func\r
  35  * SpiSequenceId                                        1     Int     (name of the sequence)\r
  36  * JobAssignment                                        1..*  Ref to SpiJob\r
  37  */\r
  38 \r
  39 /* SPI container: SpiChannel\r
  40  * SpiChannelId                                         1     Int ( name of the channel )\r
  41  * SpiChannelType                                       1         enum IB, EB\r
  42  * SpiDataWidth                                         1         Int, 1..32\r
  43  * SpiDefaultData                                       1     Int\r
  44  * SpiEbMaxLength                                       1         Int\r
  45  * SpiHwUnitSynchronous                         0..1                    [New in 4.0]\r
  46  * SpiIbNBuffers                                        1         Int\r
  47  * SpiTransferStart                             1     Enum LSB, MSB\r
  48  */\r
  49 \r
  50 /* SPI container: SpiJob\r
  51  * SpiHwUnit                                            1     Enum, CSIB0,CSIB1,CSIB2,CSIB3\r
  52  * SpiJobEndNotification                        1         Func\r
  53  * SpiJobId                                             1         Int ( name of job )\r
  54  * SpiJobPriority                                       1         Int 0..3\r
  55  * ChannelAssignment                            1..*  Ref to channel\r
  56  * DeviceAssignment                                     1         Ref to exteral device\r
  57  */\r
  58 \r
  59 /* SPI container: SpiExternalDevice\r
  60  * SpiBaudrate                                          1     float\r
  61  * SpiCsIdentifier                                      1         String\r
  62  * SpiCsPolarity                                        1     enum, HIGH, LOW\r
  63  * SpiDataShiftEdge                                     1         enum LEADING, TRAILING\r
  64  * SpiEnableCs                                          1         Bool\r
  65  * SpiShiftClockIdleLevel                       1         Enum, HIGH, LOW\r
  66  * SpiTimeClk2Cs                                        1     float\r
  67  */\r
  68 \r
  69 /* SPI container: SpiDriver\r
  70  * SpiMaxChannel                                        0..1  Int\r
  71  * SpiMaxJob                                            0..1  Int\r
  72  * SpiMaxSequence                                       0..1  Int\r
  73  * SpiChannel[c]                                        1..*  Channel Data\r
  74  * SpiExternalDevice[c]                         1..*  External device data\r
  75  * SpiJob[c]                                            1..*  Job data\r
  76  * SpiSequence[c]                                       1..*  Sequence data.\r
  77   */\r
  78 \r
  79 \r
  80 /* Standard info */\r
  81 #define SPI_VENDOR_ID             1\r
  82 #define SPI_MODULE_ID                    MODULE_ID_SPI\r
  83 #define SPI_SW_MAJOR_VERSION      1\r
  84 #define SPI_SW_MINOR_VERSION      0\r
  85 #define SPI_SW_PATCH_VERSION      2\r
  86 /* Part of release 3.0 rev 0001 */\r
  87 #define SPI_AR_MAJOR_VERSION      3\r
  88 #define SPI_AR_MINOR_VERSION      0\r
  89 #define SPI_AR_PATCH_VERSION      0\r
  90 \r
  91 \r
  92 /* --- Service IDs --- */\r
  93 #define SPI_INIT_SERVICE_ID               0x00\r
  94 #define SPI_DEINIT_SERVICE_ID             0x01\r
  95 #define SPI_WRITEIB_SERVICE_ID            0x02\r
  96 #define SPI_ASYNCTRANSMIT_SERVICE_ID      0x03\r
  97 #define SPI_READIB_SERVICE_ID             0x04\r
  98 #define SPI_SETUPEB_SERVICE_ID            0x05\r
  99 #define SPI_GETSTATUS_SERVICE_ID          0x06\r
 100 #define SPI_GETJOBRESULT_SERVICE_ID       0x07\r
 101 #define SPI_GETSEQUENCERESULT_SERVICE_ID  0x08\r
 102 #define SPI_GETVERSIONINFO_SERVICE_ID     0x09\r
 103 #define SPI_SYNCTRANSMIT_SERVICE_ID       0x0A\r
 104 #define SPI_GETHWUNITSTATUS_SERVICE_ID    0x0B\r
 105 #define SPI_CANCEL_SERVICE_ID             0x0C\r
 106 #define SPI_SETASYNCMODE_SERVICE_ID       0x0D\r
 107 \r
 108 /* --- Error codes --- */\r
 109 #define SPI_E_PARAM_CHANNEL               0x0A\r
 110 #define SPI_E_PARAM_JOB                   0x0B\r
 111 #define SPI_E_PARAM_SEQ                   0x0C\r
 112 #define SPI_E_PARAM_LENGTH                0x0D\r
 113 #define SPI_E_PARAM_UNIT                  0x0E\r
 114 #define SPI_E_UNINIT                      0x1A\r
 115 #define SPI_E_SEQ_PENDING                 0x2A\r
 116 #define SPI_E_SEQ_IN_PROCESS              0x3A\r
 117 #define SPI_E_ALREADY_INITIALIZED         0x4A\r
 118 \r
 119 \r
 120 \r
 121 #if 1\r
 122 #define CH_NOT_VALID    (0xff)\r
 123 #define JOB_NOT_VALID   (0xffff)\r
 124 #define SEQ_NOT_VALID   (0xff)\r
 125 \r
 126 /* Types according to standard */\r
 127 typedef uint8_t Spi_ChannelType ;\r
 128 typedef uint16_t Spi_JobType;\r
 129 typedef uint8_t Spi_SequenceType;\r
 130 #else\r
 131 \r
 132 #define CH_NOT_VALID    (-1)\r
 133 #define JOB_NOT_VALID   (-1)\r
 134 #define SEQ_NOT_VALID   (-1)\r
 135 \r
 136 typedef uint8_t Spi_ChannelType ;\r
 137 typedef uint16_t Spi_JobType;\r
 138 typedef uint8_t Spi_SequenceType;\r
 139 \r
 140 #endif\r
 141 \r
 142 #define SPI_SIMPLE         0   /* Not implemented, NOT TESTED */\r
 143 #define SPI_FIFO           1\r
 144 #define SPI_DMA            2\r
 145 \r
 146 #define SPI_EB_MAX_LENGTH 64\r
 147 \r
 148 #define CSIB0   0\r
 149 #define CSIB1   1\r
 150 #define CSIB2   2\r
 151 #define CSIB3   3\r
 152 \r
 153 typedef enum {\r
 154         SPI_UNINIT=0, // The SPI Handler/Driver is not initialized or not usable.\r
 155                                 // SPI011: This shall be the default value after reset. This\r
 156                         // status shall have the value 0.\r
 157 \r
 158         SPI_IDLE,       // The SPI Handler/Driver is not currently transmitting any\r
 159                         // Job.\r
 160 \r
 161         SPI_BUSY,       // The SPI Handler/Driver is performing a SPI Job( transmit )\r
 162 } Spi_StatusType;\r
 163 \r
 164 typedef enum {\r
 165         SPI_JOB_OK=0,           // The last transmission of the Job has been finished\r
 166                                         // successfully.\r
 167                                         // SPI012: This shall be the default value after reset.\r
 168                                         // This status shall have the value 0.\r
 169 \r
 170         SPI_JOB_PENDING,        // The SPI Handler/Driver is performing a SPI Job.\r
 171                                                 // The meaning of this status is equal to SPI_BUSY.\r
 172 \r
 173         SPI_JOB_FAILED,         // The last transmission of the Job has failed.\r
 174 } Spi_JobResultType;\r
 175 \r
 176 typedef enum {\r
 177 \r
 178         SPI_SEQ_OK,     //      The last transmission of the Sequence has been\r
 179                                         //    finished successfully.\r
 180                                         //    SPI017: This shall be the default value after reset.\r
 181                                         //    This status shall have the value 0.\r
 182 \r
 183         SPI_SEQ_PENDING, // The SPI Handler/Driver is performing a SPI\r
 184                         // Sequence. The meaning of this status is equal to\r
 185                         // SPI_BUSY.\r
 186 \r
 187         SPI_SEQ_FAILED,         // The last transmission of the Sequence has failed.\r
 188 \r
 189         SPI_SEQ_CANCELLED,      // The last transmission of the Sequence has been\r
 190                                         //    cancelled by user.\r
 191 } Spi_SeqResultType;\r
 192 \r
 193 \r
 194 // Type for defining the number of data elements of the type Spi_DataType to\r
 195 // send and / or receive by Channel\r
 196 typedef uint16 Spi_NumberOfDataType;\r
 197 \r
 198 \r
 199 // Specifies the asynchronous mechanism mode for SPI busses handled\r
 200 // asynchronously in LEVEL 2.\r
 201 // SPI150: This type is available or not accordint to the pre compile time parameter:\r
 202 // SPI_LEVEL_DELIVERED. This is only relevant for LEVEL 2.\r
 203 \r
 204 typedef enum {\r
 205 \r
 206         //      The asynchronous mechanism is ensured by\r
 207         //    polling, so interrupts related to SPI busses\r
 208         //    handled asynchronously are disabled.\r
 209         SPI_POLLING_MODE,\r
 210 \r
 211         //    The asynchronous mechanism is ensured by\r
 212         //    interrupt, so interrupts related to SPI busses\r
 213         //    handled asynchronously are enabled.\r
 214 \r
 215         SPI_INTERRUPT_MODE,\r
 216 } Spi_AsyncModeType;\r
 217 \r
 218 typedef enum\r
 219 {\r
 220   SPI_EB = 0, // External Buffer\r
 221   SPI_IB // Internal Buffer\r
 222 } Spi_BufferType;\r
 223 \r
 224 typedef enum\r
 225 {\r
 226   SPI_TRANSFER_START_LSB,\r
 227   SPI_TRANSFER_START_MSB,\r
 228 } Spi_TransferStartType;\r
 229 \r
 230 \r
 231 typedef enum {\r
 232         SPI_EDGE_LEADING,\r
 233         SPI_EDGE_TRAILING\r
 234 } Spi_EdgeType;\r
 235 \r
 236 \r
 237 #include "Spi_Cfg.h"\r
 238 #if (SPI_IMPLEMENTATION==SPI_DMA)\r
 239 #include "Dma.h"\r
 240 #endif\r
 241 \r
 242 // All data needed to configure one SPI-channel\r
 243 typedef struct Spi_ChannelConfig\r
 244 {\r
 245   // Symbolic name\r
 246   Spi_ChannelType SpiChannelId;\r
 247   // Buffer usage with EB/IB channel\r
 248   Spi_BufferType SpiChannelType;\r
 249 \r
 250   // This parameter is the width of a transmitted data unit.\r
 251   uint32 SpiDataWidth;\r
 252   // This parameter is the default value to transmit.\r
 253   uint32 SpiDefaultData;\r
 254 \r
 255   // This parameter contains the maximum size of data buffers in case of EB\r
 256   // Channels and only.\r
 257   Spi_NumberOfDataType SpiEbMaxLength;\r
 258 \r
 259   // This parameter contains the maximum number of data buffers in case of IB\r
 260   // Channels and only.\r
 261   Spi_NumberOfDataType SpiIbNBuffers;\r
 262 \r
 263   // This parameter defines the first starting bit for transmission.\r
 264   Spi_TransferStartType SpiTransferStart;\r
 265 \r
 266   //\r
 267 //  _Bool SpiDmaNoIncreaseSrc;\r
 268 \r
 269 } Spi_ChannelConfigType;\r
 270 \r
 271 // All data needed to configure one SPI-Job, amongst others the connection\r
 272 // between the internal SPI unit and the special settings for an external de-\r
 273 // vice is done.\r
 274 typedef struct Spi_JobConfig\r
 275 {\r
 276 \r
 277   Spi_JobType SpiJobId;\r
 278 \r
 279   //    This parameter is the symbolic name to identify the HW SPI Hardware micro-\r
 280   //    controller peripheral allocated to this Job.\r
 281   uint32 SpiHwUnit;\r
 282 \r
 283   // This parameter is a reference to a notification function.\r
 284   void (*SpiJobEndNotification)();\r
 285 \r
 286   // Priority of the Job\r
 287   // range 0..3\r
 288   unsigned SpiJobPriority;\r
 289 \r
 290   // A job references several channels. TODO: Optimize this...\r
 291   Spi_ChannelType ChannelAssignment[SPI_MAX_CHANNEL+1];\r
 292 \r
 293   // Reference to the external device used by this job\r
 294   Spi_ExternalDeviceTypeType DeviceAssignment;\r
 295 \r
 296 //      unsigned        SPI_NUMBER_OF_CHANNELS;\r
 297 //      unsigned        SPI_LIST_OF_CHANNELS[SPI_MAX_CHANNEL];\r
 298 } Spi_JobConfigType;\r
 299 \r
 300 // The communication settings of an external device. Closely linked to Spi-\r
 301 // Job.\r
 302 typedef struct Spi_ExternalDevice\r
 303 {\r
 304 \r
 305   // This parameter is the communication baudrate - This parameter allows\r
 306   // using a range of values, from the point of view of configuration tools, from\r
 307   // Hz up to MHz.\r
 308   // Note! Float in config case, not here\r
 309   uint32 SpiBaudrate;\r
 310 \r
 311   // Symbolic name to identify the CS used for this job\r
 312   uint32 SpiCsIdentifier;\r
 313 \r
 314   // This parameter defines the active polarity of Chip Select.\r
 315   // STD_HIGH or STD_LOW\r
 316   uint8 SpiCsPolarity;\r
 317 \r
 318   // This parameter defines the SPI data shift edge.\r
 319   Spi_EdgeType SpiDataShiftEdge;\r
 320 \r
 321   // This parameter enables or not the Chip Select handling functions.\r
 322   uint8 SpiEnableCs;\r
 323 \r
 324   // This parameter defines the SPI shift clock idle level.\r
 325   uint8 SpiShiftClockIdleLevel;\r
 326 \r
 327   // Timing between clock and chip select - This parameter allows to use a\r
 328   // range of values from 0 up to 100 microSec. the real configuration-value\r
 329   // used in software BSW-SPI is calculated out of this by the generator-tools\r
 330   // Note! Float in config case, not here. Unit ns\r
 331   uint32 SpiTimeClk2Cs;\r
 332 \r
 333   // Timing between PCS and first edge of SCK. Unit ns.\r
 334   uint32 SpiTimeCs2Clk;\r
 335 \r
 336   // ArcCore extension...\r
 337   // The controller ID(0..3)\r
 338   //uint32 SpiControllerId;\r
 339   void (*SpiCsCallback)(int);\r
 340 \r
 341 } Spi_ExternalDeviceType;\r
 342 \r
 343 // All data needed to configure one SPI-sequence\r
 344 typedef struct Spi_SequenceConfig\r
 345 {\r
 346   // This parameter allows or not this Sequence to be suspended by another\r
 347   // one.\r
 348   unsigned SpiInterruptibleSequence;\r
 349   // This parameter is a reference to a notification function.\r
 350   void (*SpiSeqEndNotification)();\r
 351   //\r
 352   Spi_SequenceType SpiSequenceId;\r
 353   //    unsigned                        SPI_NUMBER_OF_JOBS;\r
 354   // A sequence references several jobs, which are executed during a commu-\r
 355   // nication sequence\r
 356   Spi_JobType JobAssignment[SPI_MAX_JOB+1];\r
 357 } Spi_SequenceConfigType;\r
 358 \r
 359 typedef struct Spi_HwConfig\r
 360 {\r
 361   /* Interrupt priority level for this SPI channel. */\r
 362 //  uint8 IsrPriority;\r
 363 \r
 364   /* This channel is to be activated for use. */\r
 365   uint8 Activated;\r
 366 \r
 367   /* Receive DMA channel. */\r
 368 #if (SPI_IMPLEMENTATION==SPI_DMA)\r
 369   Dma_ChannelType RxDmaChannel;\r
 370 \r
 371   /* Transmit DMA channel. */\r
 372   Dma_ChannelType TxDmaChannel;\r
 373 #endif\r
 374 \r
 375   /* Peripheral clock source. */\r
 376 //  McuE_PeriperalClock_t PeripheralClock;\r
 377 }Spi_HwConfigType;\r
 378 \r
 379 \r
 380 #if 0\r
 381 struct SpiDriverConfiguration_s\r
 382 {\r
 383   Spi_ChannelType SPI_MAX_CHANNEL;\r
 384   Spi_JobType SPI_MAX_JOB;\r
 385   Spi_SequenceType SPI_MAX_SEQUENCE;\r
 386 };\r
 387 #endif\r
 388 \r
 389 // This is implementation specific but not all values may be valid\r
 390 // within the type.This type shall be chosen in order to have the\r
 391 // most efficient implementation on a specific microcontroller\r
 392 // platform.\r
 393 // In-short: Type of application data buffer elements\r
 394 // The 5516 TXDATA is 16-bit.. fits ?\r
 395 \r
 396 typedef uint8 Spi_DataType;\r
 397 //typedef uint16 Spi_DataType;\r
 398 \r
 399 // Specifies the identification (ID) for a SPI Hardware microcontroller peripheral (unit).\r
 400 // SPI140: This type is configurable (On / Off) at pre-compile time. The switch\r
 401 // SPI_HW_STATUS_API shall activate or deactivate the declaration of this\r
 402 // type.\r
 403 typedef uint8 Spi_HWUnitType;\r
 404 \r
 405 #if 0\r
 406 typedef struct\r
 407 {\r
 408   Spi_SequenceConfigType SpiSequenceConfig;\r
 409   Spi_JobConfigType SpiJobConfig;\r
 410   Spi_ChannelConfigType SpiChannelConfig;\r
 411   Spi_ExternalDeviceType SpiExternalDevice;\r
 412 }Spi_ConfigType;\r
 413 #endif\r
 414 \r
 415 \r
 416 typedef struct Spi_Driver\r
 417 {\r
 418   //    This parameter contains the number of Channels configured. It will be\r
 419   //    gathered by tools during the configuration stage.\r
 420   uint8 SpiMaxChannel;\r
 421 \r
 422   uint8 SpiMaxJob;\r
 423 \r
 424   uint8 SpiMaxSequence;\r
 425 \r
 426   // All data needed to configure one SPI-channel\r
 427   const struct Spi_ChannelConfig * SpiChannelConfig;\r
 428 \r
 429   // The communication settings of an external device. Closely\r
 430   // linked to SpiJob.\r
 431   const struct Spi_ExternalDevice * SpiExternalDevice;\r
 432 \r
 433   //    All data needed to configure one SPI-Job, amongst others the\r
 434   //    connection between the internal SPI unit and the special set-\r
 435   //    tings for an external device is done.\r
 436   const struct Spi_JobConfig * SpiJobConfig;\r
 437 \r
 438   // All data needed to configure one SPI-sequence\r
 439   const struct Spi_SequenceConfig * SpiSequenceConfig;\r
 440 \r
 441 //  const struct Spi_HwConfig *SpiHwConfig;\r
 442 } Spi_DriverType;\r
 443 \r
 444 typedef Spi_DriverType Spi_ConfigType;\r
 445 \r
 446 \r
 447 void Spi_Init( const Spi_ConfigType *ConfigPtr );\r
 448 Std_ReturnType Spi_DeInit( void );\r
 449 Std_ReturnType Spi_WriteIB( Spi_ChannelType Channel, const Spi_DataType *DataBufferPtr );\r
 450 Std_ReturnType Spi_AsyncTransmit( Spi_SequenceType Sequence );\r
 451 Std_ReturnType Spi_ReadIB( Spi_ChannelType Channel, Spi_DataType *const DataBufferPtr ) ;\r
 452 Std_ReturnType Spi_SetupEB( Spi_ChannelType Channel,\r
 453                                                         const Spi_DataType*  SrcDataBufferPtr,\r
 454                                                 Spi_DataType* DesDataBufferPtr,\r
 455                                                 Spi_NumberOfDataType Length );\r
 456 \r
 457 Spi_StatusType Spi_GetStatus( void );\r
 458 Spi_JobResultType Spi_GetJobResult ( Spi_JobType       Job );\r
 459 Spi_SeqResultType Spi_GetSequenceResult(Spi_SequenceType Sequence );\r
 460 \r
 461 #if ( SPI_VERSION_INFO_API == STD_ON  )\r
 462 #define Spi_GetVersionInfo(_vi) STD_GET_VERSION_INFO(_vi,SPI)\r
 463 #endif\r
 464 \r
 465 Std_ReturnType Spi_SyncTransmit( Spi_SequenceType        Sequence );\r
 466 Spi_StatusType Spi_GetHWUnitStatus(Spi_HWUnitType        HWUnit);\r
 467 \r
 468 #if (SPI_CANCEL_API == STD_ON )\r
 469 void Spi_Cancel( Spi_SequenceType Sequence );\r
 470 #endif\r
 471 \r
 472 Std_ReturnType Spi_SetAsyncMode( Spi_AsyncModeType        Mode );\r
 473 void Spi_MainFunction_Handling( void );\r
 474 void Spi_MainFunction_Driving( void );\r
 475 \r
 476 extern const Spi_ConfigType SpiConfigData;\r
 477 \r
 478 \r
 479 #endif /*SPI_H_*/\r