hal_stm32_dma.h

Go to the documentation of this file.

/*
 * Copyright (C) 2019 Alexandre Bustico, Gautier Hattenberger
 *
 * This file is part of paparazzi.
 *
 * paparazzi is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * paparazzi is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with paparazzi; see the file COPYING.  If not, see
 * <http://www.gnu.org/licenses/>.
 */

#pragma once

#include <ch.h>
#include <hal.h>


#if !defined(STM32_DMA_USE_WAIT) || defined(__DOXYGEN__)
#define STM32_DMA_USE_WAIT                TRUE
#endif

#if !defined(STM32_DMA_USE_MUTUAL_EXCLUSION) || defined(__DOXYGEN__)
#define STM32_DMA_USE_MUTUAL_EXCLUSION    FALSE
#endif

#if !defined(STM32_DMA_SUPPORTS_CSELR) || defined(__DOXYGEN__)
#define STM32_DMA_SUPPORTS_CSELR   FALSE
#endif


typedef enum {
  DMA_UNINIT = 0,                           
  DMA_STOP = 1,                             
  DMA_READY = 2,                            
  DMA_ACTIVE = 3,                           
  DMA_COMPLETE = 4,                         
  DMA_ERROR = 5                             
} dmastate_t;

typedef enum {
  DMA_ERR_TRANSFER_ERROR   = 1 << 0,        
  DMA_ERR_DIRECTMODE_ERROR = 1 << 1,        
  DMA_ERR_FIFO_ERROR       = 1 << 2         
} dmaerrormask_t;

typedef enum {
  DMA_DIR_P2M = 1,           
  DMA_DIR_M2P = 2,           
  DMA_DIR_M2M = 3,           
} dmadirection_t;

typedef struct DMADriver DMADriver;

typedef void (*dmacallback_t)(DMADriver *dmap, void *buffer, const size_t n);


typedef void (*dmaerrorcallback_t)(DMADriver *dmap, dmaerrormask_t err);



/*===========================================================================*/
/* Driver macros.                                                            */
/*===========================================================================*/
#if (STM32_DMA_USE_WAIT == TRUE) || defined(__DOXYGEN__)

#define _dma_reset_i(dmap)                                                  \
  osalThreadResumeI(&(dmap)->thread, MSG_RESET)

#define _dma_reset_s(dmap)                                                  \
  osalThreadResumeS(&(dmap)->thread, MSG_RESET)

#define _dma_wakeup_isr(dmap) {                                             \
    osalSysLockFromISR();                                                     \
    osalThreadResumeI(&(dmap)->thread, MSG_OK);                               \
    osalSysUnlockFromISR();                                                   \
  }

#define _dma_timeout_isr(dmap) {                                            \
    osalSysLockFromISR();                                                     \
    osalThreadResumeI(&(dmap)->thread, MSG_TIMEOUT);                          \
    osalSysUnlockFromISR();                                                   \
  }
#else /* !STM32_DMA_USE_WAIT */
#define _dma_reset_i(dmap)
#define _dma_reset_s(dmap)
#define _dma_wakeup_isr(dmap)
#define _dma_timeout_isr(dmap)
#endif /* !STM32_DMA_USE_WAIT */

static inline void _dma_isr_half_code(DMADriver *dmap);


static inline void _dma_isr_full_code(DMADriver *dmap);


static inline void _dma_isr_error_code(DMADriver *dmap, dmaerrormask_t err);



#ifdef __cplusplus
extern "C" {
#endif

typedef struct  {
  uint32_t    stream;

#if STM32_DMA_SUPPORTS_CSELR

  union {
    uint8_t   request; // STM terminology for dmaV1
    uint8_t   channel; // ChibiOS terminology for both dmaV1 and dmaV2 (portability)
  };
#elif STM32_DMA_ADVANCED
  uint8_t   channel;
#endif

  bool      inc_peripheral_addr;


  bool      inc_memory_addr;


  bool      circular;


  dmacallback_t         end_cb;

  dmaerrorcallback_t    error_cb;
#if STM32_DMA_USE_ASYNC_TIMOUT

  sysinterval_t timeout;
#endif


  dmadirection_t  direction;


  uint8_t   dma_priority;

  uint8_t   irq_priority;

  uint8_t   psize; // 1,2,4

  uint8_t   msize; // 1,2,4
#if STM32_DMA_ADVANCED
#define STM32_DMA_FIFO_SIZE 4 // hardware specification for dma V2

  uint8_t   pburst; // 0(burst disabled), 4, 8, 16

  uint8_t   mburst; // 0(burst disabled), 4, 8, 16

  uint8_t   fifo;   // 0(fifo disabled), 1, 2, 3, 4 : 25, 50, 75, 100%

  bool      periph_inc_size_4; // PINCOS bit

  bool      transfert_end_ctrl_by_periph; // PFCTRL bit
#endif
}  DMAConfig;


struct DMADriver {
  const stm32_dma_stream_t  *dmastream;

  const DMAConfig     *config;

#if STM32_DMA_USE_WAIT || defined(__DOXYGEN__)

  thread_reference_t        thread;
#endif
#if STM32_DMA_USE_MUTUAL_EXCLUSION || defined(__DOXYGEN__)

  mutex_t                   mutex;
#endif /* STM32_DMA_USE_MUTUAL_EXCLUSION */
#if STM32_DMA_USE_ASYNC_TIMOUT

  uint8_t       *volatile currPtr;

  virtual_timer_t      vt;
#endif

  void           *mem0p;

  uint32_t         dmamode;

  size_t         size;

  dmastate_t         state;


  uint8_t        controller;
};



void  dmaObjectInit(DMADriver *dmap);
bool  dmaStart(DMADriver *dmap, const DMAConfig *cfg);
void  dmaStop(DMADriver *dmap);

#if STM32_DMA_USE_WAIT == TRUE
msg_t dmaTransfertTimeout(DMADriver *dmap, volatile void *periphp, void *mem0p, const size_t size,
                          sysinterval_t timeout);
// helper
static inline msg_t dmaTransfert(DMADriver *dmap, volatile void *periphp, void *mem0p, const size_t size)
{
  return dmaTransfertTimeout(dmap, periphp, mem0p, size, TIME_INFINITE);
}
#endif
#if STM32_DMA_USE_MUTUAL_EXCLUSION == TRUE
void dmaAcquireBus(DMADriver *dmap);
void dmaReleaseBus(DMADriver *dmap);
#endif
bool  dmaStartTransfert(DMADriver *dmap, volatile void *periphp, void *mem0p, const size_t size);
void  dmaStopTransfert(DMADriver *dmap);

bool  dmaStartTransfertI(DMADriver *dmap, volatile void *periphp, void *mem0p, const size_t size);
void  dmaStopTransfertI(DMADriver *dmap);


// low level driver

bool  dma_lld_start(DMADriver *dmap);
void  dma_lld_stop(DMADriver *dmap);


bool  dma_lld_start_transfert(DMADriver *dmap, volatile void *periphp, void *mem0p, const size_t size);


void  dma_lld_stop_transfert(DMADriver *dmap);

#if STM32_DMA_USE_ASYNC_TIMOUT
void dma_lld_serve_timeout_interrupt(void *arg);
#endif

#if STM32_DMA_USE_ASYNC_TIMOUT
typedef enum {FROM_TIMOUT_CODE, FROM_HALF_CODE, FROM_FULL_CODE, FROM_NON_CIRCULAR_CODE} CbCallContext;
static inline void async_timout_enabled_call_end_cb(DMADriver *dmap, const CbCallContext context)
{
  uint8_t *const baseAddr = dmap->currPtr;
  const size_t fullSize = dmap->size;
  const size_t halfSize = fullSize / 2;
  size_t rem = 0;
  uint8_t *const basePtr = (uint8_t *) dmap->mem0p;
  uint8_t *const midPtr = ((uint8_t *) dmap->mem0p) + (dmap->config->msize * halfSize);
  uint8_t *const endPtr = ((uint8_t *) dmap->mem0p) + (dmap->config->msize * fullSize);


  switch (context) {
    case (FROM_HALF_CODE) :
      if (midPtr > baseAddr) {
        rem = (midPtr - baseAddr) / dmap->config->msize;
        dmap->currPtr = midPtr;
      }
      break;

    case (FROM_FULL_CODE) :
    case (FROM_NON_CIRCULAR_CODE) :
      rem = (endPtr - baseAddr) / dmap->config->msize;
      dmap->currPtr = basePtr;
      break;

    case (FROM_TIMOUT_CODE) : {
      const size_t dmaCNT = dmaStreamGetTransactionSize(dmap->dmastream);
      const size_t index = (baseAddr - basePtr) / dmap->config->msize;

      // if following test fail, it's because DMACNT has rollover during the ISR,
      // so that we can safely ignore this TIMOUT event since a fullcode ISR will follow
      // briefly
      if (fullSize >= (dmaCNT + index)) {
        rem = (fullSize - dmaCNT - index);
        dmap->currPtr = baseAddr + (rem * dmap->config->msize);
      }
    }
    break;
  }

  if (dmap->config->end_cb != NULL  && (rem > 0)) {
    dmap->config->end_cb(dmap, baseAddr, rem);
  }
}
#endif

static inline void _dma_isr_half_code(DMADriver *dmap)
{
#if STM32_DMA_USE_ASYNC_TIMOUT
  if (dmap->config->timeout != TIME_INFINITE) {
    chSysLockFromISR();
    chVTSetI(&dmap->vt, dmap->config->timeout,
             &dma_lld_serve_timeout_interrupt, (void *) dmap);
    chSysUnlockFromISR();
  }
  async_timout_enabled_call_end_cb(dmap, FROM_HALF_CODE);
#else
  if (dmap->config->end_cb != NULL) {
    dmap->config->end_cb(dmap, dmap->mem0p, dmap->size / 2);
  }
#endif
}

static inline void _dma_isr_full_code(DMADriver *dmap)
{
  if (dmap->config->circular) {
#if STM32_DMA_USE_ASYNC_TIMOUT
    if (dmap->config->timeout != TIME_INFINITE) {
      chSysLockFromISR();
      chVTSetI(&dmap->vt, dmap->config->timeout,
               &dma_lld_serve_timeout_interrupt, (void *) dmap);
      chSysUnlockFromISR();
    }
    async_timout_enabled_call_end_cb(dmap, FROM_FULL_CODE);
#else
    /* Callback handling.*/
    if (dmap->config->end_cb != NULL) {
      if (dmap->size > 1) {
        /* Invokes the callback passing the 2nd half of the buffer.*/
        const size_t half_index = dmap->size / 2;
        const uint8_t *byte_array_p = ((uint8_t *) dmap->mem0p) +
                                      dmap->config->msize * half_index;
        dmap->config->end_cb(dmap, (void *) byte_array_p, half_index);
      } else {
        /* Invokes the callback passing the whole buffer.*/
        dmap->config->end_cb(dmap, dmap->mem0p, dmap->size);
      }
    }
#endif
  } else { // not circular
    /* End transfert.*/
#if STM32_DMA_USE_ASYNC_TIMOUT
    if (dmap->config->timeout != TIME_INFINITE) {
      chSysLockFromISR();
      chVTResetI(&dmap->vt);
      chSysUnlockFromISR();
    }
#endif
    dma_lld_stop_transfert(dmap);
    if (dmap->config->end_cb != NULL) {
      dmap->state = DMA_COMPLETE;
      /* Invoke the callback passing the whole buffer.*/
#if STM32_DMA_USE_ASYNC_TIMOUT
      async_timout_enabled_call_end_cb(dmap, FROM_NON_CIRCULAR_CODE);
#else
      dmap->config->end_cb(dmap, dmap->mem0p, dmap->size);
#endif
      if (dmap->state == DMA_COMPLETE) {
        dmap->state = DMA_READY;
      }
    } else {
      dmap->state = DMA_READY;
    }
    _dma_wakeup_isr(dmap);
  }
}

static inline void _dma_isr_error_code(DMADriver *dmap, dmaerrormask_t err)
{
  dma_lld_stop_transfert(dmap);
  if (dmap->config->error_cb != NULL) {
    dmap->state = DMA_ERROR;
    dmap->config->error_cb(dmap, err);
    if (dmap->state == DMA_ERROR) {
      dmap->state = DMA_READY;
    }
  } else {
    dmap->state = DMA_READY;
  }
  _dma_timeout_isr(dmap);
}


#ifdef __cplusplus
}
#endif