blob: 8fd271250f988bf89f27b7caecc2024a836ad922 [file] [log] [blame]
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
#ifndef OPENTITAN_SW_DEVICE_LIB_BASE_RANDOM_ORDER_H_
#define OPENTITAN_SW_DEVICE_LIB_BASE_RANDOM_ORDER_H_
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* @file
* @brief Functions for generating random traversal orders.
*/
/**
* Context for a random traversal order.
*
* A "random traversal order" specifies a random order to walk through some
* buffer of length `n`, which is an important building block for
* constant-power code. Given `n`, the random order emits integers in the
* range `0..m`, where `m` is an implementation-defined, per-random-order
* value greater than `n`. The order is guaranteed to visit each integer in
* `0..n` at least once, but with some caveats:
* - Values greater than `n` may be returned.
* - The same value may be returned multiple times.
*
* Users must be mindful of these constraints when using `random_order_t`.
* These caveats are intended to allow for implementation flexibility, such as
* intentionally adding decoys to the sequence.
*/
typedef struct random_order {
size_t state;
size_t max;
} random_order_t;
/**
* Constructs a new, randomly-seeded traversal order,
* running from `0` to at least `min_len`.
*
* This function does not take a seed as input; instead, the seed is
* extracted, in some manner or another, from the hardware by this function.
*
* @param ctx The context to initialize.
* @param min_len The minimum length this traversal order must visit.
*/
void random_order_init(random_order_t *ctx, size_t min_len);
/**
* Returns the length of the sequence represented by `ctx`.
*
* This value may be greater than `min_len` specified in
* `random_order_init()`, but the sequence is guaranteed to contain every
* integer in `0..min_len`.
*
* This value represents the number of times `random_order_advance()` may be
* called.
*
* @param ctx The context to query.
* @return The length of the sequence.
*/
size_t random_order_len(const random_order_t *ctx);
/**
* Returns the next element in the sequence represented by `ctx`.
*
* See `random_order_len()` for discovering how many times this function can
* be called.
*
* @param ctx The context to advance.
* @return The next value in the sequence.
*/
size_t random_order_advance(random_order_t *ctx);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // OPENTITAN_SW_DEVICE_LIB_BASE_RANDOM_ORDER_H_