Peripheral states functions

Peripheral State functions. More...

Functions
HAL_HASH_StateTypeDef	HAL_HASH_GetState (HASH_HandleTypeDef *hhash)
	Return the HASH handle state. More...
HAL_StatusTypeDef	HAL_HASH_GetStatus (HASH_HandleTypeDef *hhash)
	Return the HASH HAL status. More...
void	HAL_HASH_ContextSaving (HASH_HandleTypeDef *hhash, uint8_t *pMemBuffer)
	Save the HASH context in case of processing suspension. More...
void	HAL_HASH_ContextRestoring (HASH_HandleTypeDef *hhash, uint8_t *pMemBuffer)
	Restore the HASH context in case of processing resumption. More...
void	HAL_HASH_SwFeed_ProcessSuspend (HASH_HandleTypeDef *hhash)
	Initiate HASH processing suspension when in polling or interruption mode. More...
HAL_StatusTypeDef	HAL_HASH_DMAFeed_ProcessSuspend (HASH_HandleTypeDef *hhash)
	Suspend the HASH processing when in DMA mode. More...
uint32_t	HAL_HASH_GetError (HASH_HandleTypeDef *hhash)
	Return the HASH handle error code. More...

Detailed Description

Peripheral State functions.

 ===============================================================================
                      ##### Peripheral State methods #####
 ===============================================================================
    [..]
    This section permits to get in run-time the state and the peripheral handle
    status of the peripheral:
      (+) HAL_HASH_GetState()
      (+) HAL_HASH_GetStatus()

    [..]
    Additionally, this subsection provides functions allowing to save and restore
    the HASH or HMAC processing context in case of calculation suspension:
      (+) HAL_HASH_ContextSaving()
      (+) HAL_HASH_ContextRestoring()

    [..]
    This subsection provides functions allowing to suspend the HASH processing
      (+) when input are fed to the Peripheral by software
          (++) HAL_HASH_SwFeed_ProcessSuspend()
      (+) when input are fed to the Peripheral by DMA
          (++) HAL_HASH_DMAFeed_ProcessSuspend()

Function Documentation

HAL_HASH_ContextRestoring()

void HAL_HASH_ContextRestoring	(	HASH_HandleTypeDef *	hhash,
		uint8_t *	pMemBuffer
	)

Restore the HASH context in case of processing resumption.

Parameters

hhash	HASH handle.
pMemBuffer	pointer to the memory buffer where the HASH context is stored.

Note

The IMR, STR, CR then all the CSR registers are restored in that order. Only the r/w bits are restored.

By default, all the context swap registers (HASH_NUMBER_OF_CSR_REGISTERS of those) are restored (all of them have been saved by default beforehand).

Return values

None

Definition at line 1359 of file stm32l4xx_hal_hash.c.

{
  uint32_t mem_ptr = (uint32_t)pMemBuffer;
  uint32_t csr_ptr = (uint32_t)HASH->CSR;
  uint32_t i;

  /* Prevent unused argument(s) compilation warning */
  UNUSED(hhash);

  /* Restore IMR register content */
  WRITE_REG(HASH->IMR, (*(uint32_t*)(mem_ptr)));
  mem_ptr+=4U;
  /* Restore STR register content */
  WRITE_REG(HASH->STR, (*(uint32_t*)(mem_ptr)));
  mem_ptr+=4U;
  /* Restore CR register content */
  WRITE_REG(HASH->CR, (*(uint32_t*)(mem_ptr)));
  mem_ptr+=4U;

  /* Reset the HASH processor before restoring the Context
  Swap Registers (CSR) */
  __HAL_HASH_INIT();

  /* By default, restore all CSR registers */
  for (i = HASH_NUMBER_OF_CSR_REGISTERS; i >0U; i--)
  {
    WRITE_REG((*(uint32_t*)(csr_ptr)), (*(uint32_t*)(mem_ptr)));
    mem_ptr+=4U;
    csr_ptr+=4U;
  }
}

HAL_HASH_ContextSaving()

void HAL_HASH_ContextSaving	(	HASH_HandleTypeDef *	hhash,
		uint8_t *	pMemBuffer
	)

Save the HASH context in case of processing suspension.

Parameters

hhash	HASH handle.
pMemBuffer	pointer to the memory buffer where the HASH context is saved.

Note

The IMR, STR, CR then all the CSR registers are saved in that order. Only the r/w bits are read to be restored later on.

By default, all the context swap registers (there are HASH_NUMBER_OF_CSR_REGISTERS of those) are saved.

pMemBuffer points to a buffer allocated by the user. The buffer size must be at least (HASH_NUMBER_OF_CSR_REGISTERS + 3) * 4 uint8 long.

Return values

None

Definition at line 1319 of file stm32l4xx_hal_hash.c.

{
  uint32_t mem_ptr = (uint32_t)pMemBuffer;
  uint32_t csr_ptr = (uint32_t)HASH->CSR;
  uint32_t i;

  /* Prevent unused argument(s) compilation warning */
  UNUSED(hhash);

  /* Save IMR register content */
  *(uint32_t*)(mem_ptr) = READ_BIT(HASH->IMR,HASH_IT_DINI|HASH_IT_DCI);
  mem_ptr+=4U;
  /* Save STR register content */
  *(uint32_t*)(mem_ptr) = READ_BIT(HASH->STR,HASH_STR_NBLW);
  mem_ptr+=4U;
  /* Save CR register content */
  *(uint32_t*)(mem_ptr) = READ_BIT(HASH->CR,HASH_CR_DMAE|HASH_CR_DATATYPE|HASH_CR_MODE|HASH_CR_ALGO|HASH_CR_LKEY|HASH_CR_MDMAT);
  mem_ptr+=4U;
  /* By default, save all CSRs registers */
  for (i = HASH_NUMBER_OF_CSR_REGISTERS; i >0U; i--)
  {
    *(uint32_t*)(mem_ptr) = *(uint32_t*)(csr_ptr);
    mem_ptr+=4U;
    csr_ptr+=4U;
  }
}

HAL_HASH_DMAFeed_ProcessSuspend()

HAL_StatusTypeDef HAL_HASH_DMAFeed_ProcessSuspend

(

HASH_HandleTypeDef *

hhash

)

Suspend the HASH processing when in DMA mode.

Parameters

hhash

HASH handle.

Note

When suspension attempt occurs at the very end of a DMA transfer and all the data have already been entered in the Peripheral, hhash->State is set to HAL_HASH_STATE_READY and the API returns HAL_ERROR. It is recommended to wrap-up the processing in reading the digest as usual.

Return values

HAL

status

Definition at line 1417 of file stm32l4xx_hal_hash.c.

{
  uint32_t tmp_remaining_DMATransferSize_inWords;
  uint32_t tmp_initial_DMATransferSize_inWords;
  uint32_t tmp_words_already_pushed;

  if (hhash->State == HAL_HASH_STATE_READY)
  {
    return HAL_ERROR;
  }
  else
  {

   /* Make sure there is enough time to suspend the processing */
    tmp_remaining_DMATransferSize_inWords = ((DMA_Channel_TypeDef *)hhash->hdmain->Instance)->CNDTR;

    if (tmp_remaining_DMATransferSize_inWords <= HASH_DMA_SUSPENSION_WORDS_LIMIT)
    {
      /* No suspension attempted since almost to the end of the transferred data. */
      /* Best option for user code is to wrap up low priority message hashing     */
      return HAL_ERROR;
    }

    /* Wait for BUSY flag to be reset */
    if (HASH_WaitOnFlagUntilTimeout(hhash, HASH_FLAG_BUSY, SET, HASH_TIMEOUTVALUE) != HAL_OK)
    {
       return HAL_TIMEOUT;
    }

    if (__HAL_HASH_GET_FLAG(HASH_FLAG_DCIS) != RESET)
    {
      return HAL_ERROR;
    }

    /* Wait for BUSY flag to be set */
    if (HASH_WaitOnFlagUntilTimeout(hhash, HASH_FLAG_BUSY, RESET, HASH_TIMEOUTVALUE) != HAL_OK)
    {
       return HAL_TIMEOUT;
    }

    /* Disable DMA channel */
    if (HAL_DMA_Abort(hhash->hdmain) ==HAL_OK)
    {
      /*
      Note that the Abort function will
      - Clear the transfer error flags
      - Unlock
      - Set the State
      */
    }

    /* Clear DMAE bit */
    CLEAR_BIT(HASH->CR,HASH_CR_DMAE);

    /* Wait for BUSY flag to be reset */
    if (HASH_WaitOnFlagUntilTimeout(hhash, HASH_FLAG_BUSY, SET, HASH_TIMEOUTVALUE) != HAL_OK)
    {
      return HAL_TIMEOUT;
    }

    if (__HAL_HASH_GET_FLAG(HASH_FLAG_DCIS) != RESET)
    {
      return HAL_ERROR;
    }

    /* At this point, DMA interface is disabled and no transfer is on-going */
    /* Retrieve from the DMA handle how many words remain to be written */
    tmp_remaining_DMATransferSize_inWords = ((DMA_Channel_TypeDef *)hhash->hdmain->Instance)->CNDTR;

    if (tmp_remaining_DMATransferSize_inWords == 0U)
    {
      /* All the DMA transfer is actually done. Suspension occurred at the very end
         of the transfer. Either the digest computation is about to start (HASH case)
         or processing is about to move from one step to another (HMAC case).
         In both cases, the processing can't be suspended at this point. It is
         safer to
         - retrieve the low priority block digest before starting the high
           priority block processing (HASH case)
         - re-attempt a new suspension (HMAC case)
         */
      return HAL_ERROR;
    }
    else
    {

      /* Compute how many words were supposed to be transferred by DMA */
      tmp_initial_DMATransferSize_inWords = (((hhash->HashInCount%4U)!=0U) ?  ((hhash->HashInCount+3U)/4U): (hhash->HashInCount/4U));

      /* If discrepancy between the number of words reported by DMA Peripheral and the numbers of words entered as reported
        by HASH Peripheral, correct it */
      /* tmp_words_already_pushed reflects the number of words that were already pushed before
         the start of DMA transfer (multi-buffer processing case) */
      tmp_words_already_pushed = hhash->NbWordsAlreadyPushed;
      if (((tmp_words_already_pushed + tmp_initial_DMATransferSize_inWords - tmp_remaining_DMATransferSize_inWords) %16U)  != HASH_NBW_PUSHED())
      {
        tmp_remaining_DMATransferSize_inWords--; /* one less word to be transferred again */
      }

      /* Accordingly, update the input pointer that points at the next word to be transferred to the Peripheral by DMA */
      hhash->pHashInBuffPtr +=  4U * (tmp_initial_DMATransferSize_inWords - tmp_remaining_DMATransferSize_inWords) ;

      /* And store in HashInCount the remaining size to transfer (in bytes) */
      hhash->HashInCount = 4U * tmp_remaining_DMATransferSize_inWords;

    }

    /* Set State as suspended */
    hhash->State = HAL_HASH_STATE_SUSPENDED;

    return HAL_OK;

  }
}

HAL_HASH_GetError()

uint32_t HAL_HASH_GetError

(

HASH_HandleTypeDef *

hhash

)

Return the HASH handle error code.

Parameters

hhash

pointer to a HASH_HandleTypeDef structure.

Return values

HASH	Error Code

Definition at line 1536 of file stm32l4xx_hal_hash.c.

{
  /* Return HASH Error Code */
  return hhash->ErrorCode;
}

HAL_HASH_GetState()

HAL_HASH_StateTypeDef HAL_HASH_GetState

(

HASH_HandleTypeDef *

hhash

)

Return the HASH handle state.

Note

The API yields the current state of the handle (BUSY, READY,...).

Parameters

hhash

HASH handle.

Return values

HAL	HASH state

Definition at line 1288 of file stm32l4xx_hal_hash.c.

{
  return hhash->State;
}

HAL_HASH_GetStatus()

HAL_StatusTypeDef HAL_HASH_GetStatus

(

HASH_HandleTypeDef *

hhash

)

Return the HASH HAL status.

Note

The API yields the HAL status of the handle: it is the result of the latest HASH processing and allows to report any issue (e.g. HAL_TIMEOUT).

Parameters

hhash

HASH handle.

Return values

HAL

status

Definition at line 1301 of file stm32l4xx_hal_hash.c.

{
  return hhash->Status;
}

HAL_HASH_SwFeed_ProcessSuspend()

void HAL_HASH_SwFeed_ProcessSuspend

(

HASH_HandleTypeDef *

hhash

)

Initiate HASH processing suspension when in polling or interruption mode.

Parameters

hhash

HASH handle.

Note

Set the handle field SuspendRequest to the appropriate value so that the on-going HASH processing is suspended as soon as the required conditions are met. Note that the actual suspension is carried out by the functions HASH_WriteData() in polling mode and HASH_IT() in interruption mode.

Return values

None

Definition at line 1402 of file stm32l4xx_hal_hash.c.

{
  /* Set Handle Suspend Request field */
  hhash->SuspendRequest = HAL_HASH_SUSPEND;
}