:orphan: .. index:: pair: group; Data change tracking .. _doxid-group__tapi__conf__changed: Data change tracking ==================== .. toctree:: :hidden: Overview ~~~~~~~~ .. 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 ~~~~~~~~~~~~~~~~~~~~~~ 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. 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