diff --git a/mps/manual/source/guide/advanced.rst b/mps/manual/source/guide/advanced.rst index c7cc53af363..79cdfd7aaa8 100644 --- a/mps/manual/source/guide/advanced.rst +++ b/mps/manual/source/guide/advanced.rst @@ -877,7 +877,7 @@ Second, the leaf objects must be allocated on ``leaf_ap`` instead of res = mps_ap_create_k(&leaf_ap, leaf_pool, mps_args_none); if (res != MPS_RES_OK) error("Couldn't create leaf objects allocation point"); -Note that the new pool shared a :term:`generation chain` with the old +Note that the new pool shares a :term:`generation chain` with the old pool. This is important, because the leaf objects live and die along with the non-leaf objects of similar ages. diff --git a/mps/manual/source/release.rst b/mps/manual/source/release.rst index 59cd1698535..039b0334732 100644 --- a/mps/manual/source/release.rst +++ b/mps/manual/source/release.rst @@ -48,10 +48,10 @@ Interface changes :c:macro:`MPS_KEY_SPARE`, :c:func:`mps_arena_spare` and :c:func:`mps_arena_spare_set` instead. -#. The format of :term:`telemetry` events has changed: Booleans are no - longer packed into bitfields, but are emitted as unsigned bytes. - This makes it possible to decode telemetry events using Python's - |struct|_. +#. The format of the :term:`telemetry stream` has changed: Booleans + are no longer packed into bitfields, but are emitted as unsigned + bytes. This makes it possible to decode the telemetry stream using + the Python function |struct|_. .. |struct| replace:: ``struct.unpack`` .. _struct: https://docs.python.org/3/library/struct.html#struct.unpack diff --git a/mps/manual/source/topic/deprecated.rst b/mps/manual/source/topic/deprecated.rst index 0241f62d9b2..ceafecba0f9 100644 --- a/mps/manual/source/topic/deprecated.rst +++ b/mps/manual/source/topic/deprecated.rst @@ -898,8 +898,12 @@ Deprecated in version 1.111 .. deprecated:: - If you need access to protected memory for debugging, - :ref:`contact us `. + If you need access to protected memory for debugging a fatal + error, use :c:func:`mps_arena_postmortem` instead. + + If you need access to protected memory and also need to + continue running the MPS afterwards, :ref:`contact us + `. Ensure that the MPS is not protecting any :term:`page` in the :term:`arena` with a :term:`read barrier` or :term:`write diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index e79b0d87a76..7cd65935a7e 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -393,9 +393,9 @@ Varieties --------- The MPS has three *varieties* which have different levels of internal -checking and :ref:`telemetry `. The variety can be -selected at compile time, by defining one of the following -preprocessor constants. If none is specified then +checking, :ref:`topic-error-assertion` and :ref:`topic-telemetry`. The +variety can be selected at compile time, by defining one of the +following preprocessor constants. If none is specified then :c:macro:`CONFIG_VAR_HOT` is the default. @@ -430,8 +430,8 @@ preprocessor constants. If none is specified then in the default ANSI Library, the default assertion handler will not terminate the program. See :c:func:`mps_lib_assert_fail_install`. - Some events are sent to the telemetry stream, namely those not on - the :term:`critical path`. + Some events are sent to the :term:`telemetry stream`, namely those + not on the :term:`critical path`. .. index:: @@ -446,4 +446,4 @@ preprocessor constants. If none is specified then No functions check the consistency of their data structures and consequently there are no assertions. - No events are sent to the telemetry stream. + No events are sent to the :term:`telemetry stream`. diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst index 780e12be7e6..cab915c1830 100644 --- a/mps/manual/source/topic/plinth.rst +++ b/mps/manual/source/topic/plinth.rst @@ -30,8 +30,7 @@ support it needs from the execution environment. The MPS uses the plinth instead #. The plinth gives the :term:`client program` complete control of interaction between the MPS and the user, including - :ref:`assertions ` and :ref:`telemetry - `. + :ref:`topic-error-assertion` and :ref:`topic-telemetry`. The plinth may be provided by the :term:`client program`; however, a sample implementation of the plinth using ANSI Standard C Library diff --git a/mps/manual/source/topic/security.rst b/mps/manual/source/topic/security.rst index 16a148b2a8b..d348a15f3d4 100644 --- a/mps/manual/source/topic/security.rst +++ b/mps/manual/source/topic/security.rst @@ -81,7 +81,7 @@ In its :term:`hot` and :term:`cool` varieties, the MPS contains a events for later analysis and debugging. When using the default :term:`plinth`, the behaviour of the telemetry system is under the control of the environment variable :envvar:`MPS_TELEMETRY_CONTROL`, -and the telemetry stream is written to the file named by the +and the :term:`telemetry stream` is written to the file named by the environment variable :envvar:`MPS_TELEMETRY_FILENAME`. This means that an attacker who can set arbitrary environment diff --git a/mps/manual/source/topic/telemetry.rst b/mps/manual/source/topic/telemetry.rst index f044a2a1a02..b5a6bfa0ec6 100644 --- a/mps/manual/source/topic/telemetry.rst +++ b/mps/manual/source/topic/telemetry.rst @@ -507,8 +507,8 @@ used in queries, for example: If the ``User`` event category is not turned on in the :term:`telemetry filter` (via :c:func:`mps_telemetry_set` or :envvar:`MPS_TELEMETRY_CONTROL`) then the string is not sent - to the telemetry stream. A label is still returned in this - case, but it is useless. + to the :term:`telemetry stream`. A label is still returned in + this case, but it is useless. .. c:function:: void mps_telemetry_label(mps_addr_t addr, mps_label_t label) @@ -518,7 +518,7 @@ used in queries, for example: ``addr`` is an address. - ``label`` is a telemetry label returned from + ``label`` is a :term:`telemetry label` returned from :c:func:`mps_telemetry_intern`. The label will be associated with the address when it appears in @@ -544,12 +544,12 @@ rather than writing it to a file on the local filesystem) then you may be able to do so by providing your own implementation of the :ref:`topic-plinth-io`. -When it first needs to output telemetry, the MPS call the plinth -function :c:func:`mps_io_create` to create an I/O stream. It then -calls :c:func:`mps_io_write` to write binary data to the stream -and :c:func:`mps_io_flush` to flush the stream in response to -:c:func:`mps_telemetry_flush`. By providing your own implementations -of these functions, you can direct the telemetry stream wherever you -like. +When it first needs to output the :term:`telemetry stream`, the MPS +calls the plinth function :c:func:`mps_io_create` to create an I/O +stream. It then calls :c:func:`mps_io_write` to write binary data to +the stream and :c:func:`mps_io_flush` to flush the stream in response +to :c:func:`mps_telemetry_flush`. By providing your own +implementations of these functions, you can direct the telemetry +stream wherever you like. See :ref:`topic-plinth` for details.