HASH HAL module driver. This file provides firmware functions to manage the following functionalities of the HASH peripheral: + Initialization and de-initialization methods + HASH or HMAC processing in polling mode + HASH or HMAC processing in interrupt mode + HASH or HMAC processing in DMA mode + Peripheral State methods + HASH or HMAC processing suspension/resumption.
More...
HASH HAL module driver. This file provides firmware functions to manage the following functionalities of the HASH peripheral: + Initialization and de-initialization methods + HASH or HMAC processing in polling mode + HASH or HMAC processing in interrupt mode + HASH or HMAC processing in DMA mode + Peripheral State methods + HASH or HMAC processing suspension/resumption.
- Author:
- MCD Application Team
===============================================================================
##### How to use this driver #####
===============================================================================
[..]
The HASH HAL driver can be used as follows:
(#)Initialize the HASH low level resources by implementing the HAL_HASH_MspInit():
(##) Enable the HASH interface clock using __HASH_CLK_ENABLE()
(##) When resorting to interrupt-based APIs (e.g. HAL_HASH_xxx_Start_IT())
(+++) Configure the HASH interrupt priority using HAL_NVIC_SetPriority()
(+++) Enable the HASH IRQ handler using HAL_NVIC_EnableIRQ()
(+++) In HASH IRQ handler, call HAL_HASH_IRQHandler() API
(##) When resorting to DMA-based APIs (e.g. HAL_HASH_xxx_Start_DMA())
(+++) Enable the DMAx interface clock using
__DMAx_CLK_ENABLE()
(+++) Configure and enable one DMA stream to manage data transfer from
memory to peripheral (input stream). Managing data transfer from
peripheral to memory can be performed only using CPU.
(+++) Associate the initialized DMA handle to the HASH DMA handle
using __HAL_LINKDMA()
(+++) Configure the priority and enable the NVIC for the transfer complete
interrupt on the DMA Stream: use
HAL_NVIC_SetPriority() and
HAL_NVIC_EnableIRQ()
(#)Initialize the HASH HAL using HAL_HASH_Init(). This function:
(##) resorts to HAL_HASH_MspInit() for low-level initialization,
(##) configures the data type: 1-bit, 8-bit, 16-bit or 32-bit.
(#)Three processing schemes are available:
(##) Polling mode: processing APIs are blocking functions
i.e. they process the data and wait till the digest computation is finished,
e.g. HAL_HASH_xxx_Start() for HASH or HAL_HMAC_xxx_Start() for HMAC
(##) Interrupt mode: processing APIs are not blocking functions
i.e. they process the data under interrupt,
e.g. HAL_HASH_xxx_Start_IT() for HASH or HAL_HMAC_xxx_Start_IT() for HMAC
(##) DMA mode: processing APIs are not blocking functions and the CPU is
not used for data transfer i.e. the data transfer is ensured by DMA,
e.g. HAL_HASH_xxx_Start_DMA() for HASH or HAL_HMAC_xxx_Start_DMA()
for HMAC. Note that in DMA mode, a call to HAL_HASH_xxx_Finish()
is then required to retrieve the digest.
(#)When the processing function is called after HAL_HASH_Init(), the HASH peripheral is
initialized and processes the buffer fed in input. When the input data have all been
fed to the IP, the digest computation can start.
(#)Multi-buffer processing is possible in polling and DMA mode.
(##) In polling mode, only multi-buffer HASH processing is possible.
API HAL_HASH_xxx_Accumulate() must be called for each input buffer, except for the last one.
User must resort to HAL_HASH_xxx_Start() to enter the last one and retrieve as
well the computed digest.
(##) In DMA mode, multi-buffer HASH and HMAC processing are possible.
(+++) HASH processing: once initialization is done, MDMAT bit must be set thru __HAL_HASH_SET_MDMAT() macro.
From that point, each buffer can be fed to the IP thru HAL_HASH_xxx_Start_DMA() API.
Before entering the last buffer, reset the MDMAT bit with __HAL_HASH_RESET_MDMAT()
macro then wrap-up the HASH processing in feeding the last input buffer thru the
same API HAL_HASH_xxx_Start_DMA(). The digest can then be retrieved with a call to
API HAL_HASH_xxx_Finish().
(+++) HMAC processing (requires to resort to extended functions):
after initialization, the key and the first input buffer are entered
in the IP with the API HAL_HMACEx_xxx_Step1_2_DMA(). This carries out HMAC step 1 and
starts step 2.
The following buffers are next entered with the API HAL_HMACEx_xxx_Step2_DMA(). At this
point, the HMAC processing is still carrying out step 2.
Then, step 2 for the last input buffer and step 3 are carried out by a single call
to HAL_HMACEx_xxx_Step2_3_DMA().
The digest can finally be retrieved with a call to API HAL_HASH_xxx_Finish().
(#)Context swapping.
(##) Two APIs are available to suspend HASH or HMAC processing:
(+++) HAL_HASH_SwFeed_ProcessSuspend() when data are entered by software (polling or IT mode),
(+++) HAL_HASH_DMAFeed_ProcessSuspend() when data are entered by DMA.
(##) When HASH or HMAC processing is suspended, HAL_HASH_ContextSaving() allows
to save in memory the IP context. This context can be restored afterwards
to resume the HASH processing thanks to HAL_HASH_ContextRestoring().
(##) Once the HASH IP has been restored to the same configuration as that at suspension
time, processing can be restarted with the same API call (same API, same handle,
same parameters) as done before the suspension. Relevant parameters to restart at
the proper location are internally saved in the HASH handle.
(#)Call HAL_HASH_DeInit() to deinitialize the HASH peripheral.
*** Callback registration ***
===================================
[..]
(#) The compilation define USE_HAL_HASH_REGISTER_CALLBACKS when set to 1
allows the user to configure dynamically the driver callbacks.
Use function @ref HAL_HASH_RegisterCallback() to register a user callback.
(#) Function @ref HAL_HASH_RegisterCallback() allows to register following callbacks:
(+) InCpltCallback : callback for input completion.
(+) DgstCpltCallback : callback for digest computation completion.
(+) ErrorCallback : callback for error.
(+) MspInitCallback : HASH MspInit.
(+) MspDeInitCallback : HASH MspDeInit.
This function takes as parameters the HAL peripheral handle, the Callback ID
and a pointer to the user callback function.
(#) Use function @ref HAL_HASH_UnRegisterCallback() to reset a callback to the default
weak (surcharged) function.
@ref HAL_HASH_UnRegisterCallback() takes as parameters the HAL peripheral handle,
and the Callback ID.
This function allows to reset following callbacks:
(+) InCpltCallback : callback for input completion.
(+) DgstCpltCallback : callback for digest computation completion.
(+) ErrorCallback : callback for error.
(+) MspInitCallback : HASH MspInit.
(+) MspDeInitCallback : HASH MspDeInit.
(#) By default, after the @ref HAL_HASH_Init and if the state is HAL_HASH_STATE_RESET
all callbacks are reset to the corresponding legacy weak (surcharged) functions:
examples @ref HAL_HASH_InCpltCallback(), @ref HAL_HASH_DgstCpltCallback()
Exception done for MspInit and MspDeInit callbacks that are respectively
reset to the legacy weak (surcharged) functions in the @ref HAL_HASH_Init
and @ref HAL_HASH_DeInit only when these callbacks are null (not registered beforehand)
If not, MspInit or MspDeInit are not null, the @ref HAL_HASH_Init and @ref HAL_HASH_DeInit
keep and use the user MspInit/MspDeInit callbacks (registered beforehand).
Callbacks can be registered/unregistered in READY state only.
Exception done for MspInit/MspDeInit callbacks that can be registered/unregistered
in READY or RESET state, thus registered (user) MspInit/DeInit callbacks can be used
during the Init/DeInit.
In that case first register the MspInit/MspDeInit user callbacks
using @ref HAL_HASH_RegisterCallback before calling @ref HAL_HASH_DeInit
or @ref HAL_HASH_Init function.
When The compilation define USE_HAL_HASH_REGISTER_CALLBACKS is set to 0 or
not defined, the callback registering feature is not available
and weak (surcharged) callbacks are used.
- Attention:
© COPYRIGHT(c) 2017 STMicroelectronics
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Definition in file stm32l4xx_hal_hash.c.
