Outline ![]()
Files ![]()
loading...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
/*
* Copyright (c) 2024 Raspberry Pi (Trading) Ltd.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
#ifndef _PICO_SHA256_H
#define _PICO_SHA256_H
#include "pico/time.h"
#include "hardware/dma.h"
#include "hardware/sha256.h"
/** \file pico/sha256.h
* \defgroup pico_sha256 pico_sha256
*
* \brief SHA-256 Hardware Accelerated implementation
*
* RP2350 is equipped with a hardware accelerated implementation of the SHA-256 hash algorithm.
* This should be much quicker than performing a SHA-256 checksum in software.
*
* \code
* pico_sha256_state_t state;
* if (pico_sha256_try_start(&state, SHA256_BIG_ENDIAN, true) == PICO_OK) {
* sha256_result_t result;
* pico_sha256_update(&state, some_data, sizeof(some_data));
* pico_sha256_update(&state, some_more_data, sizeof(some_more_data));
* pico_sha256_finish(&state, &result);
* for (int i = 0; i < SHA256_RESULT_BYTES; i++) {
* printf("%02x", result.bytes[i]);
* }
* }
* \endcode
*
* \subsection sha256_example Example
* \addtogroup pico_sha256
*
* \include hello_sha256.c
*/
#ifdef __cplusplus
extern "C" {
#endif
/*! \brief SHA-256 state used by the API
* \ingroup pico_sha256
*/
typedef struct pico_sha256_state {
enum sha256_endianness endianness;
int8_t channel;
bool locked;
uint8_t cache_used;
union {
uint32_t word;
uint8_t bytes[4];
} cache;
dma_channel_config config;
size_t total_data_size;
} pico_sha256_state_t;
/*! \brief Start a SHA-256 calculation returning immediately with an error if the SHA-256 hardware is not available
* \ingroup pico_sha256
*
* Initialises the hardware and state ready to start a new SHA-256 calculation.
* Only one instance can be started at any time.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param endianness SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
* @param use_dma Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.
* @return Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started, otherwise an error is returned
*/
int pico_sha256_try_start(pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma);
/*! \brief Start a SHA-256 calculation waiting for a defined period for the SHA-256 hardware to be available
* \ingroup pico_sha256
*
* Initialises the hardware and state ready to start a new SHA-256 calculation.
* Only one instance can be started at any time.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param endianness SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
* @param use_dma Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.
* @param until How long to wait for the SHA hardware to be available
* @return Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started in time, otherwise an error is returned
*/
int pico_sha256_start_blocking_until(pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma, absolute_time_t until);
/*! \brief Start a SHA-256 calculation, blocking forever waiting until the SHA-256 hardware is available
* \ingroup pico_sha256
*
* Initialises the hardware and state ready to start a new SHA-256 calculation.
* Only one instance can be started at any time.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param endianness SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
* @param use_dma Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.
* @return Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started, otherwise an error is returned
*/
static inline int pico_sha256_start_blocking(pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma) {
return pico_sha256_start_blocking_until(state, endianness, use_dma, at_the_end_of_time);
}
/*! \brief Add byte data to be SHA-256 calculation
* \ingroup pico_sha256
*
* Add byte data to be SHA-256 calculation
* You may call this as many times as required to add all the data needed.
* You must have called pico_sha256_try_start (or equivalent) already.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param data Pointer to the data to be added to the calculation
* @param data_size_bytes Amount of data to add
*
* @note This function may return before the copy has completed in which case the data passed to the function must remain valid and
* unchanged until a further call to pico_sha256_update or pico_sha256_finish. If this is not done, corrupt data may be used for the
* SHA-256 calculation giving an unexpected result.
*/
void pico_sha256_update(pico_sha256_state_t *state, const uint8_t *data, size_t data_size_bytes);
/*! \brief Add byte data to be SHA-256 calculation
* \ingroup pico_sha256
*
* Add byte data to be SHA-256 calculation
* You may call this as many times as required to add all the data needed.
* You must have called pico_sha256_try_start already.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param data Pointer to the data to be added to the calculation
* @param data_size_bytes Amount of data to add
*
* @note This function will only return when the data passed in is no longer required, so it can be freed or changed on return.
*/
void pico_sha256_update_blocking(pico_sha256_state_t *state, const uint8_t *data, size_t data_size_bytes);
/*! \brief Finish the SHA-256 calculation and return the result
* \ingroup pico_sha256
*
* Ends the SHA-256 calculation freeing the hardware for use by another caller.
* You must have called pico_sha256_try_start already.
*
* @param state A pointer to a pico_sha256_state_t instance
* @param out The SHA-256 checksum
*/
void pico_sha256_finish(pico_sha256_state_t *state, sha256_result_t *out);
#ifdef __cplusplus
}
#endif
#endif
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.