sw/device/lib/base/random_order.h

// 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_