Layout: Description of Data Organization¶

group aml_layout

Low level description of data organization at the byte granularity.

Layout describes how contiguous elements of a flat memory address space are organized into a multidimensional array of elements of a fixed size. The abstraction provide functions to build layouts, access elements, reshape a layout, or subset a layout.

Layouts are characterized by:

A pointer to the data it describes
A set of dimensions on which data spans.
A stride in between elements of a dimension.
A pitch indicating the space between contiguous elements of a dimension.

For a definition of row and columns of matrices see : https://en.wikipedia.org/wiki/Matrix_(mathematics)

The figure below describes a 2D layout with a sub-layout (obtained with aml_layout_slice()) operation. The sub-layout has a stride of 1 element along the second dimension. The slice has an offset of 1 element along the same dimension, and its pitch is the pitch of the original layout. Calling aml_layout_deref() on this sublayout with appropriate coordinates will return a pointer to elements noted (coor_x, coord_y). ../_images/layout.png

See also

aml_layout_slice()

Access to specific elements of a layout can be done with the aml_layout_deref() function. Access to an element is always done relatively to the dimensions’ order set by the user at creation time. However, internally, the library will always store dimensions in such a way that elements along the first dimension are contiguous in memory. This order is defined with the value AML_LAYOUT_ORDER_COLUMN_MAJOR (AML_LAYOUT_ORDER_FORTRAN). See: https://en.wikipedia.org/wiki/Row-_and_column-major_order

Additionally, AML provides access to elements without the overhead of user order choice through function suffixed with “native”.

The layout abstraction also provides a function to reshape data with a different set of dimensions. A reshaped layout will access the same data but with different coordinates as depicted in the figure below.

See also

aml_layout_deref()

See also

aml_layout_deref_native()

See also

aml_layout_dims_native()

See also

aml_layout_slice_native()

See also

aml_layout_reshape()

See also

aml_layout_dense

Defines

AML_LAYOUT_ORDER_FORTRAN¶

Tag specifying user storage of dimensions inside a layout. Layout order is the first bit in an integer bitmask.

See also

AML_LAYOUT_ORDER() This tag will store dimensions in the order provided by the user, i.e., elements of the last dimension will be contiguous in memory.

AML_LAYOUT_ORDER_C¶

Tag specifying user storage of dimensions inside a layout. Layout order is the first bit in an integer bitmask.

See also

AML_LAYOUT_ORDER() This tag will store dimensions in the reverse order to the one provided by the user, i.e., elements of the first dimension will be contiguous in memory. This storage is the actual storage used by the library inside the structure.

AML_LAYOUT_ORDER_COLUMN_MAJOR¶

This is equivalent to AML_LAYOUT_ORDER_FORTRAN.

See also

AML_LAYOUT_ORDER_FORTRAN

AML_LAYOUT_ORDER_ROW_MAJOR¶

This is equivalent to AML_LAYOUT_ORDER_C.

See also

AML_LAYOUT_ORDER_C

AML_LAYOUT_ORDER(x)¶

Get the order bit of an integer bitmask. The value can be further checked for equality with AML_LAYOUT_ORDER_* values.

Parameters:

x – [in] an integer with the first bit set to the order value.

Returns:

an integer containing only the bit order.

Functions

void *aml_layout_deref(const struct aml_layout *layout, const size_t *coords)¶

Dereference an element of a layout by its coordinates.

Parameters:

layout – [in] an initialized layout.
coords – [in] the coordinates on which to access data.

Returns:

a pointer to the dereferenced element on success ; NULL on failure with aml_errno set to the error reason:

AML_EINVAL if coordinate are out of bound
See specific implementation of layout for further information on possible error codes.

void *aml_layout_deref_safe(const struct aml_layout *layout, const size_t *coords)¶

Equivalent to aml_layout_deref() but with bound checking on coordinates.

See also

aml_layout_deref()

Parameters:

layout – [in] an initialized layout.
coords – [in] the coordinates on which to access data.

Returns:

a pointer to dereferenced element on success ; NULL on failure with aml_errno set to the error reason.

void *aml_layout_rawptr(const struct aml_layout *layout)¶

Return a pointer to the first byte of the buffer this layout maps to.

Parameters:: layout – [in] an initialized layout
Returns:: a raw pointer to the start of the layout, NULL on error.

int aml_layout_order(const struct aml_layout *layout)¶

Get the order in which dimensions of the layout are supposed to be accessed by the user.

See also

AML_LAYOUT_ORDER()

Parameters:: layout – [in] an initialized layout.
Returns:: a bitmask with order bit on success, an AML error (<0) on failure. Output value can be further checked against order AML_LAYOUT_ORDER flags by using the macro AML_LAYOUT_ORDER() on the output value.

int aml_layout_dims(const struct aml_layout *layout, size_t *dims)¶

Return the layout dimensions in the user order.

Parameters:

layout – [in] an initialized layout.
dims – [out] a non-NULL array of dimensions to fill. It is supposed to be large enough to contain aml_layout_ndims() elements.

Returns:

0 on success, else an AML error code.

size_t aml_layout_ndims(const struct aml_layout *layout)¶

Provide the number of dimensions in the layout.

Parameters:: layout – [in] an initialized layout.
Returns:: the number of dimensions in the layout.

size_t aml_layout_element_size(const struct aml_layout *layout)¶

Return the size of layout elements.

Parameters:: layout – [in] an initialized layout.
Returns:: the size of elements stored with this layout.

int aml_layout_reshape(const struct aml_layout *layout, struct aml_layout **reshaped_layout, const size_t ndims, const size_t *dims)¶

Reshape the layout with different dimensions. This function checks that the number of elements of the reshaped layout matches the number of elements in the original layout. Additional constraint may apply depending on the layout implementation.

Parameters:

layout – [in] an initialized layout.
reshaped_layout – [out] a newly allocated layout with the queried shape on succes.
ndims – [in] the number of dimensions of the new layout.
dims – [in] the number of elements along each dimension of the new layout.

Returns:

0 on success, an AML error code otherwise.

int aml_layout_slice(const struct aml_layout *layout, struct aml_layout **reshaped_layout, const size_t *offsets, const size_t *dims, const size_t *strides)¶

Return a layout that is a subset of another layout. The number of elements to subset along each dimension must be compatible with offsets and strides. This function checks that the number of elements along each dimension of the slice actually fits in the original layout.

Parameters:

layout – [in] an initialized layout.
reshaped_layout – [out] a pointer where to store the address of a newly allocated layout with the queried subset of the original layout on succes.
dims – [in] the number of elements of the slice along each dimension.
offsets – [in] the index of the first element of the slice in each dimension. If NULL, offset is set to 0.
strides – [in] the displacement (in number of elements) between elements of the slice. If NULL, stride is set to 1.

Returns:

0 on success, else an AML error code (<0).

int aml_layout_fprintf(FILE *stream, const char *prefix, const struct aml_layout *layout)¶

Print on the file handle the metadata associated with this layout.

Parameters:

stream – [in] the stream to print on
prefix – [in] prefix to use on all lines
layout – [in] layout to print

Returns:

0 if successful, an AML error code otherwise.

int aml_layout_duplicate(const struct aml_layout *src, struct aml_layout **out, void *ptr)¶

Create a duplicate of the layout (independent deep copy of all its metadata, no user data is actually copied).

Parameters:

src – [in] the layout to duplicate
out – [out] a pointer to where to store the new layout
ptr – [in] if not NULL use this pointer as the new layout raw pointer.

Returns:

-AML_ENOMEM if layout allocation failed.

Returns:

-AML_EINVAL if src or dest are NULL.

Returns:

AML_SUCCESS if copy succeeded.

void aml_layout_destroy(struct aml_layout **layout)¶

Destroy (free) a layout, irrespective of its type.

Parameters:: layout – [inout] the layout to destroy. NULL on return.

struct aml_layout¶: #include <aml.h>

Structure definition of AML layouts

struct aml_layout_ops¶: #include <aml.h>

List of operators implemented by layouts.

Implementations¶

AML Dense Layouts

AML Layouts Native Ops