Document how the new field is used, maximum value and the interaction
with SYNC timestamps.

Signed-off-by: James Clark <james.clark@linaro.org>
---
 Documentation/trace/coresight/coresight.rst | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
index 806699871b80..80b5ed09d69b 100644
--- a/Documentation/trace/coresight/coresight.rst
+++ b/Documentation/trace/coresight/coresight.rst
@@ -613,8 +613,19 @@ They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/
      - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK
        <coresight-return-stack>`
    * - timestamp
-     - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP
-       <coresight-timestamp>`
+     - Controls generation and interval of timestamps.
+
+       0 = off, 1 = maximum interval .. 15 = minimum interval.
+
+       Values 1 - 14 use a counter that decrements every cycle to generate a
+       timestamp on underflow. The reload value for the counter is 2 raised to
+       the power of timestamp interval - 1. If the value is 1 then the reload
+       value is 1, if the value is 11 then the reload value is 1024 etc.
+
+       Setting the minimum interval (15) will disable the counter generated
+       timestamps, freeing the counter resource, leaving only ones emitted when
+       a SYNC packet is generated for every 4096 bytes of trace.
+
    * - cc_threshold
      - Cycle count threshold value. If nothing is provided here or the provided value is 0, then the
        default value i.e 0x100 will be used. If provided value is less than minimum cycles threshold

-- 
2.34.1

On Wed, Nov 12, 2025 at 03:22:19PM +0000, James Clark wrote:
> Document how the new field is used, maximum value and the interaction
> with SYNC timestamps.
> 
> Signed-off-by: James Clark <james.clark@linaro.org>
> ---
>  Documentation/trace/coresight/coresight.rst | 15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 806699871b80..80b5ed09d69b 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -613,8 +613,19 @@ They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/
>       - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK
>         <coresight-return-stack>`
>     * - timestamp
> -     - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP
> -       <coresight-timestamp>`
> +     - Controls generation and interval of timestamps.
> +
> +       0 = off, 1 = maximum interval .. 15 = minimum interval.

I am struggling to understand the "maximum" and "minimum" usage here.

Seems to me, you are saying:

    1 = maximum frequency .. 15 = minimum frequency

> +
> +       Values 1 - 14 use a counter that decrements every cycle to generate a
> +       timestamp on underflow. The reload value for the counter is 2 raised to
> +       the power of timestamp interval - 1. If the value is 1 then the reload
> +       value is 1, if the value is 11 then the reload value is 1024 etc.

I saw your replying to Randy, yeah, the formula would be much clear.

> +
> +       Setting the minimum interval (15) will disable the counter generated
> +       timestamps, freeing the counter resource, leaving only ones emitted when
> +       a SYNC packet is generated for every 4096 bytes of trace.

"every 4096 bytes" is not always true.

Isn't this defined in TRCSYNCPR.PERIOD?  Maybe just say "... for every
period of trace defined in TRCSYNCPR.PERIOD", or even more general
"... for every period of trace".

Thanks,
Leo

> +
>     * - cc_threshold
>       - Cycle count threshold value. If nothing is provided here or the provided value is 0, then the
>         default value i.e 0x100 will be used. If provided value is less than minimum cycles threshold
> 
> -- 
> 2.34.1
>

On 14/11/2025 6:05 pm, Leo Yan wrote:
> On Wed, Nov 12, 2025 at 03:22:19PM +0000, James Clark wrote:
>> Document how the new field is used, maximum value and the interaction
>> with SYNC timestamps.
>>
>> Signed-off-by: James Clark <james.clark@linaro.org>
>> ---
>>   Documentation/trace/coresight/coresight.rst | 15 +++++++++++++--
>>   1 file changed, 13 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
>> index 806699871b80..80b5ed09d69b 100644
>> --- a/Documentation/trace/coresight/coresight.rst
>> +++ b/Documentation/trace/coresight/coresight.rst
>> @@ -613,8 +613,19 @@ They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/
>>        - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK
>>          <coresight-return-stack>`
>>      * - timestamp
>> -     - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP
>> -       <coresight-timestamp>`
>> +     - Controls generation and interval of timestamps.
>> +
>> +       0 = off, 1 = maximum interval .. 15 = minimum interval.
> 
> I am struggling to understand the "maximum" and "minimum" usage here.
> 
> Seems to me, you are saying:
> 
>      1 = maximum frequency .. 15 = minimum frequency
> 

Yes the documentation was the wrong way around. Will flip it.

>> +
>> +       Values 1 - 14 use a counter that decrements every cycle to generate a
>> +       timestamp on underflow. The reload value for the counter is 2 raised to
>> +       the power of timestamp interval - 1. If the value is 1 then the reload
>> +       value is 1, if the value is 11 then the reload value is 1024 etc.
> 
> I saw your replying to Randy, yeah, the formula would be much clear.
> 
>> +
>> +       Setting the minimum interval (15) will disable the counter generated
>> +       timestamps, freeing the counter resource, leaving only ones emitted when
>> +       a SYNC packet is generated for every 4096 bytes of trace.
> 
> "every 4096 bytes" is not always true.
> 
> Isn't this defined in TRCSYNCPR.PERIOD?  Maybe just say "... for every
> period of trace defined in TRCSYNCPR.PERIOD", or even more general
> "... for every period of trace".
> 
> Thanks,
> Leo
> 

It would only not be true when using a custom config. I can say that 
it's TRCSYNCPR.PERIOD but that the default is 4096 bytes.

>> +
>>      * - cc_threshold
>>        - Cycle count threshold value. If nothing is provided here or the provided value is 0, then the
>>          default value i.e 0x100 will be used. If provided value is less than minimum cycles threshold
>>
>> -- 
>> 2.34.1
>>

On 11/12/25 7:22 AM, James Clark wrote:
> Document how the new field is used, maximum value and the interaction
> with SYNC timestamps.
> 
> Signed-off-by: James Clark <james.clark@linaro.org>
> ---
>  Documentation/trace/coresight/coresight.rst | 15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 806699871b80..80b5ed09d69b 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -613,8 +613,19 @@ They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/
>       - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK
>         <coresight-return-stack>`
>     * - timestamp
> -     - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP
> -       <coresight-timestamp>`
> +     - Controls generation and interval of timestamps.
> +
> +       0 = off, 1 = maximum interval .. 15 = minimum interval.
> +
> +       Values 1 - 14 use a counter that decrements every cycle to generate a
> +       timestamp on underflow. The reload value for the counter is 2 raised to
> +       the power of timestamp interval - 1. If the value is 1 then the reload
> +       value is 1, if the value is 11 then the reload value is 1024 etc.

	  value = 11: 2^11-1 = 2047

Maybe add some parens?


-- 
~Randy

On 14/11/2025 5:02 am, Randy Dunlap wrote:
> 
> 
> On 11/12/25 7:22 AM, James Clark wrote:
>> Document how the new field is used, maximum value and the interaction
>> with SYNC timestamps.
>>
>> Signed-off-by: James Clark <james.clark@linaro.org>
>> ---
>>   Documentation/trace/coresight/coresight.rst | 15 +++++++++++++--
>>   1 file changed, 13 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
>> index 806699871b80..80b5ed09d69b 100644
>> --- a/Documentation/trace/coresight/coresight.rst
>> +++ b/Documentation/trace/coresight/coresight.rst
>> @@ -613,8 +613,19 @@ They are also listed in the folder /sys/bus/event_source/devices/cs_etm/format/
>>        - Session local version of the system wide setting: :ref:`ETM_MODE_RETURNSTACK
>>          <coresight-return-stack>`
>>      * - timestamp
>> -     - Session local version of the system wide setting: :ref:`ETMv4_MODE_TIMESTAMP
>> -       <coresight-timestamp>`
>> +     - Controls generation and interval of timestamps.
>> +
>> +       0 = off, 1 = maximum interval .. 15 = minimum interval.
>> +
>> +       Values 1 - 14 use a counter that decrements every cycle to generate a
>> +       timestamp on underflow. The reload value for the counter is 2 raised to
>> +       the power of timestamp interval - 1. If the value is 1 then the reload
>> +       value is 1, if the value is 11 then the reload value is 1024 etc.
> 
> 	  value = 11: 2^11-1 = 2047
> 
> Maybe add some parens?
> 
> 

Will do. I had them but I removed them because it was in a sentence so 
it made it look like a side note. I think I'll change from words to symbols:

   The reload value for the counter is 2 ^ (interval - 1).

Thanks
James