Re: [PATCH 1/2 v5] kdump: add the vmcoreinfo documentation
在 2019年01月07日 15:55, Hatayama, Daisuke 写道: > Hi, > >> -Original Message- >> From: linux-kernel-ow...@vger.kernel.org >> [mailto:linux-kernel-ow...@vger.kernel.org] On Behalf Of Lianbo Jiang >> Sent: Monday, January 7, 2019 10:48 AM >> To: linux-ker...@vger.kernel.org >> Cc: kexec@lists.infradead.org; t...@linutronix.de; mi...@redhat.com; >> b...@alien8.de; x...@kernel.org; a...@linux-foundation.org; b...@redhat.com; >> dyo...@redhat.com; linux-...@vger.kernel.org; k-ha...@ab.jp.nec.com; >> ander...@redhat.com >> Subject: [PATCH 1/2 v5] kdump: add the vmcoreinfo documentation >> >> This document lists some variables that export to vmcoreinfo, and briefly >> describles what these variables indicate. It should be instructive for >> many people who do not know the vmcoreinfo, and it also normalizes the > > I agree to this part, but > >> exported variables as a convention between kernel and use-space. > > I don't agree to this part. > > The meaning of each symbol is decided by each feature in the kernel, > not by vmcoreinfo. I suspect anyone mistakenly understand this document is > ABI enforcing each symbol works as described. We can change symbols and > their meaning regardless of this document. > > Oh, I found this topic has already been discussed at v3, and > you removed "ABI" in the patch description at v4. > > But it seems still confusing to me. > I think the explicit description saying that this is for user-land tools, > they treats each symbol as described, > and the document never affect implementation of each kernel components, > is necessary in e.g. "Purpose of this document" section? > Thanks for your advice. If this part could make the document become a rope tied around our necks, i would like to remove this part from the patch log in next post. Regards, Lianbo >> >> Suggested-by: Borislav Petkov >> Signed-off-by: Lianbo Jiang >> --- >> Documentation/kdump/vmcoreinfo.txt | 500 + >> 1 file changed, 500 insertions(+) >> create mode 100644 Documentation/kdump/vmcoreinfo.txt >> >> diff --git a/Documentation/kdump/vmcoreinfo.txt >> b/Documentation/kdump/vmcoreinfo.txt >> new file mode 100644 >> index ..8e444586b87b >> --- /dev/null >> +++ b/Documentation/kdump/vmcoreinfo.txt >> @@ -0,0 +1,500 @@ >> + >> +VMCOREINFO >> + >> + >> +=== >> +What is the VMCOREINFO? >> +=== >> + >> +VMCOREINFO is a special ELF note section. It contains various >> +information from the kernel like structure size, page size, symbol >> +values, field offsets, etc. These data are packed into an ELF note >> +section and used by user-space tools like crash and makedumpfile to >> +analyze a kernel's memory layout. >> + >> + >> +Common variables >> + >> + >> +init_uts_ns.name.release >> + >> + >> +The version of the Linux kernel. Used to find the corresponding source >> +code from which the kernel has been built. >> + >> +PAGE_SIZE >> +- >> + >> +The size of a page. It is the smallest unit of data for memory >> +management in kernel. It is usually 4096 bytes and a page is aligned >> +on 4096 bytes. Used for computing page addresses. >> + >> +init_uts_ns >> +--- >> + >> +This is the UTS namespace, which is used to isolate two specific >> +elements of the system that relate to the uname(2) system call. The UTS >> +namespace is named after the data structure used to store information >> +returned by the uname(2) system call. >> + >> +User-space tools can get the kernel name, host name, kernel release >> +number, kernel version, architecture name and OS type from it. >> + >> +node_online_map >> +--- >> + >> +An array node_states[N_ONLINE] which represents the set of online node >> +in a system, one bit position per node number. Used to keep track of >> +which nodes are in the system and online. >> + >> +swapper_pg_dir >> +- >> + >> +The global page directory pointer of the kernel. Used to translate >> +virtual to physical addresses. >> + >> +_stext >> +-- >> + >> +Defines the beginning of the text section. In general, _stext indicates >> +the kernel start address.
RE: [PATCH 1/2 v5] kdump: add the vmcoreinfo documentation
Hi, > -Original Message- > From: linux-kernel-ow...@vger.kernel.org > [mailto:linux-kernel-ow...@vger.kernel.org] On Behalf Of Lianbo Jiang > Sent: Monday, January 7, 2019 10:48 AM > To: linux-ker...@vger.kernel.org > Cc: kexec@lists.infradead.org; t...@linutronix.de; mi...@redhat.com; > b...@alien8.de; x...@kernel.org; a...@linux-foundation.org; b...@redhat.com; > dyo...@redhat.com; linux-...@vger.kernel.org; k-ha...@ab.jp.nec.com; > ander...@redhat.com > Subject: [PATCH 1/2 v5] kdump: add the vmcoreinfo documentation > > This document lists some variables that export to vmcoreinfo, and briefly > describles what these variables indicate. It should be instructive for > many people who do not know the vmcoreinfo, and it also normalizes the I agree to this part, but > exported variables as a convention between kernel and use-space. I don't agree to this part. The meaning of each symbol is decided by each feature in the kernel, not by vmcoreinfo. I suspect anyone mistakenly understand this document is ABI enforcing each symbol works as described. We can change symbols and their meaning regardless of this document. Oh, I found this topic has already been discussed at v3, and you removed "ABI" in the patch description at v4. But it seems still confusing to me. I think the explicit description saying that this is for user-land tools, they treats each symbol as described, and the document never affect implementation of each kernel components, is necessary in e.g. "Purpose of this document" section? > > Suggested-by: Borislav Petkov > Signed-off-by: Lianbo Jiang > --- > Documentation/kdump/vmcoreinfo.txt | 500 + > 1 file changed, 500 insertions(+) > create mode 100644 Documentation/kdump/vmcoreinfo.txt > > diff --git a/Documentation/kdump/vmcoreinfo.txt > b/Documentation/kdump/vmcoreinfo.txt > new file mode 100644 > index ..8e444586b87b > --- /dev/null > +++ b/Documentation/kdump/vmcoreinfo.txt > @@ -0,0 +1,500 @@ > + > + VMCOREINFO > + > + > +=== > +What is the VMCOREINFO? > +=== > + > +VMCOREINFO is a special ELF note section. It contains various > +information from the kernel like structure size, page size, symbol > +values, field offsets, etc. These data are packed into an ELF note > +section and used by user-space tools like crash and makedumpfile to > +analyze a kernel's memory layout. > + > + > +Common variables > + > + > +init_uts_ns.name.release > + > + > +The version of the Linux kernel. Used to find the corresponding source > +code from which the kernel has been built. > + > +PAGE_SIZE > +- > + > +The size of a page. It is the smallest unit of data for memory > +management in kernel. It is usually 4096 bytes and a page is aligned > +on 4096 bytes. Used for computing page addresses. > + > +init_uts_ns > +--- > + > +This is the UTS namespace, which is used to isolate two specific > +elements of the system that relate to the uname(2) system call. The UTS > +namespace is named after the data structure used to store information > +returned by the uname(2) system call. > + > +User-space tools can get the kernel name, host name, kernel release > +number, kernel version, architecture name and OS type from it. > + > +node_online_map > +--- > + > +An array node_states[N_ONLINE] which represents the set of online node > +in a system, one bit position per node number. Used to keep track of > +which nodes are in the system and online. > + > +swapper_pg_dir > +- > + > +The global page directory pointer of the kernel. Used to translate > +virtual to physical addresses. > + > +_stext > +-- > + > +Defines the beginning of the text section. In general, _stext indicates > +the kernel start address. Used to convert a virtual address from the > +direct kernel map to a physical address. > + > +vmap_area_list > +-- > + > +Stores the virtual area list. makedumpfile can get the vmalloc start > +value from this variable. This value is necessary for vmalloc translation. > + > +mem_map > +--- > + > +Physical addresses are translated to struct pages by treating them as > +an index into the mem_map array. Right-shifting a physical address > +PAGE_SHIFT bits converts it into a page frame number which is an index > +into that mem_map array. > + > +Used to map an address to
[PATCH 1/2 v5] kdump: add the vmcoreinfo documentation
This document lists some variables that export to vmcoreinfo, and briefly describles what these variables indicate. It should be instructive for many people who do not know the vmcoreinfo, and it also normalizes the exported variables as a convention between kernel and use-space. Suggested-by: Borislav Petkov Signed-off-by: Lianbo Jiang --- Documentation/kdump/vmcoreinfo.txt | 500 + 1 file changed, 500 insertions(+) create mode 100644 Documentation/kdump/vmcoreinfo.txt diff --git a/Documentation/kdump/vmcoreinfo.txt b/Documentation/kdump/vmcoreinfo.txt new file mode 100644 index ..8e444586b87b --- /dev/null +++ b/Documentation/kdump/vmcoreinfo.txt @@ -0,0 +1,500 @@ + + VMCOREINFO + + +=== +What is the VMCOREINFO? +=== + +VMCOREINFO is a special ELF note section. It contains various +information from the kernel like structure size, page size, symbol +values, field offsets, etc. These data are packed into an ELF note +section and used by user-space tools like crash and makedumpfile to +analyze a kernel's memory layout. + + +Common variables + + +init_uts_ns.name.release + + +The version of the Linux kernel. Used to find the corresponding source +code from which the kernel has been built. + +PAGE_SIZE +- + +The size of a page. It is the smallest unit of data for memory +management in kernel. It is usually 4096 bytes and a page is aligned +on 4096 bytes. Used for computing page addresses. + +init_uts_ns +--- + +This is the UTS namespace, which is used to isolate two specific +elements of the system that relate to the uname(2) system call. The UTS +namespace is named after the data structure used to store information +returned by the uname(2) system call. + +User-space tools can get the kernel name, host name, kernel release +number, kernel version, architecture name and OS type from it. + +node_online_map +--- + +An array node_states[N_ONLINE] which represents the set of online node +in a system, one bit position per node number. Used to keep track of +which nodes are in the system and online. + +swapper_pg_dir +- + +The global page directory pointer of the kernel. Used to translate +virtual to physical addresses. + +_stext +-- + +Defines the beginning of the text section. In general, _stext indicates +the kernel start address. Used to convert a virtual address from the +direct kernel map to a physical address. + +vmap_area_list +-- + +Stores the virtual area list. makedumpfile can get the vmalloc start +value from this variable. This value is necessary for vmalloc translation. + +mem_map +--- + +Physical addresses are translated to struct pages by treating them as +an index into the mem_map array. Right-shifting a physical address +PAGE_SHIFT bits converts it into a page frame number which is an index +into that mem_map array. + +Used to map an address to the corresponding struct page. + +contig_page_data + + +Makedumpfile can get the pglist_data structure from this symbol, which +is used to describe the memory layout. + +User-space tools use this to exclude free pages when dumping memory. + +mem_section|(mem_section, NR_SECTION_ROOTS)|(mem_section, section_mem_map) +-- + +The address of the mem_section array, its length, structure size, and +the section_mem_map offset. + +It exists in the sparse memory mapping model, and it is also somewhat +similar to the mem_map variable, both of them are used to translate an +address. + +page + + +The size of a page structure. struct page is an important data structure +and it is widely used to compute the contiguous memory. + +pglist_data +--- + +The size of a pglist_data structure. This value will be used to check +if the pglist_data structure is valid. It is also used for checking the +memory type. + +zone + + +The size of a zone structure. This value is often used to check if the +zone structure has been found. It is also used for excluding free pages. + +free_area +- + +The size of a free_area structure. It indicates whether the free_area +structure is valid or not. Useful for excluding free pages. + +list_head +- + +The size of a list_head structure. Used when iterating lists in a +post-mortem analysis session. + +nodemask_t +-- + +The size of a nodemask_t type. Used to compute the number of online +nodes. + +(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor| + compound_order|compound_head) +--- + +User-space tools can compute their values based on the offset of these +variables. The variables are helpful to
