* [PATCH v2 30/79] docs: Debugging390.txt: convert table to ascii artwork [not found] <cover.1555938375.git.mchehab+samsung@kernel.org> @ 2019-04-22 13:27 ` Mauro Carvalho Chehab 2019-04-22 13:27 ` [PATCH v2 32/79] s390: include/asm/debug.h add kerneldoc markups Mauro Carvalho Chehab [not found] ` <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org> 2 siblings, 0 replies; 8+ messages in thread From: Mauro Carvalho Chehab @ 2019-04-22 13:27 UTC (permalink / raw) To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, linux-s390 The first bit/value table inside the document is very hard to read and won't fit ReST format. Also, some columns aren't properly aligned. Convert it to a nice ascii artwork table with makes it easier to read as plain text and is compatible with ReST format parser on Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> --- Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------ 1 file changed, 120 insertions(+), 90 deletions(-) diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 5ae7f868a007..c35804c238ad 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -78,96 +78,126 @@ e.g. switching address translation off requires that you have a logical=physical mapping for the address you are currently running at. - Bit Value -s/390 z/Architecture -0 0 Reserved ( must be 0 ) otherwise specification exception occurs. - -1 1 Program Event Recording 1 PER enabled, - PER is used to facilitate debugging e.g. single stepping. - -2-4 2-4 Reserved ( must be 0 ). - -5 5 Dynamic address translation 1=DAT on. - -6 6 Input/Output interrupt Mask - -7 7 External interrupt Mask used primarily for interprocessor - signalling and clock interrupts. - -8-11 8-11 PSW Key used for complex memory protection mechanism - (not used under linux) - -12 12 1 on s/390 0 on z/Architecture - -13 13 Machine Check Mask 1=enable machine check interrupts - -14 14 Wait State. Set this to 1 to stop the processor except for - interrupts and give time to other LPARS. Used in CPU idle in - the kernel to increase overall usage of processor resources. - -15 15 Problem state ( if set to 1 certain instructions are disabled ) - all linux user programs run with this bit 1 - ( useful info for debugging under VM ). - -16-17 16-17 Address Space Control - - 00 Primary Space Mode: - The register CR1 contains the primary address-space control ele- - ment (PASCE), which points to the primary space region/segment - table origin. - - 01 Access register mode - - 10 Secondary Space Mode: - The register CR7 contains the secondary address-space control - element (SASCE), which points to the secondary space region or - segment table origin. - - 11 Home Space Mode: - The register CR13 contains the home space address-space control - element (HASCE), which points to the home space region/segment - table origin. - - See "Address Spaces on Linux for s/390 & z/Architecture" below - for more information about address space usage in Linux. - -18-19 18-19 Condition codes (CC) - -20 20 Fixed point overflow mask if 1=FPU exceptions for this event - occur ( normally 0 ) - -21 21 Decimal overflow mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -22 22 Exponent underflow mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -23 23 Significance Mask if 1=FPU exceptions for this event occur - ( normally 0 ) - -24-31 24-30 Reserved Must be 0. - - 31 Extended Addressing Mode - 32 Basic Addressing Mode - Used to set addressing mode - PSW 31 PSW 32 - 0 0 24 bit - 0 1 31 bit - 1 1 64 bit - -32 1=31 bit addressing mode 0=24 bit addressing mode (for backward - compatibility), linux always runs with this bit set to 1 - -33-64 Instruction address. - 33-63 Reserved must be 0 - 64-127 Address - In 24 bits mode bits 64-103=0 bits 104-127 Address - In 31 bits mode bits 64-96=0 bits 97-127 Address - Note: unlike 31 bit mode on s/390 bit 96 must be zero - when loading the address with LPSWE otherwise a - specification exception occurs, LPSW is fully backward - compatible. - ++-------------------------+-------------------------------------------------+ +| Bit | | ++--------+----------------+ Value | +| s/390 | z/Architecture | | ++========+================+=================================================+ +| 0 | 0 | Reserved (must be 0) otherwise specification | +| | | exception occurs. | ++--------+----------------+-------------------------------------------------+ +| 1 | 1 | Program Event Recording 1 PER enabled, | +| | | PER is used to facilitate debugging e.g. | +| | | single stepping. | ++--------+----------------+-------------------------------------------------+ +| 2-4 | 2-4 | Reserved (must be 0). | ++--------+----------------+-------------------------------------------------+ +| 5 | 5 | Dynamic address translation 1=DAT on. | ++--------+----------------+-------------------------------------------------+ +| 6 | 6 | Input/Output interrupt Mask | ++--------+----------------+-------------------------------------------------+ +| 7 | 7 | External interrupt Mask used primarily for | +| | | interprocessor signalling and clock interrupts. | ++--------+----------------+-------------------------------------------------+ +| 8-11 | 8-11 | PSW Key used for complex memory protection | +| | | mechanism (not used under linux) | ++--------+----------------+-------------------------------------------------+ +| 12 | 12 | 1 on s/390 0 on z/Architecture | ++--------+----------------+-------------------------------------------------+ +| 13 | 13 | Machine Check Mask 1=enable machine check | +| | | interrupts | ++--------+----------------+-------------------------------------------------+ +| 14 | 14 | Wait State. Set this to 1 to stop the processor | +| | | except for interrupts and give time to other | +| | | LPARS. Used in CPU idle in the kernel to | +| | | increase overall usage of processor resources. | ++--------+----------------+-------------------------------------------------+ +| 15 | 15 | Problem state (if set to 1 certain instructions | +| | | are disabled). All linux user programs run with | +| | | this bit 1 (useful info for debugging under VM).| ++--------+----------------+-------------------------------------------------+ +| 16-17 | 16-17 | Address Space Control | +| | | | +| | | 00 Primary Space Mode: | +| | | | +| | | The register CR1 contains the primary | +| | | address-space control element (PASCE), which | +| | | points to the primary space region/segment | +| | | table origin. | +| | | | +| | | 01 Access register mode | +| | | | +| | | 10 Secondary Space Mode: | +| | | | +| | | The register CR7 contains the secondary | +| | | address-space control element (SASCE), which | +| | | points to the secondary space region or | +| | | segment table origin. | +| | | | +| | | 11 Home Space Mode: | +| | | | +| | | The register CR13 contains the home space | +| | | address-space control element (HASCE), which | +| | | points to the home space region/segment | +| | | table origin. | +| | | | +| | | See "Address Spaces on Linux for s/390 & | +| | | z/Architecture" below for more information | +| | | about address space usage in Linux. | ++--------+----------------+-------------------------------------------------+ +| 18-19 | 18-19 | Condition codes (CC) | ++--------+----------------+-------------------------------------------------+ +| 20 | 20 | Fixed point overflow mask if 1=FPU exceptions | +| | | for this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 21 | 21 | Decimal overflow mask if 1=FPU exceptions for | +| | | this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 22 | 22 | Exponent underflow mask if 1=FPU exceptions | +| | | for this event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 23 | 23 | Significance Mask if 1=FPU exceptions for this | +| | | event occur (normally 0) | ++--------+----------------+-------------------------------------------------+ +| 24-31 | 24-30 | Reserved Must be 0. | +| +----------------+-------------------------------------------------+ +| | 31 | Extended Addressing Mode | +| +----------------+-------------------------------------------------+ +| | 32 | Basic Addressing Mode | +| | | | +| | | Used to set addressing mode | +| | | | +| | | +---------+----------+----------+ | +| | | | PSW 31 | PSW 32 | | | +| | | +---------+----------+----------+ | +| | | | 0 | 0 | 24 bit | | +| | | +---------+----------+----------+ | +| | | | 0 | 1 | 31 bit | | +| | | +---------+----------+----------+ | +| | | | 1 | 1 | 64 bit | | +| | | +---------+----------+----------+ | ++--------+----------------+-------------------------------------------------+ +| 32 | | 1=31 bit addressing mode 0=24 bit addressing | +| | | mode (for backward compatibility), linux | +| | | always runs with this bit set to 1 | ++--------+----------------+-------------------------------------------------+ +| 33-64 | | Instruction address. | +| +----------------+-------------------------------------------------+ +| | 33-63 | Reserved must be 0 | +| +----------------+-------------------------------------------------+ +| | 64-127 | Address | +| | | | +| | | - In 24 bits mode bits 64-103=0 bits 104-127 | +| | | Address | +| | | - In 31 bits mode bits 64-96=0 bits 97-127 | +| | | Address | +| | | | +| | | Note: | +| | | unlike 31 bit mode on s/390 bit 96 must be | +| | | zero when loading the address with LPSWE | +| | | otherwise a specification exception occurs, | +| | | LPSW is fully backward compatible. | ++--------+----------------+-------------------------------------------------+ Prefix Page(s) -------------- -- 2.20.1 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH v2 32/79] s390: include/asm/debug.h add kerneldoc markups [not found] <cover.1555938375.git.mchehab+samsung@kernel.org> 2019-04-22 13:27 ` [PATCH v2 30/79] docs: Debugging390.txt: convert table to ascii artwork Mauro Carvalho Chehab @ 2019-04-22 13:27 ` Mauro Carvalho Chehab [not found] ` <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org> 2 siblings, 0 replies; 8+ messages in thread From: Mauro Carvalho Chehab @ 2019-04-22 13:27 UTC (permalink / raw) To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, linux-s390 Instead of keeping the documentation inside s390dbf.rst, move them to arch/s390/include/asm/debug.h, using standard kernel-doc markups. Keeping the documentation close to the code helps to keep it updated. It also makes easier to document other stuff inside debug.h, as all it needs is to add kernel-doc markups inside it, as the file will be already be included at the produced documentation. - Those were converted to kerneldoc using this script specially designed to parse ths file, and manually editted: <script> use strict; my $mode = ""; my $parameter = ""; my $ret = ""; my $descr = ""; sub add_var($) { my $ln = shift; $ln =~ s/^\s+//; $ln =~ s/\s+$//; return if ($ln eq ""); $ln =~ s/^(\S+)\s+/$1\t/; print " * \@$ln\n"; } sub add_return($) { my $ln = shift; print " *\n * Return:\n" if ($mode ne "Return Value:"); $ln =~ s/^\s+//; $ln =~ s/\s+$//; return if ($ln eq ""); print " * - $ln\n"; } sub add_description($) { my $ln = shift; print " *\n * \n" if ($mode ne "Description:"); $ln =~ s/^\s+//; $ln =~ s/\s+$//; return if ($ln eq ""); print " * $ln\n"; } sub flush_results() { print " */\n\n"; } while (<>) { if (m/^[\-]+$/) { flush_results(); $mode = ""; $parameter = ""; $ret = ""; $descr = ""; next; } if (m/(Parameter:)(.*)/) { print " *\n" if ($mode eq "func"); add_var($2); $mode = $1; next; } if (m/(Return Value:)(.*)/) { add_return($2); $mode = $1; next; } if (m/(Description:)(.*)/) { add_description($2); $mode = $1; next; } if ($mode eq "Parameter:") { add_var($_); next; } if ($mode eq "Return Value:") { add_return($_); next; } if ($mode eq "Description:") { add_description($_); next; } next if (m/^\s*$/); if (m/^\S+.*\s\*?(\S+)\s*\(/) { if ($mode eq "") { print "/**\n * $1()\n"; } else { print " * $1()\n"; } $mode="func"; } } flush_results(); </script> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> --- Documentation/s390/s390dbf.rst | 672 +-------------------------------- arch/s390/include/asm/debug.h | 231 ++++++++++++ 2 files changed, 232 insertions(+), 671 deletions(-) diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst index ec2a1faa414b..d2595b548879 100644 --- a/Documentation/s390/s390dbf.rst +++ b/Documentation/s390/s390dbf.rst @@ -104,684 +104,14 @@ the "debug_stoppable" sysctl. If you set "debug_stoppable" to 0 the debug feature cannot be stopped. If the debug feature is already stopped, it will stay deactivated. ----------------------------------------------------------------------------- - Kernel Interfaces: ------------------ -:: - - debug_info_t *debug_register(char *name, int pages, int nr_areas, - int buf_size); - -Parameter: - name: - Name of debug log (e.g. used for debugfs entry) - pages: - Number of pages, which will be allocated per area - nr_areas: - Number of debug areas - buf_size: - Size of data area in each debug entry - -Return Value: - Handle for generated debug area - - NULL if register failed - -Description: Allocates memory for a debug log - Must not be called within an interrupt handler - ----------------------------------------------------------------------------- - -:: - - debug_info_t *debug_register_mode(char *name, int pages, int nr_areas, - int buf_size, mode_t mode, uid_t uid, - gid_t gid); - -Parameter: - name: - Name of debug log (e.g. used for debugfs entry) - pages: - Number of pages, which will be allocated per area - nr_areas: - Number of debug areas - buf_size: - Size of data area in each debug entry - mode: - File mode for debugfs files. E.g. S_IRWXUGO - uid: - User ID for debugfs files. Currently only 0 is - supported. - gid: - Group ID for debugfs files. Currently only 0 is - supported. - -Return Value: - Handle for generated debug area - - NULL if register failed - -Description: - Allocates memory for a debug log - Must not be called within an interrupt handler - ---------------------------------------------------------------------------- - -:: - - void debug_unregister (debug_info_t * id); - -Parameter: - id: - handle for debug log - -Return Value: - none - -Description: - frees memory for a debug log and removes all registered debug - views. - - Must not be called within an interrupt handler - ---------------------------------------------------------------------------- - -:: - - void debug_set_level (debug_info_t * id, int new_level); - -Parameter: id: handle for debug log - new_level: new debug level - -Return Value: - none - -Description: - Sets new actual debug level if new_level is valid. - ---------------------------------------------------------------------------- - -:: - - bool debug_level_enabled (debug_info_t * id, int level); - -Parameter: - id: - handle for debug log - level: - debug level - -Return Value: - True if level is less or equal to the current debug level. - -Description: - Returns true if debug events for the specified level would be - logged. Otherwise returns false. - ---------------------------------------------------------------------------- - -:: - - void debug_stop_all(void); - -Parameter: - none - -Return Value: - none - -Description: - stops the debug feature if stopping is allowed. Currently - used in case of a kernel oops. - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_event (debug_info_t* id, int level, void* data, - int length); - -Parameter: - id: - handle for debug log - level: - debug level - data: - pointer to data for debug entry - length: - length of data in bytes - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_int_event (debug_info_t * id, int level, - unsigned int data); - debug_entry_t* debug_long_event(debug_info_t * id, int level, - unsigned long data); - -Parameter: - id: - handle for debug log - level: - debug level - data: - integer value for debug entry - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_text_event (debug_info_t * id, int level, - const char* data); - -Parameter: - id: - handle for debug log - level: - debug level - data: - string for debug entry - -Return Value: - Address of written debug entry - -Description: - writes debug entry in ascii format to active debug area - (if level <= actual debug level) - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_sprintf_event (debug_info_t * id, int level, - char* string,...); - -Parameter: - id: - handle for debug log - level: - debug level - string: - format string for debug entry - ...: - varargs used as in sprintf() - -Return Value: Address of written debug entry - -Description: - writes debug entry with format string and varargs (longs) to - active debug area (if level $<=$ actual debug level). - floats and long long datatypes cannot be used as varargs. - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_exception (debug_info_t* id, int level, void* data, - int length); - -Parameter: - id: - handle for debug log - level: - debug level - data: - pointer to data for debug entry - length: - length of data in bytes - -Return Value: - Address of written debug entry - -Description: - writes debug entry to active debug area (if level <= actual - debug level) and switches to next debug area - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_int_exception (debug_info_t * id, int level, - unsigned int data); - debug_entry_t* debug_long_exception(debug_info_t * id, int level, - unsigned long data); - -Parameter: id: handle for debug log - level: debug level - data: integer value for debug entry - -Return Value: Address of written debug entry - -Description: writes debug entry to active debug area (if level <= actual - debug level) and switches to next debug area - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_text_exception (debug_info_t * id, int level, - const char* data); - -Parameter: id: handle for debug log - level: debug level - data: string for debug entry - -Return Value: Address of written debug entry - -Description: writes debug entry in ascii format to active debug area - (if level <= actual debug level) and switches to next debug - area - ---------------------------------------------------------------------------- - -:: - - debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level, - char* string,...); - -Parameter: id: handle for debug log - level: debug level - string: format string for debug entry - ...: varargs used as in sprintf() - -Return Value: Address of written debug entry - -Description: writes debug entry with format string and varargs (longs) to - active debug area (if level $<=$ actual debug level) and - switches to next debug area. - floats and long long datatypes cannot be used as varargs. - ---------------------------------------------------------------------------- - -:: - - int debug_register_view (debug_info_t * id, struct debug_view *view); - -Parameter: id: handle for debug log - view: pointer to debug view struct - -Return Value: 0 : ok - < 0: Error - -Description: registers new debug view and creates debugfs dir entry - ---------------------------------------------------------------------------- - -:: - - int debug_unregister_view (debug_info_t * id, struct debug_view *view); - -Parameter: id: handle for debug log - view: pointer to debug view struct - -Return Value: 0 : ok - < 0: Error - -Description: unregisters debug view and removes debugfs dir entry - - +.. kernel-doc:: arch/s390/include/asm/debug.h Predefined views: ----------------- -extern struct debug_view debug_hex_ascii_view; - -extern struct debug_view debug_raw_view; - -extern struct debug_view debug_sprintf_view; - -Examples --------- - -:: - - /* - * hex_ascii- + raw-view Example - */ - - #include <linux/init.h> - #include <asm/debug.h> - - static debug_info_t* debug_info; - - static int init(void) - { - /* register 4 debug areas with one page each and 4 byte data field */ - - debug_info = debug_register ("test", 1, 4, 4 ); - debug_register_view(debug_info,&debug_hex_ascii_view); - debug_register_view(debug_info,&debug_raw_view); - - debug_text_event(debug_info, 4 , "one "); - debug_int_exception(debug_info, 4, 4711); - debug_event(debug_info, 3, &debug_info, 4); - - return 0; - } - - static void cleanup(void) - { - debug_unregister (debug_info); - } - - module_init(init); - module_exit(cleanup); - ---------------------------------------------------------------------------- - -:: - - /* - * sprintf-view Example - */ - - #include <linux/init.h> - #include <asm/debug.h> - - static debug_info_t* debug_info; - - static int init(void) - { - /* register 4 debug areas with one page each and data field for */ - /* format string pointer + 2 varargs (= 3 * sizeof(long)) */ - - debug_info = debug_register ("test", 1, 4, sizeof(long) * 3); - debug_register_view(debug_info,&debug_sprintf_view); - - debug_sprintf_event(debug_info, 2 , "first event in %s:%i\n",__FILE__,__LINE__); - debug_sprintf_exception(debug_info, 1, "pointer to debug info: %p\n",&debug_info); - - return 0; - } - - static void cleanup(void) - { - debug_unregister (debug_info); - } - - module_init(init); - module_exit(cleanup); - -Debugfs Interface ------------------ -Views to the debug logs can be investigated through reading the corresponding -debugfs-files: - -Example:: - - > ls /sys/kernel/debug/s390dbf/dasd - flush hex_ascii level pages raw - > cat /sys/kernel/debug/s390dbf/dasd/hex_ascii | sort -k2,2 -s - 00 00974733272:680099 2 - 02 0006ad7e 07 ea 4a 90 | .... - 00 00974733272:682210 2 - 02 0006ade6 46 52 45 45 | FREE - 00 00974733272:682213 2 - 02 0006adf6 07 ea 4a 90 | .... - 00 00974733272:682281 1 * 02 0006ab08 41 4c 4c 43 | EXCP - 01 00974733272:682284 2 - 02 0006ab16 45 43 4b 44 | ECKD - 01 00974733272:682287 2 - 02 0006ab28 00 00 00 04 | .... - 01 00974733272:682289 2 - 02 0006ab3e 00 00 00 20 | ... - 01 00974733272:682297 2 - 02 0006ad7e 07 ea 4a 90 | .... - 01 00974733272:684384 2 - 00 0006ade6 46 52 45 45 | FREE - 01 00974733272:684388 2 - 00 0006adf6 07 ea 4a 90 | .... - -See section about predefined views for explanation of the above output! - -Changing the debug level ------------------------- - -Example:: - - - > cat /sys/kernel/debug/s390dbf/dasd/level - 3 - > echo "5" > /sys/kernel/debug/s390dbf/dasd/level - > cat /sys/kernel/debug/s390dbf/dasd/level - 5 - -Flushing debug areas --------------------- -Debug areas can be flushed with piping the number of the desired -area (0...n) to the debugfs file "flush". When using "-" all debug areas -are flushed. - -Examples: - -1. Flush debug area 0:: - - > echo "0" > /sys/kernel/debug/s390dbf/dasd/flush - -2. Flush all debug areas:: - - > echo "-" > /sys/kernel/debug/s390dbf/dasd/flush - -Changing the size of debug areas ------------------------------------- -It is possible the change the size of debug areas through piping -the number of pages to the debugfs file "pages". The resize request will -also flush the debug areas. - -Example: - -Define 4 pages for the debug areas of debug feature "dasd":: - - > echo "4" > /sys/kernel/debug/s390dbf/dasd/pages - -Stooping the debug feature --------------------------- -Example: - -1. Check if stopping is allowed:: - - > cat /proc/sys/s390dbf/debug_stoppable - -2. Stop debug feature:: - - > echo 0 > /proc/sys/s390dbf/debug_active - -lcrash Interface ----------------- -It is planned that the dump analysis tool lcrash gets an additional command -'s390dbf' to display all the debug logs. With this tool it will be possible -to investigate the debug logs on a live system and with a memory dump after -a system crash. - -Investigating raw memory ------------------------- -One last possibility to investigate the debug logs at a live -system and after a system crash is to look at the raw memory -under VM or at the Service Element. -It is possible to find the anker of the debug-logs through -the 'debug_area_first' symbol in the System map. Then one has -to follow the correct pointers of the data-structures defined -in debug.h and find the debug-areas in memory. -Normally modules which use the debug feature will also have -a global variable with the pointer to the debug-logs. Following -this pointer it will also be possible to find the debug logs in -memory. - -For this method it is recommended to use '16 * x + 4' byte (x = 0..n) -for the length of the data field in debug_register() in -order to see the debug entries well formatted. - - -Predefined Views ----------------- - -There are three predefined views: hex_ascii, raw and sprintf. -The hex_ascii view shows the data field in hex and ascii representation -(e.g. '45 43 4b 44 | ECKD'). -The raw view returns a bytestream as the debug areas are stored in memory. - -The sprintf view formats the debug entries in the same way as the sprintf -function would do. The sprintf event/exception functions write to the -debug entry a pointer to the format string (size = sizeof(long)) -and for each vararg a long value. So e.g. for a debug entry with a format -string plus two varargs one would need to allocate a (3 * sizeof(long)) -byte data area in the debug_register() function. - -IMPORTANT: - Using "%s" in sprintf event functions is dangerous. You can only - use "%s" in the sprintf event functions, if the memory for the passed string - is available as long as the debug feature exists. The reason behind this is - that due to performance considerations only a pointer to the string is stored - in the debug feature. If you log a string that is freed afterwards, you will - get an OOPS when inspecting the debug feature, because then the debug feature - will access the already freed memory. - -NOTE: - If using the sprintf view do NOT use other event/exception functions - than the sprintf-event and -exception functions. - -The format of the hex_ascii and sprintf view is as follows: - -- Number of area -- Timestamp (formatted as seconds and microseconds since 00:00:00 Coordinated - Universal Time (UTC), January 1, 1970) -- level of debug entry -- Exception flag (* = Exception) -- Cpu-Number of calling task -- Return Address to caller -- data field - -The format of the raw view is: - -- Header as described in debug.h -- datafield - -A typical line of the hex_ascii view will look like the following (first line -is only for explanation and will not be displayed when 'cating' the view): - -area time level exception cpu caller data (hex + ascii) --------------------------------------------------------------------------- -00 00964419409:440690 1 - 00 88023fe - - -Defining views --------------- - -Views are specified with the 'debug_view' structure. There are defined -callback functions which are used for reading and writing the debugfs files:: - - struct debug_view { - char name[DEBUG_MAX_PROCF_LEN]; - debug_prolog_proc_t* prolog_proc; - debug_header_proc_t* header_proc; - debug_format_proc_t* format_proc; - debug_input_proc_t* input_proc; - void* private_data; - }; - -where:: - - typedef int (debug_header_proc_t) (debug_info_t* id, - struct debug_view* view, - int area, - debug_entry_t* entry, - char* out_buf); - - typedef int (debug_format_proc_t) (debug_info_t* id, - struct debug_view* view, char* out_buf, - const char* in_buf); - typedef int (debug_prolog_proc_t) (debug_info_t* id, - struct debug_view* view, - char* out_buf); - typedef int (debug_input_proc_t) (debug_info_t* id, - struct debug_view* view, - struct file* file, const char* user_buf, - size_t in_buf_size, loff_t* offset); - - -The "private_data" member can be used as pointer to view specific data. -It is not used by the debug feature itself. - -The output when reading a debugfs file is structured like this:: - - "prolog_proc output" - - "header_proc output 1" "format_proc output 1" - "header_proc output 2" "format_proc output 2" - "header_proc output 3" "format_proc output 3" - ... - -When a view is read from the debugfs, the Debug Feature calls the -'prolog_proc' once for writing the prolog. -Then 'header_proc' and 'format_proc' are called for each -existing debug entry. - -The input_proc can be used to implement functionality when it is written to -the view (e.g. like with 'echo "0" > /sys/kernel/debug/s390dbf/dasd/level). - -For header_proc there can be used the default function -debug_dflt_header_fn() which is defined in debug.h. -and which produces the same header output as the predefined views. -E.g:: - - 00 00964419409:440761 2 - 00 88023ec - -In order to see how to use the callback functions check the implementation -of the default views! - -Example:: - - #include <asm/debug.h> - - #define UNKNOWNSTR "data: %08x" - - const char* messages[] = - {"This error...........\n", - "That error...........\n", - "Problem..............\n", - "Something went wrong.\n", - "Everything ok........\n", - NULL - }; - - static int debug_test_format_fn( - debug_info_t * id, struct debug_view *view, - char *out_buf, const char *in_buf - ) - { - int i, rc = 0; - - if(id->buf_size >= 4) { - int msg_nr = *((int*)in_buf); - if(msg_nr < sizeof(messages)/sizeof(char*) - 1) - rc += sprintf(out_buf, "%s", messages[msg_nr]); - else - rc += sprintf(out_buf, UNKNOWNSTR, msg_nr); - } - out: - return rc; - } - - struct debug_view debug_test_view = { - "myview", /* name of view */ - NULL, /* no prolog */ - &debug_dflt_header_fn, /* default header for each entry */ - &debug_test_format_fn, /* our own format function */ - NULL, /* no input function */ - NULL /* no private data */ - }; - -test: -===== - :: debug_info_t *debug_info; diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h index b94783f71322..b55486f70deb 100644 --- a/arch/s390/include/asm/debug.h +++ b/arch/s390/include/asm/debug.h @@ -95,25 +95,106 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level, /* Debug Feature API: */ +/** + * debug_register() - allocates memory for a debug log. + * + * @name: Name of debug log (e.g. used for debugfs entry) + * @pages: Number of pages, which will be allocated per area + * @nr_areas: Number of debug areas + * @buf_size: Size of data area in each debug entry + * + * Return: + * - Handler for generated debug area + * - %NULL if register failed + * + * Must not be called within an interrupt handler. + */ debug_info_t *debug_register(const char *name, int pages, int nr_areas, int buf_size); +/** + * debug_register_mode() - allocates memory for a debug log. + * + * @name: Name of debug log (e.g. used for debugfs entry) + * @pages: Number of pages, which will be allocated per area + * @nr_areas: Number of debug areas + * @buf_size: Size of data area in each debug entry + * @mode: File mode for debugfs files. E.g. S_IRWXUGO + * @uid: User ID for debugfs files. Currently only 0 is supported. + * @gid: Group ID for debugfs files. Currently only 0 is supported. + * + * Return: + * - Handler for generated debug area + * - %NULL if register failed + * + * Must not be called within an interrupt handler + */ debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas, int buf_size, umode_t mode, uid_t uid, gid_t gid); +/** + * debug_unregister() - frees memory for a debug log and removes all + * registered debug + * views. + * + * @id: handle for debug log + * + * Return: + * none + * + * Must not be called within an interrupt handler + */ void debug_unregister(debug_info_t *id); +/** + * debug_set_level() - Sets new actual debug level if new_level is valid. + * + * @id: handle for debug log + * @new_level: new debug level + * + * Return: + * none + */ void debug_set_level(debug_info_t *id, int new_level); void debug_set_critical(void); + +/** + * debug_stop_all() - stops the debug feature if stopping is allowed. + * + * Return: + * - none + */ void debug_stop_all(void); +/** + * debug_level_enabled() - Returns true if debug events for the specified + * level would be logged. Otherwise returns false. + * + * @id: handle for debug log + * @level: debug level + * + * Return: + * - %true if level is less or equal to the current debug level. + */ static inline bool debug_level_enabled(debug_info_t *id, int level) { return level <= id->level; } +/** + * debug_event() - writes debug entry to active debug area + * (if level <= actual debug level) + * + * @id: handle for debug log + * @level: debug level + * @data: pointer to data for debug entry + * @length: length of data in bytes + * + * Return: + * - Address of written debug entry + */ static inline debug_entry_t *debug_event(debug_info_t *id, int level, void *data, int length) { @@ -122,6 +203,18 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level, return debug_event_common(id, level, data, length); } +/** + * debug_int_event() - writes debug entry to active debug area + * (if level <= actual debug level) + * + * @id: handle for debug log + * @level: debug level + * @tag: integer value for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level, unsigned int tag) { @@ -132,6 +225,18 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level, return debug_event_common(id, level, &t, sizeof(unsigned int)); } +/** + * debug_long_event() - writes debug entry to active debug area + * (if level <= actual debug level) + * + * @id: handle for debug log + * @level: debug level + * @tag: integer value for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level, unsigned long tag) { @@ -142,6 +247,18 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level, return debug_event_common(id, level, &t, sizeof(unsigned long)); } +/** + * debug_text_event() - writes debug entry in ascii format to active + * debug area (if level <= actual debug level) + * + * @id: handle for debug log + * @level: debug level + * @txt: string for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_text_event(debug_info_t *id, int level, const char *txt) { @@ -158,6 +275,22 @@ extern debug_entry_t * __debug_sprintf_event(debug_info_t *id, int level, char *string, ...) __attribute__ ((format(printf, 3, 4))); +/** + * debug_sprintf_event() - writes debug entry with format string + * and varargs (longs) to active debug area + * (if level $<=$ actual debug level). + * + * @_id: handle for debug log + * @_level: debug level + * @_fmt: format string for debug entry + * @...: varargs used as in sprintf() + * + * Return: + * - Address of written debug entry + * - %NULL if error + * + * floats and long long datatypes cannot be used as varargs. + */ #define debug_sprintf_event(_id, _level, _fmt, ...) \ ({ \ debug_entry_t *__ret; \ @@ -172,6 +305,20 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...) __ret; \ }) +/** + * debug_exception() - writes debug entry to active debug area + * (if level <= actual debug level) and switches + * to next debug area + * + * @id: handle for debug log + * @level: debug level + * @data: pointer to data for debug entry + * @length: length of data in bytes + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_exception(debug_info_t *id, int level, void *data, int length) { @@ -180,6 +327,19 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level, return debug_exception_common(id, level, data, length); } +/** + * debug_int_exception() - writes debug entry to active debug area + * (if level <= actual debug level) + * and switches to next debug area + * + * @id: handle for debug log + * @level: debug level + * @tag: integer value for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level, unsigned int tag) { @@ -190,6 +350,19 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level, return debug_exception_common(id, level, &t, sizeof(unsigned int)); } +/** + * debug_long_exception() - writes debug entry to active debug area + * (if level <= actual debug level) + * and switches to next debug area + * + * @id: handle for debug log + * @level: debug level + * @tag: integer value for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level, unsigned long tag) { @@ -200,6 +373,20 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level, return debug_exception_common(id, level, &t, sizeof(unsigned long)); } +/** + * debug_text_exception() - writes debug entry in ascii format to active + * debug area (if level <= actual debug level) + * and switches to next debug + * area + * + * @id: handle for debug log + * @level: debug level + * @txt: string for debug entry + * + * Return: + * - Address of written debug entry + * - %NULL if error + */ static inline debug_entry_t *debug_text_exception(debug_info_t *id, int level, const char *txt) { @@ -216,6 +403,24 @@ extern debug_entry_t * __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...) __attribute__ ((format(printf, 3, 4))); + +/** + * debug_sprintf_exception() - writes debug entry with format string and + * varargs (longs) to active debug area + * (if level $<=$ actual debug level) + * and switches to next debug area. + * + * @_id: handle for debug log + * @_level: debug level + * @_fmt: format string for debug entry + * @...: varargs used as in sprintf() + * + * Return: + * - Address of written debug entry + * - %NULL if error + * + * floats and long long datatypes cannot be used as varargs. + */ #define debug_sprintf_exception(_id, _level, _fmt, ...) \ ({ \ debug_entry_t *__ret; \ @@ -230,7 +435,33 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...) __ret; \ }) +/** + * debug_register_view() - registers new debug view and creates debugfs + * dir entry + * + * @id: handle for debug log + * @view: pointer to debug view struct + * + * Return: + * - 0 : ok + * - < 0: Error + */ int debug_register_view(debug_info_t *id, struct debug_view *view); + +/** + * debug_unregister_view() + * + * @id: handle for debug log + * @view: pointer to debug view struct + * + * Return: + * - 0 : ok + * - < 0: Error + * + * + * unregisters debug view and removes debugfs dir entry + */ + int debug_unregister_view(debug_info_t *id, struct debug_view *view); /* -- 2.20.1 ^ permalink raw reply related [flat|nested] 8+ messages in thread
[parent not found: <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org>]
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst [not found] ` <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org> @ 2019-04-23 16:12 ` Farhan Ali 2019-04-23 19:46 ` Mauro Carvalho Chehab 2019-04-24 11:41 ` Cornelia Huck 1 sibling, 1 reply; 8+ messages in thread From: Farhan Ali @ 2019-04-23 16:12 UTC (permalink / raw) To: Mauro Carvalho Chehab, Linux Doc Mailing List Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, Tony Krowiak, Pierre Morel, Halil Pasic, Cornelia Huck, Eric Farman, linux-s390, kvm On 04/22/2019 09:27 AM, Mauro Carvalho Chehab wrote: > Convert all text files with s390 documentation to ReST format. > > Tried to preserve as much as possible the original document > format. Still, some of the files required some work in order > for it to be visible on both plain text and after converted > to html. > > The conversion is actually: > - add blank lines and identation in order to identify paragraphs; > - fix tables markups; > - add some lists markups; > - mark literal blocks; > - adjust title markups. > > At its new index.rst, let's add a :orphan: while this is not linked to > the main index.rst file, in order to avoid build warnings. > > Signed-off-by: Mauro Carvalho Chehab<mchehab+samsung@kernel.org> > --- Hi Mauro, How would the s390 rst files be accessed from a top level index.rst file? Is there a view of the changes? I looked at a link you posted [1] as a reply in another thread, but I couldn't find the s390 docs there. [1] https://www.infradead.org/~mchehab/rst_conversion/ Thanks Farhan ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst 2019-04-23 16:12 ` [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst Farhan Ali @ 2019-04-23 19:46 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 8+ messages in thread From: Mauro Carvalho Chehab @ 2019-04-23 19:46 UTC (permalink / raw) To: Farhan Ali Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, Tony Krowiak, Pierre Morel, Halil Pasic, Cornelia Huck, Eric Farman, linux-s390, kvm Em Tue, 23 Apr 2019 12:12:41 -0400 Farhan Ali <alifm@linux.ibm.com> escreveu: > On 04/22/2019 09:27 AM, Mauro Carvalho Chehab wrote: > > Convert all text files with s390 documentation to ReST format. > > > > Tried to preserve as much as possible the original document > > format. Still, some of the files required some work in order > > for it to be visible on both plain text and after converted > > to html. > > > > The conversion is actually: > > - add blank lines and identation in order to identify paragraphs; > > - fix tables markups; > > - add some lists markups; > > - mark literal blocks; > > - adjust title markups. > > > > At its new index.rst, let's add a :orphan: while this is not linked to > > the main index.rst file, in order to avoid build warnings. > > > > Signed-off-by: Mauro Carvalho Chehab<mchehab+samsung@kernel.org> > > --- > > Hi Mauro, > > How would the s390 rst files be accessed from a top level index.rst > file? Is there a view of the changes? I looked at a link you posted [1] > as a reply in another thread, but I couldn't find the s390 docs there. > > [1] https://www.infradead.org/~mchehab/rst_conversion/ With just the patch I added on this series, you'll find the s390 index.html, and one file for each .rst at Documentation/output/s390/. In order to have it linked to the main index, you need to add s390/index to Documentation/index.rst, but, if you just want to see the results, you can just call: $ firefox file://`pwd`/Documentation/output/s390/index.html I have a patch already that adds s390 to the main index, together with other arch conversions: https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames&id=d28c466a495488e5e57c7893123011342eea40b2 However, as subsystem maintainers may take a while to apply some of those patches, and there's a patchset converting x86 arch too, I opted to do such additions on a separate patch, in order to reduce merge conflicts. Thanks, Mauro ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst [not found] ` <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org> 2019-04-23 16:12 ` [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst Farhan Ali @ 2019-04-24 11:41 ` Cornelia Huck 2019-04-24 12:30 ` Heiko Carstens 2019-04-24 12:44 ` Mauro Carvalho Chehab 1 sibling, 2 replies; 8+ messages in thread From: Cornelia Huck @ 2019-04-24 11:41 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, Tony Krowiak, Pierre Morel, Halil Pasic, Farhan Ali, Eric Farman, linux-s390, kvm On Mon, 22 Apr 2019 10:27:20 -0300 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > Convert all text files with s390 documentation to ReST format. > > Tried to preserve as much as possible the original document > format. Still, some of the files required some work in order > for it to be visible on both plain text and after converted > to html. > > The conversion is actually: > - add blank lines and identation in order to identify paragraphs; > - fix tables markups; > - add some lists markups; > - mark literal blocks; > - adjust title markups. > > At its new index.rst, let's add a :orphan: while this is not linked to > the main index.rst file, in order to avoid build warnings. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > --- > .../admin-guide/kernel-parameters.txt | 4 +- > Documentation/driver-api/s390-drivers.rst | 4 +- > Documentation/s390/{3270.txt => 3270.rst} | 85 +- > Documentation/s390/{cds.txt => cds.rst} | 354 ++- > .../s390/{CommonIO => common_io.rst} | 49 +- > Documentation/s390/{DASD => dasd.rst} | 33 +- > .../{Debugging390.txt => debugging390.rst} | 2389 ++++++++++------- > .../{driver-model.txt => driver-model.rst} | 179 +- > Documentation/s390/index.rst | 30 + > .../s390/{monreader.txt => monreader.rst} | 85 +- > Documentation/s390/{qeth.txt => qeth.rst} | 36 +- > Documentation/s390/s390dbf.rst | 803 ++++++ > Documentation/s390/s390dbf.txt | 667 ----- > Documentation/s390/text_files.rst | 11 + > .../s390/{vfio-ap.txt => vfio-ap.rst} | 487 ++-- > .../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +- > .../s390/{zfcpdump.txt => zfcpdump.rst} | 2 + > MAINTAINERS | 4 +- > arch/s390/Kconfig | 4 +- > arch/s390/include/asm/debug.h | 4 +- > drivers/s390/char/zcore.c | 2 +- > 21 files changed, 3089 insertions(+), 2233 deletions(-) > rename Documentation/s390/{3270.txt => 3270.rst} (90%) > rename Documentation/s390/{cds.txt => cds.rst} (64%) > rename Documentation/s390/{CommonIO => common_io.rst} (87%) > rename Documentation/s390/{DASD => dasd.rst} (92%) > rename Documentation/s390/{Debugging390.txt => debugging390.rst} (53%) > rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%) > create mode 100644 Documentation/s390/index.rst > rename Documentation/s390/{monreader.txt => monreader.rst} (81%) > rename Documentation/s390/{qeth.txt => qeth.rst} (62%) > create mode 100644 Documentation/s390/s390dbf.rst > delete mode 100644 Documentation/s390/s390dbf.txt > create mode 100644 Documentation/s390/text_files.rst > rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%) > rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%) > rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%) > (...) > diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.rst > similarity index 90% > rename from Documentation/s390/3270.txt > rename to Documentation/s390/3270.rst > index 7c715de99774..e09e77954238 100644 > --- a/Documentation/s390/3270.txt > +++ b/Documentation/s390/3270.rst (...) > @@ -17,12 +21,12 @@ twenty and thirty years ago. > You may have 3270s in-house and not know it. If you're using the > VM-ESA operating system, define a 3270 to your virtual machine by using > the command "DEF GRAF <hex-address>" This paper presumes you will be > -defining four 3270s with the CP/CMS commands > +defining four 3270s with the CP/CMS commands: > > - DEF GRAF 620 > - DEF GRAF 621 > - DEF GRAF 622 > - DEF GRAF 623 > + - DEF GRAF 620 > + - DEF GRAF 621 > + - DEF GRAF 622 > + - DEF GRAF 623 IIUC, this makes this into a bulleted list... but the user is supposed to enter these commands (similar to the shell commands further down in this file). > > Your network connection from VM-ESA allows you to use x3270, tn3270, or > another 3270 emulator, started from an xterm window on your PC or (...) > @@ -84,20 +92,22 @@ Here are the installation steps in detail: > make modules_install > > 2. (Perform this step only if you have configured tub3270 as a > - module.) Add a line to a file /etc/modprobe.d/*.conf to automatically > + module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically > load the driver when it's needed. With this line added, you will see > login prompts appear on your 3270s as soon as boot is complete (or > with emulated 3270s, as soon as you dial into your vm guest using the > command "DIAL <vmguestname>"). Since the line-mode major number is > - 227, the line to add should be: > + 227, the line to add should be:: > + > alias char-major-227 tub3270 > > 3. Define graphic devices to your vm guest machine, if you > haven't already. Define them before you reboot (reipl): > - DEFINE GRAF 620 > - DEFINE GRAF 621 > - DEFINE GRAF 622 > - DEFINE GRAF 623 > + > + - DEFINE GRAF 620 > + - DEFINE GRAF 621 > + - DEFINE GRAF 622 > + - DEFINE GRAF 623 Same here. > > 4. Reboot. The reboot process scans hardware devices, including > 3270s, and this enables the tub3270 driver once loaded to respond (...) > diff --git a/Documentation/s390/CommonIO b/Documentation/s390/common_io.rst > similarity index 87% > rename from Documentation/s390/CommonIO > rename to Documentation/s390/common_io.rst > index 6e0f63f343b4..846485681ce7 100644 > --- a/Documentation/s390/CommonIO > +++ b/Documentation/s390/common_io.rst > @@ -1,5 +1,9 @@ > -S/390 common I/O-Layer - command line parameters, procfs and debugfs entries > -============================================================================ > +====================== > +S/390 common I/O-Layer > +====================== > + > +command line parameters, procfs and debugfs entries > +=================================================== I don't see why this should be split into two lines? If anything needs to be changed, I'd drop the hyphen. > > Command line parameters > ----------------------- > @@ -13,7 +17,7 @@ Command line parameters > device := {all | [!]ipldev | [!]condev | [!]<devno> | [!]<devno>-<devno>} > > The given devices will be ignored by the common I/O-layer; no detection > - and device sensing will be done on any of those devices. The subchannel to > + and device sensing will be done on any of those devices. The subchannel to > which the device in question is attached will be treated as if no device was > attached. > > @@ -28,14 +32,20 @@ Command line parameters > keywords can be used to refer to the CCW based boot device and CCW console > device respectively (these are probably useful only when combined with the '!' > operator). The '!' operator will cause the I/O-layer to _not_ ignore a device. > - The command line is parsed from left to right. > + The command line > + is parsed from left to right. Why this change? > + > + For example:: > > - For example, > cio_ignore=0.0.0023-0.0.0042,0.0.4711 > + > will ignore all devices ranging from 0.0.0023 to 0.0.0042 and the device > 0.0.4711, if detected. > - As another example, > + > + As another example:: > + > cio_ignore=all,!0.0.4711,!0.0.fd00-0.0.fd02 > + > will ignore all devices but 0.0.4711, 0.0.fd00, 0.0.fd01, 0.0.fd02. > > By default, no devices are ignored. (...) > diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/debugging390.rst > similarity index 53% > rename from Documentation/s390/Debugging390.txt > rename to Documentation/s390/debugging390.rst > index c35804c238ad..d49305fd5e1a 100644 > --- a/Documentation/s390/Debugging390.txt > +++ b/Documentation/s390/debugging390.rst I'll skip this one... (Question for the s390 arch maintainers: I remember that there was some interesting stuff in there, but I'm not sure how much of it is still accurate/useful... is it worth spending time on trying to update this?) (...) > diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst > new file mode 100644 > index 000000000000..ec2a1faa414b > --- /dev/null > +++ b/Documentation/s390/s390dbf.rst (...) > diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt > deleted file mode 100644 > index 61329fd62e89..000000000000 > --- a/Documentation/s390/s390dbf.txt > +++ /dev/null I wonder why this does not show up as a rename? (...) > diff --git a/Documentation/s390/text_files.rst b/Documentation/s390/text_files.rst > new file mode 100644 > index 000000000000..c94d05d4fa17 > --- /dev/null > +++ b/Documentation/s390/text_files.rst > @@ -0,0 +1,11 @@ > +ibm 3270 changelog > +------------------ > + > +.. include:: 3270.ChangeLog > + :literal: > + > +ibm 3270 config3270.sh > +---------------------- > + > +.. literalinclude:: config3270.sh > + :language: shell Another question for the s390 arch maintainers: How valuable is this still? (...) > diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.rst > similarity index 89% > rename from Documentation/s390/vfio-ccw.txt > rename to Documentation/s390/vfio-ccw.rst > index 2be11ad864ff..1f6d0b56d53e 100644 > --- a/Documentation/s390/vfio-ccw.txt > +++ b/Documentation/s390/vfio-ccw.rst (...) > @@ -295,6 +321,6 @@ Reference > 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) > 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) > 3. https://en.wikipedia.org/wiki/Channel_I/O > -4. Documentation/s390/cds.txt > +4. Documentation/s390/cds.rst > 5. Documentation/vfio.txt > 6. Documentation/vfio-mediated-device.txt Are these two renamed in a later patch? (...) ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst 2019-04-24 11:41 ` Cornelia Huck @ 2019-04-24 12:30 ` Heiko Carstens 2019-04-24 12:44 ` Mauro Carvalho Chehab 1 sibling, 0 replies; 8+ messages in thread From: Heiko Carstens @ 2019-04-24 12:30 UTC (permalink / raw) To: Cornelia Huck Cc: Mauro Carvalho Chehab, Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Tony Krowiak, Pierre Morel, Halil Pasic, Farhan Ali, Eric Farman, linux-s390, kvm On Wed, Apr 24, 2019 at 01:41:09PM +0200, Cornelia Huck wrote: > > diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/debugging390.rst > > similarity index 53% > > rename from Documentation/s390/Debugging390.txt > > rename to Documentation/s390/debugging390.rst > > index c35804c238ad..d49305fd5e1a 100644 > > --- a/Documentation/s390/Debugging390.txt > > +++ b/Documentation/s390/debugging390.rst > > I'll skip this one... > > (Question for the s390 arch maintainers: I remember that there was some > interesting stuff in there, but I'm not sure how much of it is still > accurate/useful... is it worth spending time on trying to update this?) > > > diff --git a/Documentation/s390/text_files.rst b/Documentation/s390/text_files.rst > > new file mode 100644 > > index 000000000000..c94d05d4fa17 > > --- /dev/null > > +++ b/Documentation/s390/text_files.rst > > @@ -0,0 +1,11 @@ > > +ibm 3270 changelog > > +------------------ > > + > > +.. include:: 3270.ChangeLog > > + :literal: > > + > > +ibm 3270 config3270.sh > > +---------------------- > > + > > +.. literalinclude:: config3270.sh > > + :language: shell > > > Another question for the s390 arch maintainers: How valuable is this still? ...to be honest I consider 80% within Documentation/s390 to be completely outdated, partially wrong, or irrelevant in the meantime; the vfio stuff seems to be pretty much up-to-date, and I like the parts that move comments to code. Cleaning this up can be done at a later time. I don't want to make Mauro spend more time than necessary on this. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst 2019-04-24 11:41 ` Cornelia Huck 2019-04-24 12:30 ` Heiko Carstens @ 2019-04-24 12:44 ` Mauro Carvalho Chehab 2019-04-24 12:52 ` Cornelia Huck 1 sibling, 1 reply; 8+ messages in thread From: Mauro Carvalho Chehab @ 2019-04-24 12:44 UTC (permalink / raw) To: Cornelia Huck Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, Tony Krowiak, Pierre Morel, Halil Pasic, Farhan Ali, Eric Farman, linux-s390, kvm Em Wed, 24 Apr 2019 13:41:09 +0200 Cornelia Huck <cohuck@redhat.com> escreveu: > On Mon, 22 Apr 2019 10:27:20 -0300 > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > > > Convert all text files with s390 documentation to ReST format. > > > > Tried to preserve as much as possible the original document > > format. Still, some of the files required some work in order > > for it to be visible on both plain text and after converted > > to html. > > > > The conversion is actually: > > - add blank lines and identation in order to identify paragraphs; > > - fix tables markups; > > - add some lists markups; > > - mark literal blocks; > > - adjust title markups. > > > > At its new index.rst, let's add a :orphan: while this is not linked to > > the main index.rst file, in order to avoid build warnings. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > > --- > > .../admin-guide/kernel-parameters.txt | 4 +- > > Documentation/driver-api/s390-drivers.rst | 4 +- > > Documentation/s390/{3270.txt => 3270.rst} | 85 +- > > Documentation/s390/{cds.txt => cds.rst} | 354 ++- > > .../s390/{CommonIO => common_io.rst} | 49 +- > > Documentation/s390/{DASD => dasd.rst} | 33 +- > > .../{Debugging390.txt => debugging390.rst} | 2389 ++++++++++------- > > .../{driver-model.txt => driver-model.rst} | 179 +- > > Documentation/s390/index.rst | 30 + > > .../s390/{monreader.txt => monreader.rst} | 85 +- > > Documentation/s390/{qeth.txt => qeth.rst} | 36 +- > > Documentation/s390/s390dbf.rst | 803 ++++++ > > Documentation/s390/s390dbf.txt | 667 ----- > > Documentation/s390/text_files.rst | 11 + > > .../s390/{vfio-ap.txt => vfio-ap.rst} | 487 ++-- > > .../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +- > > .../s390/{zfcpdump.txt => zfcpdump.rst} | 2 + > > MAINTAINERS | 4 +- > > arch/s390/Kconfig | 4 +- > > arch/s390/include/asm/debug.h | 4 +- > > drivers/s390/char/zcore.c | 2 +- > > 21 files changed, 3089 insertions(+), 2233 deletions(-) > > rename Documentation/s390/{3270.txt => 3270.rst} (90%) > > rename Documentation/s390/{cds.txt => cds.rst} (64%) > > rename Documentation/s390/{CommonIO => common_io.rst} (87%) > > rename Documentation/s390/{DASD => dasd.rst} (92%) > > rename Documentation/s390/{Debugging390.txt => debugging390.rst} (53%) > > rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%) > > create mode 100644 Documentation/s390/index.rst > > rename Documentation/s390/{monreader.txt => monreader.rst} (81%) > > rename Documentation/s390/{qeth.txt => qeth.rst} (62%) > > create mode 100644 Documentation/s390/s390dbf.rst > > delete mode 100644 Documentation/s390/s390dbf.txt > > create mode 100644 Documentation/s390/text_files.rst > > rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%) > > rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%) > > rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%) > > > > (...) > > > diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.rst > > similarity index 90% > > rename from Documentation/s390/3270.txt > > rename to Documentation/s390/3270.rst > > index 7c715de99774..e09e77954238 100644 > > --- a/Documentation/s390/3270.txt > > +++ b/Documentation/s390/3270.rst > > (...) > > > @@ -17,12 +21,12 @@ twenty and thirty years ago. > > You may have 3270s in-house and not know it. If you're using the > > VM-ESA operating system, define a 3270 to your virtual machine by using > > the command "DEF GRAF <hex-address>" This paper presumes you will be > > -defining four 3270s with the CP/CMS commands > > +defining four 3270s with the CP/CMS commands: > > > > - DEF GRAF 620 > > - DEF GRAF 621 > > - DEF GRAF 622 > > - DEF GRAF 623 > > + - DEF GRAF 620 > > + - DEF GRAF 621 > > + - DEF GRAF 622 > > + - DEF GRAF 623 > > IIUC, this makes this into a bulleted list... but the user is supposed > to enter these commands (similar to the shell commands further down in > this file). Ah, OK! I'll change it to use a literal block (::). > > > > > Your network connection from VM-ESA allows you to use x3270, tn3270, or > > another 3270 emulator, started from an xterm window on your PC or > > (...) > > > @@ -84,20 +92,22 @@ Here are the installation steps in detail: > > make modules_install > > > > 2. (Perform this step only if you have configured tub3270 as a > > - module.) Add a line to a file /etc/modprobe.d/*.conf to automatically > > + module.) Add a line to a file `/etc/modprobe.d/*.conf` to automatically > > load the driver when it's needed. With this line added, you will see > > login prompts appear on your 3270s as soon as boot is complete (or > > with emulated 3270s, as soon as you dial into your vm guest using the > > command "DIAL <vmguestname>"). Since the line-mode major number is > > - 227, the line to add should be: > > + 227, the line to add should be:: > > + > > alias char-major-227 tub3270 > > > > 3. Define graphic devices to your vm guest machine, if you > > haven't already. Define them before you reboot (reipl): > > - DEFINE GRAF 620 > > - DEFINE GRAF 621 > > - DEFINE GRAF 622 > > - DEFINE GRAF 623 > > + > > + - DEFINE GRAF 620 > > + - DEFINE GRAF 621 > > + - DEFINE GRAF 622 > > + - DEFINE GRAF 623 > > Same here. Ok. > > > > > 4. Reboot. The reboot process scans hardware devices, including > > 3270s, and this enables the tub3270 driver once loaded to respond > > (...) > > > > diff --git a/Documentation/s390/CommonIO b/Documentation/s390/common_io.rst > > similarity index 87% > > rename from Documentation/s390/CommonIO > > rename to Documentation/s390/common_io.rst > > index 6e0f63f343b4..846485681ce7 100644 > > --- a/Documentation/s390/CommonIO > > +++ b/Documentation/s390/common_io.rst > > @@ -1,5 +1,9 @@ > > -S/390 common I/O-Layer - command line parameters, procfs and debugfs entries > > -============================================================================ > > +====================== > > +S/390 common I/O-Layer > > +====================== > > + > > +command line parameters, procfs and debugfs entries > > +=================================================== > > I don't see why this should be split into two lines? If anything needs > to be changed, I'd drop the hyphen. No real need for html output. I suspect that a big title like the above would cause troubles for pdf output. That's basically why I opted to break it. Yet, if you prefer, I'll keep it as-is. > > > > > Command line parameters > > ----------------------- > > @@ -13,7 +17,7 @@ Command line parameters > > device := {all | [!]ipldev | [!]condev | [!]<devno> | [!]<devno>-<devno>} > > > > The given devices will be ignored by the common I/O-layer; no detection > > - and device sensing will be done on any of those devices. The subchannel to > > + and device sensing will be done on any of those devices. The subchannel to > > which the device in question is attached will be treated as if no device was > > attached. > > > > @@ -28,14 +32,20 @@ Command line parameters > > keywords can be used to refer to the CCW based boot device and CCW console > > device respectively (these are probably useful only when combined with the '!' > > operator). The '!' operator will cause the I/O-layer to _not_ ignore a device. > > - The command line is parsed from left to right. > > + The command line > > + is parsed from left to right. > > Why this change? This was unintentional. I probably hit <enter> by mistake on that line. I'll revert. > > > + > > + For example:: > > > > - For example, > > cio_ignore=0.0.0023-0.0.0042,0.0.4711 > > + > > will ignore all devices ranging from 0.0.0023 to 0.0.0042 and the device > > 0.0.4711, if detected. > > - As another example, > > + > > + As another example:: > > + > > cio_ignore=all,!0.0.4711,!0.0.fd00-0.0.fd02 > > + > > will ignore all devices but 0.0.4711, 0.0.fd00, 0.0.fd01, 0.0.fd02. > > > > By default, no devices are ignored. > > (...) > > > diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/debugging390.rst > > similarity index 53% > > rename from Documentation/s390/Debugging390.txt > > rename to Documentation/s390/debugging390.rst > > index c35804c238ad..d49305fd5e1a 100644 > > --- a/Documentation/s390/Debugging390.txt > > +++ b/Documentation/s390/debugging390.rst > > I'll skip this one... > > (Question for the s390 arch maintainers: I remember that there was some > interesting stuff in there, but I'm not sure how much of it is still > accurate/useful... is it worth spending time on trying to update this?) > > (...) > > > > diff --git a/Documentation/s390/s390dbf.rst b/Documentation/s390/s390dbf.rst > > new file mode 100644 > > index 000000000000..ec2a1faa414b > > --- /dev/null > > +++ b/Documentation/s390/s390dbf.rst > > (...) > > > diff --git a/Documentation/s390/s390dbf.txt b/Documentation/s390/s390dbf.txt > > deleted file mode 100644 > > index 61329fd62e89..000000000000 > > --- a/Documentation/s390/s390dbf.txt > > +++ /dev/null > > I wonder why this does not show up as a rename? Probably because the number of changes were bigger than 50%. The algo there seems to be dumb. I suspect that adding whitespace/tabs on lines makes it to consider the entire line as different. git log -M10 would change the threshold to 10% similarity and will likely show it as a rename. I'll use -M on the next version for this patch. > > (...) > > > diff --git a/Documentation/s390/text_files.rst b/Documentation/s390/text_files.rst > > new file mode 100644 > > index 000000000000..c94d05d4fa17 > > --- /dev/null > > +++ b/Documentation/s390/text_files.rst > > @@ -0,0 +1,11 @@ > > +ibm 3270 changelog > > +------------------ > > + > > +.. include:: 3270.ChangeLog > > + :literal: > > + > > +ibm 3270 config3270.sh > > +---------------------- > > + > > +.. literalinclude:: config3270.sh > > + :language: shell > > > Another question for the s390 arch maintainers: How valuable is this still? > > (...) > > > diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.rst > > similarity index 89% > > rename from Documentation/s390/vfio-ccw.txt > > rename to Documentation/s390/vfio-ccw.rst > > index 2be11ad864ff..1f6d0b56d53e 100644 > > --- a/Documentation/s390/vfio-ccw.txt > > +++ b/Documentation/s390/vfio-ccw.rst > > (...) > > > @@ -295,6 +321,6 @@ Reference > > 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) > > 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) > > 3. https://en.wikipedia.org/wiki/Channel_I/O > > -4. Documentation/s390/cds.txt > > +4. Documentation/s390/cds.rst > > 5. Documentation/vfio.txt > > 6. Documentation/vfio-mediated-device.txt > > Are these two renamed in a later patch? Yes. Patch 56 renames almost all Documentation/*.txt to .rst. Those files are already parsed properly by Sphinx, so no changes there are needed. I'm working on followup patches (not submitted yet), with moves all ReST files under Documentation to some place. In the specific case of those files, on the series I'm working, I moved them to be part of the driver-api: https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames&id=3387ab063cf43f91d5c0f79d741244e7dbcdec05 The results, when parsed, are at: https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio.html https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio-mediated-device.html Thanks, Mauro ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst 2019-04-24 12:44 ` Mauro Carvalho Chehab @ 2019-04-24 12:52 ` Cornelia Huck 0 siblings, 0 replies; 8+ messages in thread From: Cornelia Huck @ 2019-04-24 12:52 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Martin Schwidefsky, Heiko Carstens, Tony Krowiak, Pierre Morel, Halil Pasic, Farhan Ali, Eric Farman, linux-s390, kvm On Wed, 24 Apr 2019 09:44:50 -0300 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > Em Wed, 24 Apr 2019 13:41:09 +0200 > Cornelia Huck <cohuck@redhat.com> escreveu: > > > On Mon, 22 Apr 2019 10:27:20 -0300 > > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote: > > > > > Convert all text files with s390 documentation to ReST format. > > > > > > Tried to preserve as much as possible the original document > > > format. Still, some of the files required some work in order > > > for it to be visible on both plain text and after converted > > > to html. > > > > > > The conversion is actually: > > > - add blank lines and identation in order to identify paragraphs; > > > - fix tables markups; > > > - add some lists markups; > > > - mark literal blocks; > > > - adjust title markups. > > > > > > At its new index.rst, let's add a :orphan: while this is not linked to > > > the main index.rst file, in order to avoid build warnings. > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > > > --- > > > .../admin-guide/kernel-parameters.txt | 4 +- > > > Documentation/driver-api/s390-drivers.rst | 4 +- > > > Documentation/s390/{3270.txt => 3270.rst} | 85 +- > > > Documentation/s390/{cds.txt => cds.rst} | 354 ++- > > > .../s390/{CommonIO => common_io.rst} | 49 +- > > > Documentation/s390/{DASD => dasd.rst} | 33 +- > > > .../{Debugging390.txt => debugging390.rst} | 2389 ++++++++++------- > > > .../{driver-model.txt => driver-model.rst} | 179 +- > > > Documentation/s390/index.rst | 30 + > > > .../s390/{monreader.txt => monreader.rst} | 85 +- > > > Documentation/s390/{qeth.txt => qeth.rst} | 36 +- > > > Documentation/s390/s390dbf.rst | 803 ++++++ > > > Documentation/s390/s390dbf.txt | 667 ----- > > > Documentation/s390/text_files.rst | 11 + > > > .../s390/{vfio-ap.txt => vfio-ap.rst} | 487 ++-- > > > .../s390/{vfio-ccw.txt => vfio-ccw.rst} | 90 +- > > > .../s390/{zfcpdump.txt => zfcpdump.rst} | 2 + > > > MAINTAINERS | 4 +- > > > arch/s390/Kconfig | 4 +- > > > arch/s390/include/asm/debug.h | 4 +- > > > drivers/s390/char/zcore.c | 2 +- > > > 21 files changed, 3089 insertions(+), 2233 deletions(-) > > > rename Documentation/s390/{3270.txt => 3270.rst} (90%) > > > rename Documentation/s390/{cds.txt => cds.rst} (64%) > > > rename Documentation/s390/{CommonIO => common_io.rst} (87%) > > > rename Documentation/s390/{DASD => dasd.rst} (92%) > > > rename Documentation/s390/{Debugging390.txt => debugging390.rst} (53%) > > > rename Documentation/s390/{driver-model.txt => driver-model.rst} (73%) > > > create mode 100644 Documentation/s390/index.rst > > > rename Documentation/s390/{monreader.txt => monreader.rst} (81%) > > > rename Documentation/s390/{qeth.txt => qeth.rst} (62%) > > > create mode 100644 Documentation/s390/s390dbf.rst > > > delete mode 100644 Documentation/s390/s390dbf.txt > > > create mode 100644 Documentation/s390/text_files.rst > > > rename Documentation/s390/{vfio-ap.txt => vfio-ap.rst} (72%) > > > rename Documentation/s390/{vfio-ccw.txt => vfio-ccw.rst} (89%) > > > rename Documentation/s390/{zfcpdump.txt => zfcpdump.rst} (97%) > > > > > > > (...) > > > > > diff --git a/Documentation/s390/3270.txt b/Documentation/s390/3270.rst > > > similarity index 90% > > > rename from Documentation/s390/3270.txt > > > rename to Documentation/s390/3270.rst > > > index 7c715de99774..e09e77954238 100644 > > > --- a/Documentation/s390/3270.txt > > > +++ b/Documentation/s390/3270.rst > > > > (...) > > > > > @@ -17,12 +21,12 @@ twenty and thirty years ago. > > > You may have 3270s in-house and not know it. If you're using the > > > VM-ESA operating system, define a 3270 to your virtual machine by using > > > the command "DEF GRAF <hex-address>" This paper presumes you will be > > > -defining four 3270s with the CP/CMS commands > > > +defining four 3270s with the CP/CMS commands: > > > > > > - DEF GRAF 620 > > > - DEF GRAF 621 > > > - DEF GRAF 622 > > > - DEF GRAF 623 > > > + - DEF GRAF 620 > > > + - DEF GRAF 621 > > > + - DEF GRAF 622 > > > + - DEF GRAF 623 > > > > IIUC, this makes this into a bulleted list... but the user is supposed > > to enter these commands (similar to the shell commands further down in > > this file). > > Ah, OK! I'll change it to use a literal block (::). Sounds good. > > > diff --git a/Documentation/s390/CommonIO b/Documentation/s390/common_io.rst > > > similarity index 87% > > > rename from Documentation/s390/CommonIO > > > rename to Documentation/s390/common_io.rst > > > index 6e0f63f343b4..846485681ce7 100644 > > > --- a/Documentation/s390/CommonIO > > > +++ b/Documentation/s390/common_io.rst > > > @@ -1,5 +1,9 @@ > > > -S/390 common I/O-Layer - command line parameters, procfs and debugfs entries > > > -============================================================================ > > > +====================== > > > +S/390 common I/O-Layer > > > +====================== > > > + > > > +command line parameters, procfs and debugfs entries > > > +=================================================== > > > > I don't see why this should be split into two lines? If anything needs > > to be changed, I'd drop the hyphen. > > No real need for html output. I suspect that a big title like the > above would cause troubles for pdf output. That's basically why I opted > to break it. > > Yet, if you prefer, I'll keep it as-is. I basically find the short title confusing (the file is not about the common I/O layer as a whole, but only about parameters etc.) Maybe "S/390 common I/O layer user interface"? But I don't care about this deeply :) > > > diff --git a/Documentation/s390/vfio-ccw.txt b/Documentation/s390/vfio-ccw.rst > > > similarity index 89% > > > rename from Documentation/s390/vfio-ccw.txt > > > rename to Documentation/s390/vfio-ccw.rst > > > index 2be11ad864ff..1f6d0b56d53e 100644 > > > --- a/Documentation/s390/vfio-ccw.txt > > > +++ b/Documentation/s390/vfio-ccw.rst > > > > (...) > > > > > @@ -295,6 +321,6 @@ Reference > > > 1. ESA/s390 Principles of Operation manual (IBM Form. No. SA22-7832) > > > 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204) > > > 3. https://en.wikipedia.org/wiki/Channel_I/O > > > -4. Documentation/s390/cds.txt > > > +4. Documentation/s390/cds.rst > > > > 5. Documentation/vfio.txt > > > 6. Documentation/vfio-mediated-device.txt > > > > Are these two renamed in a later patch? > > Yes. Patch 56 renames almost all Documentation/*.txt to .rst. Those files > are already parsed properly by Sphinx, so no changes there are needed. > > I'm working on followup patches (not submitted yet), with moves all > ReST files under Documentation to some place. > > In the specific case of those files, on the series I'm working, > I moved them to be part of the driver-api: > > https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames&id=3387ab063cf43f91d5c0f79d741244e7dbcdec05 > > The results, when parsed, are at: > > https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio.html > https://www.infradead.org/~mchehab/rst_conversion/driver-api/vfio-mediated-device.html Sounds good! ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2019-04-24 12:52 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <cover.1555938375.git.mchehab+samsung@kernel.org>
2019-04-22 13:27 ` [PATCH v2 30/79] docs: Debugging390.txt: convert table to ascii artwork Mauro Carvalho Chehab
2019-04-22 13:27 ` [PATCH v2 32/79] s390: include/asm/debug.h add kerneldoc markups Mauro Carvalho Chehab
[not found] ` <fb86b676b3b426732f1f11378868a9bd3b580b46.1555938376.git.mchehab+samsung@kernel.org>
2019-04-23 16:12 ` [PATCH v2 31/79] docs: s390: convert docs to ReST and rename to *.rst Farhan Ali
2019-04-23 19:46 ` Mauro Carvalho Chehab
2019-04-24 11:41 ` Cornelia Huck
2019-04-24 12:30 ` Heiko Carstens
2019-04-24 12:44 ` Mauro Carvalho Chehab
2019-04-24 12:52 ` Cornelia Huck
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox