v2.0.0
Data Structures | Macros | Enumerations | Functions
hardware_sha256
Hardware APIs

Hardware SHA-256 Accelerator API. More...

## Data Structures
union | sha256_result_t
| SHA-256 result generated by the API. More...

## Macros
#define | SHA256_RESULT_BYTES 32
| Size of a sha256 result in bytes.

## Enumerations
enum | sha256_endianness { SHA256_LITTLE_ENDIAN , SHA256_BIG_ENDIAN }
| SHA-256 endianness definition used in the API. More...

## Functions
static void | sha256_set_dma_size (uint size_in_bytes)
| Configure the correct DMA data size. More...
static void | sha256_set_bswap (bool swap)
| Enable or disable byte swapping of 32-bit values. More...
static void | sha256_start (void)
| Prepare the hardware for a new checksum. More...
static bool | sha256_is_sum_valid (void)
| Check if a valid checksum has been calculated. More...
static bool | sha256_is_ready (void)
| Check if a the hardware is ready to accept more data. More...
static void | sha256_wait_valid_blocking (void)
| Wait until the checksum is valid. More...
static void | sha256_wait_ready_blocking (void)
| Wait until the hardware is ready to accept more data. More...
void | sha256_get_result (sha256_result_t *out, enum sha256_endianness endianness)
| Get the checksum result. More...
static bool | sha256_err_not_ready (void)
| Check if data was written before the hardware was ready. More...
static void | sha256_err_not_ready_clear (void)
| Clear the "not ready" error condition. More...
static volatile void * | sha256_get_write_addr (void)
| Address to write the data to be hashed. More...
static void | sha256_put_word (uint32_t word)
| Write one 32bit word of data to the SHA-256 hardware. More...
static void | sha256_put_byte (uint8_t b)
| Write one byte of data to the SHA-256 hardware. More...

## Detailed Description

Hardware SHA-256 Accelerator API.

RP2350 is equipped with an implementation of the SHA-256 hash algorithm. The hardware should first be configured by calling the sha256_set_dma_size and sha256_set_bswap functions. To generate a new hash the hardware should first be initialised by calling sha256_start. The hardware is ready to accept data when sha256_is_ready returns true, at which point the data to be hashed can be written to the address returned by sha256_get_write_addr. The hardware requires 64 bytes to be written in one go or else sha256_err_not_ready will indicate an error and the hashing process must be restarted. sha256_is_sum_valid will return true when there is a valid checksum result which can be retrieved by calling sha256_get_result.

## Enumeration Type Documentation

## ◆ sha256_endianness

enum sha256_endianness

SHA-256 endianness definition used in the API.

Enumerator
SHA256_LITTLE_ENDIAN | Little Endian.
SHA256_BIG_ENDIAN | Big Endian.

## Function Documentation

## ◆ sha256_err_not_ready()

static bool sha256_err_not_ready | ( | void |  | ) |
| inlinestatic

Check if data was written before the hardware was ready.

Indicates if an error has occurred due to data being written when the hardware is not ready.

Returns
  True if data was written before the hardware was ready

## ◆ sha256_err_not_ready_clear()

static void sha256_err_not_ready_clear | ( | void |  | ) |
| inlinestatic

Clear the "not ready" error condition.

Resets the hardware if a "not ready" error condition is indicated.

## ◆ sha256_get_result()

void sha256_get_result | ( | sha256_result_t * | out,
|  | enum sha256_endianness | endianness
| ) |  |

Get the checksum result.

Read the 32 byte result calculated by the hardware. Only valid if sha256_is_sum_valid is True

Parameters

  out | The checksum result

Copyright (c) 2024 Raspberry Pi (Trading) Ltd.

SPDX-License-Identifier: BSD-3-Clause

## ◆ sha256_get_write_addr()

static volatile void * sha256_get_write_addr | ( | void |  | ) |
| inlinestatic

Address to write the data to be hashed.

Returns the hardware address where data to be hashed should be written

Returns
  Address to write data to be hashed

## ◆ sha256_is_ready()

static bool sha256_is_ready | ( | void |  | ) |
| inlinestatic

Check if a the hardware is ready to accept more data.

After writing 64 bytes of data to the hardware, it will be unable to accept more data for a time. Call this to check if the hardware is ready for more data to be written.

See also
  sha256_err_not_ready

Returns
  True if the hardware is ready to receive more data

## ◆ sha256_is_sum_valid()

static bool sha256_is_sum_valid | ( | void |  | ) |
| inlinestatic

Check if a valid checksum has been calculated.

The checksum result will be invalid when data is first written to the hardware, and then once 64 bytes of data has been written it may take some time to complete the digest of the current block. This function can be used to determine when the checksum is valid.

Returns
  True if sha256_get_result would return a valid result

## ◆ sha256_put_byte()

static void sha256_put_byte | ( | uint8_t | b | ) |
| inlinestatic

Write one byte of data to the SHA-256 hardware.

Parameters

  b | data to write

## ◆ sha256_put_word()

static void sha256_put_word | ( | uint32_t | word | ) |
| inlinestatic

Write one 32bit word of data to the SHA-256 hardware.

Parameters

  word | data to write

## ◆ sha256_set_bswap()

static void sha256_set_bswap | ( | bool | swap | ) |
| inlinestatic

Enable or disable byte swapping of 32-bit values.

The SHA256 algorithm expects bytes in big endian order, but the system bus deals with little endian data, so control is provided to convert little endian bus data to big endian internal data. This defaults to true

Parameters

  swap | false to disable byte swapping

## ◆ sha256_set_dma_size()

static void sha256_set_dma_size | ( | uint | size_in_bytes | ) |
| inlinestatic

Configure the correct DMA data size.

This must be configured before the DMA channel is triggered and ensures the correct number of transfers is requested per block.

Parameters

  size_in_bytes | Size of DMA transfers, either 1, 2 or 4 bytes only.

## ◆ sha256_start()

static void sha256_start | ( | void |  | ) |
| inlinestatic

Prepare the hardware for a new checksum.

Called to initialise the hardware before starting the checksum calculation

## ◆ sha256_wait_ready_blocking()

static void sha256_wait_ready_blocking | ( | void |  | ) |
| inlinestatic

Wait until the hardware is ready to accept more data.

Before writing to the hardware, it's necessary to check it is ready to accept more data. This function waits until the hardware is ready to accept more data

## ◆ sha256_wait_valid_blocking()

static void sha256_wait_valid_blocking | ( | void |  | ) |
| inlinestatic

Wait until the checksum is valid.

When a multiple of 64 bytes of data has been written to the hardware, the checksum will be valid once the digest of the current block is complete. This function waits until when the checksum result is valid.