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