Re: [PATCH 2/2] soc: qcom: dcc: rewrite description of dcc sysfs files

[Souradeep Chowdhury]

On 12/30/2022 7:20 PM, Bagas Sanjaya wrote:
> The description of dcc sysfs files is somewhat confusing and not effective.
> Rewrite it to be clear.
>
> While at it, also use literal code block for config sysfs examples and
> remove redundant examples that are obvious.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> ---
>   Documentation/ABI/testing/debugfs-driver-dcc | 142 ++++++++++---------
>   1 file changed, 76 insertions(+), 66 deletions(-)
>
> diff --git a/Documentation/ABI/testing/debugfs-driver-dcc b/Documentation/ABI/testing/debugfs-driver-dcc
> index a00f4502885b58..27ed5919d21b9c 100644
> --- a/Documentation/ABI/testing/debugfs-driver-dcc
> +++ b/Documentation/ABI/testing/debugfs-driver-dcc
> @@ -3,115 +3,125 @@ Date:           December 2022
>   Contact:        Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>
>   Description:
>   		This file is used to check the status of the dcc
> -		hardware if it's ready to take the inputs. A 'Y'
> -		here indicates dcc is in a ready condition.
> -		Example:
> -		cat /sys/kernel/debug/dcc/.../ready
> +		hardware if it's ready to receive user configurations.
> +		A 'Y' here indicates dcc is ready.
>   
>   What:           /sys/kernel/debug/dcc/.../trigger
>   Date:           December 2022
>   Contact:        Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>
>   Description:
>   		This is the debugfs interface for manual software
> -		triggers. The user can simply enter a 1 against
> -		the debugfs file and enable a manual trigger.
> -		Example:
> -		echo  1 > /sys/kernel/debug/dcc/.../trigger
> +		triggers. The trigger can be invoked by writing '1'
> +		to the file.
>   
>   What:           /sys/kernel/debug/dcc/.../config_reset
>   Date:           December 2022
>   Contact:        Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>
>   Description:
>   		This file is used to reset the configuration of
> -		a dcc driver to the default configuration. This
> -		means that all the previous addresses stored in
> -		the driver gets removed and user needs to enter
> -		the address values from the start.
> -		Example:
> -		echo  1 > /sys/kernel/debug/dcc/../config_reset
> +		a dcc driver to the default configuration. When '1'
> +		is written to the file, all the previous addresses
> +		stored in the driver gets removed and users need to
> +		reconfigure addresses again.
>   
>   What:           /sys/kernel/debug/dcc/.../[list-number]/config
>   Date:		 December 2022
>   Contact:        Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>
>   Description:
>   		This stores the addresses of the registers which
> -		should be read in case of a hardware crash or
> -		manual software triggers. The addresses entered here
> -		are considered under all the 4 types of dcc
> -		instructions Read type, Write type, Read Modify Write
> -		type and Loop type. The lists need to be configured
> -		sequentially and not in a overlapping manner. As an
> -		example user can jump to list x only after list y is
> -		configured and enabled. The format for entering all
> -		types of instructions are explained in examples as
> -		follows:
> +		can be read in case of a hardware crash or manual
> +		software triggers. The input addresses type
> +		can be one of following dcc instructions: read,
> +		write, read-write, and loop type. The lists need to
> +		be configured sequentially and not in a overlapping
> +		manner; e.g. users can jump to list x only after
> +		list y is configured and enabled. The input format for
> +		each type is as follows:
>   
> -	        i) Read Type Instruction
> +	        i) Read instruction
>   
> -		   echo R <1> <2> <3> >/sys/kernel/debug/dcc/../[list-number]/config
> +		   ::
>   
> -		   1->Address to be considered for reading the value.
> +		     echo R <addr> <n> <bus> >/sys/kernel/debug/dcc/../[list-number]/config
>   
> -		   2->The word count of the addresses, read n words
> -		      starting from address <1>. Each word is of 32 bits.
> -		      If not entered 1 is considered.
> +		   where:
>   
> -		   3->Can be 'apb' or 'ahb' which indicates if it is apb or ahb
> -		      bus respectively. If not entered ahb is considered.
> +		   <addr>
> +			The address to be read.
>   
> -		ii) Write Type Instruction
> +		   <n>
> +			The addresses word count, starting from address <1>.
> +			Each word is 32 bits (4 bytes). If omitted, defaulted
> +			to 1.
>   
> -		    echo W <1> <2> <3> > /sys/kernel/debug/dcc/../[list-number]/config
> +		   <bus type>
> +			The bus type, which can be either 'apb' or 'ahb'.
> +			The default is 'ahb' if leaved out.
>   
> -		    1->Address to be considered for writing the value.
> +		ii) Write instruction
>   
> -		    2->The value that needs to be written at the location.
> +		    ::
>   
> -		    3->Can be a 'apb' or 'ahb' which indicates if it is apb or ahb
> -		       but respectively.
> +		      echo W <addr> <n> <bus type> > /sys/kernel/debug/dcc/../[list-number]/config
>   
> -	        iii) Read Modify Write type instruction
> +		    where:
>   
> -		     echo RW <1> <2> <3> > /sys/kernel/debug/dcc/../[list-number]/config
> +		    <addr>
> +			The address to be written.
>   
> -		     1->The address which needs to be considered for read then write.
> +		    <n>
> +			The value to be written at <addr>.
>   
> -		     2->The value that needs to be written on the address.
> +		    <bus type>
> +			The bus type, which can be either 'apb' or 'ahb'.
>   
> -		     3->The mask of the value to be written.
> +	        iii) Read-write instruction
>   
> -		iv) Loop Type Instruction
> +		     ::
>   
> -		    echo L <1> <2> <3> > /sys/kernel/debug/dcc/../[list-number]/config
> +		       echo RW <addr> <n> <mask> > /sys/kernel/debug/dcc/../[list-number]/config
>   
> -		    1->The loop count, the number of times the value of the addresses will be
> -		       captured.
> +		     where:
>   
> -		    2->The address count, total number of addresses to be entered in this
> -		       instruction.
> +		     <addr>
> +			The address to be read and written.
>   
> -		    3->The series of addresses to be entered separated by a space like <addr1>
> -		       <addr2>... and so on.
> +		     <n>
> +		        The value to be written at <addr>.
> +
> +		     <mask>
> +			The value mask.
> +
> +		iv) Loop instruction
> +
> +		    ::
> +
> +		      echo L <loop count> <address count> <address>... > /sys/kernel/debug/dcc/../[list-number]/config
> +
> +		    where:
> +
> +		    <loop count>
> +			Number of iterations
> +
> +		    <address count>
> +			total number of addresses to be written
> +
> +		    <address>
> +			Space-separated list of addresses.
>   
>   What:           /sys/kernel/debug/dcc/.../[list-number]/enable
>   Date:           December 2022
>   Contact:        Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>
>   Description:
>   		This debugfs interface is used for enabling the
> -		the dcc hardware. Enable file is kept under the
> -		directory list number for which the user wants
> -		to enable it. For example if the user wants to
> -		enable list 1, then he should go for
> -		echo 1 > /sys/kernel/debug/dcc/.../1/enable.
> -		On enabling the dcc, all the addresses entered
> +		the dcc hardware. A file named "enable" is in the
> +		directory list number where users can enable/disable
> +		the specific list by writing boolean (1 or 0) to the
> +		file.
> +
> +		On enabling the dcc, all the addresses specified
>   		by the user for the corresponding list is written
>   		into dcc sram which is read by the dcc hardware
> -		on manual or crash induced triggers. Lists should
> -		be enabled sequentially.For example after configuring
> -		addresses for list 1 and enabling it, a user can
> -		proceed to enable list 2 or vice versa.
> -		Example:
> -		echo  0 > /sys/kernel/debug/dcc/.../[list-number]/enable
> -		(disable dcc for the corresponding list number)
> -		echo  1 > /sys/kernel/debug/dcc/.../[list-number]/enable
> -		(enable dcc for the corresponding list number)
> +		on manual or crash induced triggers. Lists must
> +		be configured and enabled sequentially, e.g. list
> +		2 can only be enabled when list 1 have so.

Acked-by:Souradeep Chowdhury <quic_schowdhu@xxxxxxxxxxx>