:orphan: .. index:: pair: group; Change tracking .. _doxid-group__tapi__conf__changed: Change tracking =============== .. toctree:: :hidden: Overview ~~~~~~~~ Record which parts of the configuration a test has touched, so that cleanup can put back exactly what was changed and nothing else. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef :ref:`te_errno` :ref:`tapi_cfg_changed_callback`( const char *tag, size_t start, size_t len, void *ctx ); // global functions :ref:`te_errno` :ref:`tapi_cfg_changed_add_region`(const char* tag, size_t start, size_t len); :ref:`te_errno` :ref:`tapi_cfg_changed_add_region_overlap`(const char* tag, size_t start, size_t len); :ref:`te_errno` :ref:`tapi_cfg_changed_remove_region`(const char* tag, size_t start); :ref:`te_errno` :ref:`tapi_cfg_changed_remove_region_overlap`(const char* tag, size_t start, size_t len); :ref:`te_errno` :ref:`tapi_cfg_changed_process_regions`(const char* tag, :ref:`tapi_cfg_changed_callback`* cb, void* ctx); :ref:`te_errno` :ref:`tapi_cfg_changed_clear_tag`(const char* tag); .. _details-group__tapi__conf__changed: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Record which parts of the configuration a test has touched, so that cleanup can put back exactly what was changed and nothing else. Typedefs -------- .. index:: pair: typedef; tapi_cfg_changed_callback .. _doxid-group__tapi__conf__changed_1ga902b90338432a4dfcbc734e9b107388c: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef :ref:`te_errno` tapi_cfg_changed_callback( const char *tag, size_t start, size_t len, void *ctx ) Type for :ref:`tapi_cfg_changed_process_regions() ` callback functions. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier * - start - Start of a region * - len - Length of a region * - ctx - User data * - 0 - :ref:`tapi_cfg_changed_process_regions() ` would remove the processed region * - TE_EGAIN - the region would be retained .. rubric:: Returns: Status code Global Functions ---------------- .. index:: pair: function; tapi_cfg_changed_add_region .. _doxid-group__tapi__conf__changed_1gac758d46f367fb6bbadf34185ede59dca: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_add_region(const char* tag, size_t start, size_t len) Add a changed region starting at ``start`` of the length ``len``. If there's already a marked region at this point, its length is extended (but never shrunk). No other checks are done, so this function may cause overlapping regions to appear. .. note:: The semantics of region is completely test-specific, they may be blocks, pages byte ranges or anything else. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier (i.e. a block device name) * - start - Start of a region * - len - Length of a region .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_changed_add_region_overlap .. _doxid-group__tapi__conf__changed_1ga9ecdb2d89c8be9cc47161f7400c0a5eb: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_add_region_overlap(const char* tag, size_t start, size_t len) Like :ref:`tapi_cfg_changed_add_region() `, but properly check for overlapping regions and modify them accordingly. This function is more robust than :ref:`tapi_cfg_changed_add_region() ` but is significantly slower because a full list of regions under a given ``tag`` should be retrieved. Basically it performs a union of already marked regions and an interval ``start``.. ``start`` + ``len``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier * - start - Start of a region * - len - Length of a region .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_changed_remove_region .. _doxid-group__tapi__conf__changed_1gaa6590f287ba08723c2d1769e3cc4a0a6: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_remove_region(const char* tag, size_t start) Remove a changed region of any length that starts at ``start``. If there is no region at ``start``, the function does nothing. The region must start exactly at ``start``, no checks for overlapping regions are performed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier * - start - Start of a region .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_changed_remove_region_overlap .. _doxid-group__tapi__conf__changed_1ga2374db109359da0c3c81b533dadd2780: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_remove_region_overlap(const char* tag, size_t start, size_t len) Exclude ``start``.. ``start`` + ``length`` from a list of changed regions. Unlike :ref:`tapi_cfg_changed_remove_region() `, the function performs proper set difference. In particular that may mean that a single region may be split in two. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier * - start - Start of a region * - len - Length of a region .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_changed_process_regions .. _doxid-group__tapi__conf__changed_1gaa4061d3d6b3da53bbd445f94eab584aa: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_process_regions(const char* tag, :ref:`tapi_cfg_changed_callback`* cb, void* ctx) Process all defined regions for a given ``tag`` calling ``cb`` on each of them. The regions are processed in the increased order of their start points. The function fixes possible unsigned overflows (e.g. if a length is ``SIZE_MAX``) and adjust the lengths to removed overlaps, so the callback may see a different length of a region than stored in the Configurator tree. If the callback returns 0, the current region is removed. If the callback return TE_EAGAIN, the region is retained. All other return values cause processing to stop immediately. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier * - cb - Callback * - ctx - User data .. rubric:: Returns: Status code .. index:: pair: function; tapi_cfg_changed_clear_tag .. _doxid-group__tapi__conf__changed_1ga93e740bb2517a52ad78335df250435fa: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_changed_clear_tag(const char* tag) Remove all changed regions belonging to a given ``tag``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tag - Change scope identifier .. rubric:: Returns: Status code