Merge branch 'refs/heads/upstream-HEAD' into repo-HEAD

Author: Delphix Engineering

CONTRIBUTING.rst

@@ -0,0 +1,88 @@
+Contributing
+============
+
+Thanks for your interest in drgn! See below for how to build, test, code, and
+submit changes for drgn.
+
+Building
+--------
+
+The easiest way to develop drgn is by building and running it locally. See the
+`installation documentation
+<https://drgn.readthedocs.io/en/latest/installation.html#development>`_.
+
+Testing
+-------
+
+.. highlight:: console
+
+Tests should be added for all features and bug fixes.
+
+drgn's test suite can be run with::
+
+    $ python3 setup.py test
+
+To run Linux kernel helper tests in a virtual machine on all supported kernels,
+add ``-K``. See `vmtest <vmtest/README.rst>`_ for more details.
+
+Tests can also be run manually with `unittest
+<https://docs.python.org/3/library/unittest.html#command-line-interface>`_
+after building locally::
+
+    $ python3 -m unittest discover -v
+
+To run Linux kernel helper tests on the running kernel, this must be run as
+root, and debug information for the running kernel must be available.
+
+Coding Guidelines
+-----------------
+
+* Core functionality should be implemented in ``libdrgn`` and exposed to Python
+  via the `C extension <libdrgn/python>`_. Only the CLI and helpers should be
+  in pure Python.
+* Linux kernel helpers should work on all supported kernels if possible.
+
+C
+^
+
+C code in drgn mostly follows the `Linux kernel coding style
+<https://www.kernel.org/doc/html/latest/process/coding-style.html>`_ except
+that drgn requires C11 or newer, so declarations may be mixed with code.
+
+A few other guidelines:
+
+* Functions that can fail should return a ``struct drgn_error *`` (and return
+  their result via an out parameter if necessary).
+* Out parameters should be named ``ret`` (or suffixed with ``_ret`` if there
+  are multiple).
+* Constants should be defined as enums or ``static const`` variables rather
+  than macros.
+
+drgn assumes some `implementation-defined behavior
+<https://gcc.gnu.org/onlinedocs/gcc/C-Implementation.html>`_ for sanity:
+
+* Signed integers are represented with two's complement.
+* Bitwise operators on signed integers operate on the two's complement
+  representation.
+* Right shift of a signed integer type is arithmetic.
+* Conversion to a signed integer type is modular.
+* Casting between pointers and integers does not change the bit representation.
+
+Python
+^^^^^^
+
+Python code in drgn is formatted with `black <https://github.com/psf/black>`_.
+Code should be compatible with Python 3.6 and newer.
+
+Type hints should be provided for all public interfaces other than helpers
+(including the C extension) and most private interfaces.
+
+Submitting PRs
+--------------
+
+Pull requests and issues are always welcome. Feel free to start a discussion
+with a prototype.
+
+All commits must be signed off (i.e., ``Signed-off-by: Jane Doe
+<[email protected]>``) as per the `Developer Certificate of Origin
+<https://developercertificate.org/>`_. ``git commit -s`` can do this for you.

README.rst

@@ -56,6 +56,8 @@ Installation
 
 .. start-install-dependencies
 
+.. highlight:: console
+
 Install dependencies:
 
 Arch Linux::
@@ -81,9 +83,7 @@ Optionally, install:
 
 .. end-install-dependencies
 
-Then, run:
-
-.. code-block:: console
+Then, run::
 
     $ sudo pip3 install drgn
 

docs/installation.rst

@@ -1,7 +1,10 @@
 Installation
 ============
 
-.. highlight:: console
+There are several options for installing drgn.
+
+Dependencies
+------------
 
 drgn depends on:
 
@@ -30,8 +33,13 @@ The build requires:
     :start-after: start-install-dependencies
     :end-before: end-install-dependencies
 
-The latest release of drgn can be installed globally with `pip
-<https://pip.pypa.io>`_::
+Installation
+------------
+
+.. highlight:: console
+
+After installing dependencies, the latest release of drgn can be installed
+globally with `pip <https://pip.pypa.io>`_::
 
     $ sudo pip3 install drgn
     $ drgn --help
@@ -53,9 +61,12 @@ drgn globally::
     (drgenv) $ pip3 install drgn
     (drgenv) $ drgn --help
 
+Development
+-----------
+
 For development, drgn can be built and run locally::
 
-    $ python3 setup.py egg_info build_ext -i
+    $ CFLAGS="-Wall -Werror -g -O2" python3 setup.py egg_info build_ext -i
     $ python3 -m drgn --help
 
 libkdumpfile

libdrgn/dwarf_index.c

@@ -242,11 +242,7 @@ struct abbrev_table {
 	struct uint8_vector insns;
 };
 
-static void abbrev_table_init(struct abbrev_table *abbrev)
-{
-	uint32_vector_init(&abbrev->decls);
-	uint8_vector_init(&abbrev->insns);
-}
+#define ABBREV_TABLE_INIT { VECTOR_INIT, VECTOR_INIT }
 
 static void abbrev_table_deinit(struct abbrev_table *abbrev)
 {
@@ -1310,12 +1306,10 @@ static struct drgn_error *read_cus(struct drgn_dwarf_index *dindex,
 
 	#pragma omp parallel
 	{
-		struct compilation_unit_vector cus;
-		size_t i;
+		struct compilation_unit_vector cus = VECTOR_INIT;
 
-		compilation_unit_vector_init(&cus);
 		#pragma omp for schedule(dynamic)
-		for (i = 0; i < num_unindexed; i++) {
+		for (size_t i = 0; i < num_unindexed; i++) {
 			struct drgn_error *module_err;
 			const char *name;
 
@@ -1723,25 +1717,22 @@ read_file_name_table(struct drgn_dwarf_index *dindex,
 	Elf_Data *debug_line = cu->sections[SECTION_DEBUG_LINE];
 	const char *ptr = section_ptr(debug_line, stmt_list);
 	const char *end = section_end(debug_line);
-	struct siphash_vector directories;
-
-	siphash_vector_init(&directories);
 
 	err = skip_lnp_header(cu, &ptr, end);
 	if (err)
 		return err;
 
+	struct siphash_vector directories = VECTOR_INIT;
 	for (;;) {
-		struct siphash *hash;
 		const char *path;
 		size_t path_len;
-
 		if (!read_string(&ptr, end, &path, &path_len))
 			return drgn_eof();
 		if (!path_len)
 			break;
 
-		hash = siphash_vector_append_entry(&directories);
+		struct siphash *hash =
+			siphash_vector_append_entry(&directories);
 		if (!hash) {
 			err = &drgn_enomem;
 			goto out;
@@ -1753,17 +1744,14 @@ read_file_name_table(struct drgn_dwarf_index *dindex,
 	for (;;) {
 		const char *path;
 		size_t path_len;
-		uint64_t directory_index;
-		struct siphash hash;
-		uint64_t file_name_hash;
-
 		if (!read_string(&ptr, end, &path, &path_len)) {
 			err = drgn_eof();
 			goto out;
 		}
 		if (!path_len)
 			break;
 
+		uint64_t directory_index;
 		if ((err = read_uleb128(&ptr, end, &directory_index)))
 			goto out;
 		/* mtime, size */
@@ -1779,13 +1767,14 @@ read_file_name_table(struct drgn_dwarf_index *dindex,
 			goto out;
 		}
 
+		struct siphash hash;
 		if (directory_index)
 			hash = directories.data[directory_index - 1];
 		else
 			siphash_init(&hash, siphash_key);
 		siphash_update(&hash, path, path_len);
 
-		file_name_hash = siphash_final(&hash);
+		uint64_t file_name_hash = siphash_final(&hash);
 		if (!uint64_vector_append(file_name_table, &file_name_hash)) {
 			err = &drgn_enomem;
 			goto out;
@@ -2059,8 +2048,8 @@ static struct drgn_error *index_cu(struct drgn_dwarf_index *dindex,
 				   struct compilation_unit *cu)
 {
 	struct drgn_error *err;
-	struct abbrev_table abbrev;
-	struct uint64_vector file_name_table;
+	struct abbrev_table abbrev = ABBREV_TABLE_INIT;
+	struct uint64_vector file_name_table = VECTOR_INIT;
 	Elf_Data *debug_abbrev = cu->sections[SECTION_DEBUG_ABBREV];
 	const char *debug_abbrev_end = section_end(debug_abbrev);
 	const char *ptr = &cu->ptr[cu->is_64_bit ? 23 : 11];
@@ -2073,9 +2062,6 @@ static struct drgn_error *index_cu(struct drgn_dwarf_index *dindex,
 	unsigned int depth = 0;
 	uint64_t enum_die_offset = 0;
 
-	abbrev_table_init(&abbrev);
-	uint64_vector_init(&file_name_table);
-
 	if ((err = read_abbrev_table(section_ptr(debug_abbrev,
 						 cu->debug_abbrev_offset),
 				     debug_abbrev_end, cu, &abbrev)))
@@ -2265,8 +2251,8 @@ drgn_dwarf_index_report_end_internal(struct drgn_dwarf_index *dindex,
 				     bool report_from_dwfl)
 {
 	struct drgn_error *err;
-	struct drgn_dwarf_module_vector unindexed;
-	struct compilation_unit_vector cus;
+	struct drgn_dwarf_module_vector unindexed = VECTOR_INIT;
+	struct compilation_unit_vector cus = VECTOR_INIT;
 
 	dwfl_report_end(dindex->dwfl, NULL, NULL);
 	if (report_from_dwfl &&
@@ -2275,8 +2261,6 @@ drgn_dwarf_index_report_end_internal(struct drgn_dwarf_index *dindex,
 		err = &drgn_enomem;
 		goto err;
 	}
-	drgn_dwarf_module_vector_init(&unindexed);
-	compilation_unit_vector_init(&cus);
 	err = drgn_dwarf_index_get_unindexed(dindex, &unindexed);
 	if (err)
 		goto err;