struct field_interface

Scope: fifi::api

In header: #include <field_interface.hpp>

Member types (public)

using value_type

Member functions (public)

virtual ~field_interface ()
value_type add (value_type a, value_type b) const
uint32_t best_granularity () const
value_type divide (value_type a, value_type b) const
uint32_t elements_to_length (uint32_t elements) const
uint32_t elements_to_size (uint32_t elements) const
fifi::api::field field () const
value_type get_value (const uint8_t * elements, uint32_t index) const
value_type invert (value_type a) const
uint32_t length_to_elements (uint32_t length) const
uint32_t length_to_size (uint32_t length) const
value_type max_value () const
uint32_t min_granularity () const
value_type min_value () const
value_type multiply (value_type a, value_type b) const
void region_add (uint8_t * dest, const uint8_t * src, uint32_t size) const
void region_divide (uint8_t * dest, const uint8_t * src, uint32_t size) const
void region_multiply (uint8_t * dest, const uint8_t * src, uint32_t size) const
void region_multiply_add (uint8_t * dest, const uint8_t * src, value_type constant, uint32_t size) const
void region_multiply_constant (uint8_t * dest, value_type constant, uint32_t size) const
void region_multiply_subtract (uint8_t * dest, const uint8_t * src, value_type constant, uint32_t size) const
void region_subtract (uint8_t * dest, const uint8_t * src, uint32_t size) const
void set_value (uint8_t * elements, uint32_t index, value_type value) const
uint32_t size_to_elements (uint32_t size) const
uint32_t size_to_length (uint32_t size) const
value_type subtract (value_type a, value_type b) const
virtual void vector_dot_product (uint8_t ** dest, const uint8_t ** src, uint8_t ** constants, uint32_t size, uint32_t dest_vectors, uint32_t src_vectors) const

Description

Generic interface for all finite field implementation wrappers. The fifi::api::create_default_field() function returns a field_interface instance that implements the specified finite field.

Member Function Description

~field_interface ()

Virtual destructor.

value_type add (value_type a, value_type b)

Returns the sum of two field elements.

Parameter a:
The augend.
Parameter b:
The addend.
Returns:
The sum of a and b.

uint32_t best_granularity ()

Returns:
The optimal granularity requirement of the stack. An application can achieve optimal performance if it uses buffers whose size is an integer multiple of this value.

value_type divide (value_type a, value_type b)

Returns the quotient of two field elements.

Parameter a:
The numerator.
Parameter b:
The denominator.
Returns:
The quotient of a and b.

uint32_t elements_to_length (uint32_t elements)

Returns the number of value_type elements needed to store a certain number of field elements

Parameter elements:
the number of field elements
Returns:
the number of value_type elements needed

uint32_t elements_to_size (uint32_t elements)

Returns the minimum size in bytes required to accommodate a certain number of field elements

Parameter elements:
the number of field elements
Returns:
the size in bytes needed to store the field elements

fifi::api::field field ()

The fifi::api::field enum value for the field that is implemented by this interface

Returns:
The API field value

value_type get_value (const uint8_t * elements, uint32_t index)

Function to access individual field elements in a buffer. This function assumes that values are packed.

Parameter elements:
raw buffer that contains the field elements
Parameter index:
index of element to access in the packed buffer
Returns:
the value of the element at specified index

value_type invert (value_type a)

Returns inverse of a field element.

Parameter a:
Element to invert.
Returns:
The inverse of the field element.

uint32_t length_to_elements (uint32_t length)

Returns the number of field elements needed to store a certain number of value_type elements

Parameter length:
the number of value_type elements
Returns:
the number of field elements needed

uint32_t length_to_size (uint32_t length)

Returns the size in bytes needed to store a certain number of value_type elements

Parameter length:
the number of value_type elements to store
Returns:
the size in bytes needed to store the value_type elements

value_type max_value ()

The maximum value for any field element

Returns:
the maximum value

uint32_t min_granularity ()

Returns:
The minimum granularity requirement of a given stack. The size of the buffers used with the arithmetic functions must be divisible by this granularity value.

value_type min_value ()

The minimum value for any field element

Returns:
the minimum value

value_type multiply (value_type a, value_type b)

Returns the product of two field elements.

Parameter a:
The multiplicand.
Parameter b:
The multiplier.
Returns:
The product of a and b.

void region_add (uint8_t * dest, const uint8_t * src, uint32_t size)

Adds two field element buffers. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest + src

Parameter dest:
The buffer containing the augends, and the destination for the resulting sums.
Parameter src:
The buffer containing the addends.
Parameter size:
The size of the provided buffers.

void region_divide (uint8_t * dest, const uint8_t * src, uint32_t size)

Divides two field element buffers. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest / src

Parameter dest:
The buffer containing the numerators, and the destination for the resulting quotients.
Parameter src:
The buffer containing the denominators.
Parameter size:
The size of the provided buffers.

void region_multiply (uint8_t * dest, const uint8_t * src, uint32_t size)

Multiplies two field element buffers. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest * src

Parameter dest:
The buffer containing the multiplicands, and the destination for the resulting products.
Parameter src:
The buffer containing the multipliers.
Parameter size:
The size of the provided buffers.

void region_multiply_add (uint8_t * dest, const uint8_t * src, value_type constant, uint32_t size)

Multiplies a field element buffer with a constant, and afterwards adds the product to a second buffer. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest + (constant * src)

Parameter dest:
The buffer containing the augends, and the destination for the resulting sums.
Parameter src:
The buffer containing the multiplicands.
Parameter constant:
The constant multiplier.
Parameter size:
The size of the provided buffers.

void region_multiply_constant (uint8_t * dest, value_type constant, uint32_t size)

Multiplies a field element buffer with a constant. It is assumed that the buffer contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest * constant

Parameter dest:
The buffer containing the multiplicands, and the destination for the resulting products.
Parameter constant:
The constant multiplier.
Parameter size:
The size of the provided buffers.

void region_multiply_subtract (uint8_t * dest, const uint8_t * src, value_type constant, uint32_t size)

Multiplies a field element buffer with a constant, and afterwards subtracts the product from a second buffer. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest - (constant * src)

Parameter dest:
The buffer containing the minuends, and the destination for the resulting differences.
Parameter src:
The buffer containing the multiplicands.
Parameter constant:
The constant multiplier.
Parameter size:
The size of the provided buffers.

void region_subtract (uint8_t * dest, const uint8_t * src, uint32_t size)

Subtracts two field element buffers. It is assumed that the buffers contains “packed” values, i.e., that, if possible, multiple field elements are stored in the same value type. The operation is: dest = dest - src

Parameter dest:
The buffer containing the minuends, and the destination for the resulting differences.
Parameter src:
The buffer containing the subtrahend.
Parameter size:
The size of the provided buffers.

void set_value (uint8_t * elements, uint32_t index, value_type value)

Function for assigning field elements a specific value in a buffer. This function assumes that values are packed.

Parameter elements:
raw buffer that contains the elements to manipulate
Parameter index:
index of element
Parameter value:
The new value to assign to the element

uint32_t size_to_elements (uint32_t size)

Returns the number of field elements that can fit within a certain number of bytes

Parameter size:
the number of bytes to store the field elements
Returns:
the number of field elements stored within the bytes

uint32_t size_to_length (uint32_t size)

Returns the number of value_type elements needed to store a certain number of bytes.

Parameter size:
the number of bytes to store
Returns:
the number of value_type elements that need to be stored

value_type subtract (value_type a, value_type b)

Returns the difference of two field elements.

Parameter a:
The minuend.
Parameter b:
The subtrahend.
Returns:
The difference of a and b.

void vector_dot_product (uint8_t ** dest, const uint8_t ** src, uint8_t ** constants, uint32_t size, uint32_t dest_vectors, uint32_t src_vectors)

Calculates the dot product of the constants and the source vectors. The result is stored in dest. This variant should be optimal for any number of destination vectors. For example, consider the following setup:

  • 2 destination buffers
  • 3 source buffers
  • 2 constant buffers each with 3 constants (one per source) The following calculations will be performed: dest_1 = c_11 * src_1 + c_12 * src_2 + c_13 * src_3 dest_2 = c_21 * src_1 + c_22 * src_2 + c_23 * src_3 where dest_1, dest_2, src_1, src_2, src_3 are all vectors of the same size. c_ij denotes element j of the the i’th constant buffer.
Parameter dest:
Array of pointers to destination buffers
Parameter src:
Array of pointers to source buffers
Parameter constants:
Array of pointers to constant buffers
Parameter size:
The size of the destination and source buffers
Parameter dest_vectors:
The number of destination buffers
Parameter src_vectors:
The number of source vectors

Type Description

using value_type = uint32_t

The value type storing the field elements used for the specified field. E.g. the binary extension field 2^8 uses uint8_t as the value_type.