diff --git a/docs/sphinx/essentials.rst b/docs/sphinx/essentials.rst index 1eab704e8755a9bbce8b013cbe6e41450d9e0ca7..4fdd6336b76ff8cbc04588092a9dfdfbe1ae5326 100644 --- a/docs/sphinx/essentials.rst +++ b/docs/sphinx/essentials.rst @@ -3,6 +3,8 @@ Essentials Play with Maestro Core basic concepts. +.. _cdo: + Core Data Objects (CDOs) ------------------------ @@ -43,13 +45,69 @@ actual data to be transferred, we are going to need a pointer and a size: At this point of the CDO definition the upcoming transfer will indeed consist of data and metadata. +.. _mamba: + +Memory +------ + +Maestro relies internally on the `Mamba <https://mamba-docs.readthedocs.io>`__ +library to manage CDO arrays in memory, in particular for Maestro-sided +allocation -- as opposed to user-provided allocation -- and migration of array +between memory layers. Mamba library is embedded in the Maestro core repo and +can readily be used. + +.. code-block:: c + + mstro_cdo dst_handle; + char* data; size_t len; + mmbArray* ma; + ... + mstro_cdo_demand(dst_handle); + mstro_cdo_access_ptr(dst_handle, (void**)&data, &len); + mstro_cdo_access_mamba_array(dst_handle, &ma); + +Users may access ``demanded`` CDOs pointer and length directly through the +``mstro_cdo_access_ptr()`` function, or access the Mamba array prepared by +Maestro via ``mstro_cdo_access_mamba_array()``. The obtained Mamba array may +then be iterated through with Mamba tile API for instance. See `Mamba +<https://mamba-docs.readthedocs.io>`__ library docs for more information. + +.. _layout: + +Layout +------ + +CDO core attributes also comprise layout attributes, that may be filled by +producers and consumers + +.. code-block:: c + + int64_t patt = ROWMAJ; // 0 for row-major, 1 for column-major + mstro_cdo_attribute_set(cdo, + MSTRO_ATTR_CORE_CDO_LAYOUT_ORDER, + &patt, ...); + +Maestro core takes care of layout transformation that may be needed to accomodate layout attribute required on the consumer side, with respect to the producer-side layout attributes. + +Distributed CDOs on the other hand are expressed via a Mamba layout + +.. code-block:: c + + mmbLayout* dist_layout; + ... + mstro_cdo_attribute_set(cdo, MSTRO_ATTR_CORE_CDO_DIST_LAYOUT, dist_layout, ...); + +.. NOTE:: + + All participants in a distributed CDO transfer use the same CDO name. Maestro core considers a distributed layout as a single CDO still. + .. _cdo_management: CDO Management -------------- Once the metadata is set, the user may ``seal`` the CDO, meaning no more -metadata can be added, and metadata transport may be triggered. +metadata can be added, and metadata transport may be triggered later on. .. code-block:: c @@ -71,7 +129,7 @@ can freely use for its own purposes. mstro_cdo_withdraw(src_handle); After, the user may withdraw the CDO, effectively removing the CDO from the -Maestro Pool. When ``withdrawn``, the CDO data is garanteed to be left +Maestro Pool. When ``withdrawn``, the CDO data is guaranteed to be left unscathed by Maestro. @@ -173,10 +231,7 @@ system transport or "MIO" for object store transport. MIO is Maestro Core interface to object stores, which has one backend that is the `cortx-motr <https://github.com/Seagate/cortx-mio>`__ object store. -Memory Management ------------------ -See Mamba library (coming soon). .. _events: