--- a/gcc/doc/gcov.texi	Thu Oct 25 07:37:49 2018 +0900
+++ b/gcc/doc/gcov.texi	Thu Feb 13 11:34:05 2020 +0900
@@ -1,10 +1,10 @@
-@c Copyright (C) 1996-2018 Free Software Foundation, Inc.
+@c Copyright (C) 1996-2020 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
 @ignore
 @c man begin COPYRIGHT
-Copyright @copyright{} 1996-2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1996-2020 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -124,7 +124,7 @@
      [@option{-c}|@option{--branch-counts}]
      [@option{-d}|@option{--display-progress}]
      [@option{-f}|@option{--function-summaries}]
-     [@option{-i}|@option{--intermediate-format}]
+     [@option{-i}|@option{--json-format}]
      [@option{-j}|@option{--human-readable}]
      [@option{-k}|@option{--use-colors}]
      [@option{-l}|@option{--long-file-names}]
@@ -181,79 +181,164 @@
 exit without doing any further processing.
 
 @item -i
-@itemx --intermediate-format
-Output gcov file in an easy-to-parse intermediate text format that can
-be used by @command{lcov} or other tools. The output is a single
-@file{.gcov} file per @file{.gcda} file. No source code is required.
+@itemx --json-format
+Output gcov file in an easy-to-parse JSON intermediate format
+which does not require source code for generation.  The JSON
+file is compressed with gzip compression algorithm
+and the files have @file{.gcov.json.gz} extension.
 
-The format of the intermediate @file{.gcov} file is plain text with
-one entry per line
+Structure of the JSON is following:
 
 @smallexample
-version:@var{gcc_version}
-cwd:@var{working_directory}
-file:@var{source_file_name}
-function:@var{start_line_number},@var{end_line_number},@var{execution_count},@var{function_name}
-lcount:@var{line number},@var{execution_count},@var{has_unexecuted_block}
-branch:@var{line_number},@var{branch_coverage_type}
-
-Where the @var{branch_coverage_type} is
-   notexec (Branch not executed)
-   taken (Branch executed and taken)
-   nottaken (Branch executed, but not taken)
+@{
+  "current_working_directory": @var{current_working_directory},
+  "data_file": @var{data_file},
+  "format_version": @var{format_version},
+  "gcc_version": @var{gcc_version}
+  "files": [@var{file}]
+@}
 @end smallexample
 
-There can be multiple @var{file} entries in an intermediate gcov
-file. All entries following a @var{file} pertain to that source file
-until the next @var{file} entry.  If there are multiple functions that
-start on a single line, then corresponding lcount is repeated multiple
-times.
+Fields of the root element have following semantics:
+
+@itemize @bullet
+@item
+@var{current_working_directory}: working directory where
+a compilation unit was compiled
+
+@item
+@var{data_file}: name of the data file (GCDA)
+
+@item
+@var{format_version}: semantic version of the format
+
+@item
+@var{gcc_version}: version of the GCC compiler
+@end itemize
 
-Here is a sample when @option{-i} is used in conjunction with @option{-b} option:
+Each @var{file} has the following form:
+
+@smallexample
+@{
+  "file": @var{file_name},
+  "functions": [@var{function}],
+  "lines": [@var{line}]
+@}
+@end smallexample
+
+Fields of the @var{file} element have following semantics:
+
+@itemize @bullet
+@item
+@var{file_name}: name of the source file
+@end itemize
+
+Each @var{function} has the following form:
 
 @smallexample
-version: 8.1.0 20180103
-cwd:/home/gcc/testcase
-file:tmp.cpp
-function:7,7,0,_ZN3FooIcEC2Ev
-function:7,7,1,_ZN3FooIiEC2Ev
-function:8,8,0,_ZN3FooIcE3incEv
-function:8,8,2,_ZN3FooIiE3incEv
-function:18,37,1,main
-lcount:7,0,1
-lcount:7,1,0
-lcount:8,0,1
-lcount:8,2,0
-lcount:18,1,0
-lcount:21,1,0
-branch:21,taken
-branch:21,nottaken
-lcount:23,1,0
-branch:23,taken
-branch:23,nottaken
-lcount:24,1,0
-branch:24,taken
-branch:24,nottaken
-lcount:25,1,0
-lcount:27,11,0
-branch:27,taken
-branch:27,taken
-lcount:28,10,0
-lcount:30,1,1
-branch:30,nottaken
-branch:30,taken
-lcount:32,1,0
-branch:32,nottaken
-branch:32,taken
-lcount:33,0,1
-branch:33,notexec
-branch:33,notexec
-lcount:35,1,0
-branch:35,taken
-branch:35,nottaken
-lcount:36,1,0
+@{
+  "blocks": @var{blocks},
+  "blocks_executed": @var{blocks_executed},
+  "demangled_name": "@var{demangled_name},
+  "end_column": @var{end_column},
+  "end_line": @var{end_line},
+  "execution_count": @var{execution_count},
+  "name": @var{name},
+  "start_column": @var{start_column}
+  "start_line": @var{start_line}
+@}
 @end smallexample
 
+Fields of the @var{function} element have following semantics:
+
+@itemize @bullet
+@item
+@var{blocks}: number of blocks that are in the function
+
+@item
+@var{blocks_executed}: number of executed blocks of the function
+
+@item
+@var{demangled_name}: demangled name of the function
+
+@item
+@var{end_column}: column in the source file where the function ends
+
+@item
+@var{end_line}: line in the source file where the function ends
+
+@item
+@var{execution_count}: number of executions of the function
+
+@item
+@var{name}: name of the function
+
+@item
+@var{start_column}: column in the source file where the function begins
+
+@item
+@var{start_line}: line in the source file where the function begins
+@end itemize
+
+Note that line numbers and column numbers number from 1.  In the current
+implementation, @var{start_line} and @var{start_column} do not include
+any template parameters and the leading return type but that
+this is likely to be fixed in the future.
+
+Each @var{line} has the following form:
+
+@smallexample
+@{
+  "branches": [@var{branch}],
+  "count": @var{count},
+  "line_number": @var{line_number},
+  "unexecuted_block": @var{unexecuted_block}
+  "function_name": @var{function_name},
+@}
+@end smallexample
+
+Branches are present only with @var{-b} option.
+Fields of the @var{line} element have following semantics:
+
+@itemize @bullet
+@item
+@var{count}: number of executions of the line
+
+@item
+@var{line_number}: line number
+
+@item
+@var{unexecuted_block}: flag whether the line contains an unexecuted block
+(not all statements on the line are executed)
+
+@item
+@var{function_name}: a name of a function this @var{line} belongs to
+(for a line with an inlined statements can be not set)
+@end itemize
+
+Each @var{branch} has the following form:
+
+@smallexample
+@{
+  "count": @var{count},
+  "fallthrough": @var{fallthrough},
+  "throw": @var{throw}
+@}
+@end smallexample
+
+Fields of the @var{branch} element have following semantics:
+
+@itemize @bullet
+@item
+@var{count}: number of executions of the branch
+
+@item
+@var{fallthrough}: true when the branch is a fall through branch
+
+@item
+@var{throw}: true when the branch is an exceptional branch
+@end itemize
+
 @item -j
 @itemx --human-readable
 Write counts in human readable format (like 24.6k).
@@ -346,13 +431,15 @@
 
 @item -x
 @itemx --hash-filenames
-By default, gcov uses the full pathname of the source files to create
+When using @var{--preserve-paths},
+gcov uses the full pathname of the source files to create
 an output filename.  This can lead to long filenames that can overflow
 filesystem limits.  This option creates names of the form
 @file{@var{source-file}##@var{md5}.gcov},
 where the @var{source-file} component is the final filename part and
 the @var{md5} component is calculated from the full mangled name that
-would have been used otherwise.
+would have been used otherwise.  The option is an alternative
+to the @var{--preserve-paths} on systems which have a filesystem limit.
 
 @end table
 
@@ -423,8 +510,8 @@
 conventionally be rounded to 0% or 100% are instead printed as the
 nearest non-boundary value.
 
-When using @command{gcov}, you must first compile your program with two
-special GCC options: @samp{-fprofile-arcs -ftest-coverage}.
+When using @command{gcov}, you must first compile your program
+with a special GCC option @samp{--coverage}.
 This tells the compiler to generate additional information needed by
 gcov (basically a flow graph of the program) and also includes
 additional code in the object files for generating the extra profiling
@@ -441,7 +528,7 @@
 is what you see when you use the basic @command{gcov} facility:
 
 @smallexample
-$ g++ -fprofile-arcs -ftest-coverage tmp.cpp
+$ g++ --coverage tmp.cpp
 $ a.out
 $ gcov tmp.cpp -m
 File 'tmp.cpp'
@@ -739,8 +826,8 @@
 @section Using @command{gcov} with GCC Optimization
 
 If you plan to use @command{gcov} to help optimize your code, you must
-first compile your program with two special GCC options:
-@samp{-fprofile-arcs -ftest-coverage}.  Aside from that, you can use any
+first compile your program with a special GCC option
+@samp{--coverage}.  Aside from that, you can use any
 other GCC options; but if you want to prove that every single line
 in your program was executed, you should not compile with optimization
 at the same time.  On some machines the optimizer can eliminate some
@@ -842,7 +929,7 @@
 
 It is not recommended to access the coverage files directly.
 Consumers should use the intermediate format that is provided
-by @command{gcov} tool via @option{--intermediate-format} option.
+by @command{gcov} tool via @option{--json-format} option.
 
 @node Cross-profiling
 @section Data File Relocation to Support Cross-Profiling