xref: /illumos-gate/usr/src/lib/libctf/common/ctf_dwarf.c

/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */
/*
 * Copyright 2012 Jason King.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * Copyright 2020 Joyent, Inc.
 * Copyright 2020 Robert Mustacchi
 */

/*
 * CTF DWARF conversion theory.
 *
 * DWARF data contains a series of compilation units. Each compilation unit
 * generally refers to an object file or what once was, in the case of linked
 * binaries and shared objects. Each compilation unit has a series of what DWARF
 * calls a DIE (Debugging Information Entry). The set of entries that we care
 * about have type information stored in a series of attributes. Each DIE also
 * has a tag that identifies the kind of attributes that it has.
 *
 * A given DIE may itself have children. For example, a DIE that represents a
 * structure has children which represent members. Whenever we encounter a DIE
 * that has children or other values or types associated with it, we recursively
 * process those children first so that way we can then refer to the generated
 * CTF type id while processing its parent. This reduces the amount of unknowns
 * and fixups that we need. It also ensures that we don't accidentally add types
 * that an overzealous compiler might add to the DWARF data but aren't used by
 * anything in the system.
 *
 * Once we do a conversion, we store a mapping in an AVL tree that goes from the
 * DWARF's die offset, which is relative to the given compilation unit, to a
 * ctf_id_t.
 *
 * Unfortunately, some compilers actually will emit duplicate entries for a
 * given type that look similar, but aren't quite. To that end, we go through
 * and do a variant on a merge once we're done processing a single compilation
 * unit which deduplicates all of the types that are in the unit.
 *
 * Finally, if we encounter an object that has multiple compilation units, then
 * we'll convert all of the compilation units separately and then do a merge, so
 * that way we can result in one single ctf_file_t that represents everything
 * for the object.
 *
 * Conversion Steps
 * ----------------
 *
 * Because a given object we've been given to convert may have multiple
 * compilation units, we break the work into two halves. The first half
 * processes each compilation unit (potentially in parallel) and then the second
 * half optionally merges all of the dies in the first half. First, we'll cover
 * what's involved in converting a single ctf_cu_t's dwarf to CTF. This covers
 * the work done in ctf_dwarf_convert_one().
 *
 * An individual ctf_cu_t, which represents a compilation unit, is converted to
 * CTF in a series of multiple passes.
 *
 * Pass 1: During the first pass we walk all of the top-level dies and if we
 * find a function, variable, struct, union, enum or typedef, we recursively
 * transform all of its types. We don't recurse or process everything, because
 * we don't want to add some of the types that compilers may add which are
 * effectively unused.
 *
 * During pass 1, if we encounter any structures or unions we mark them for
 * fixing up later. This is necessary because we may not be able to determine
 * the full size of a structure at the beginning of time. This will happen if
 * the DWARF attribute DW_AT_byte_size is not present for a member. Because of
 * this possibility we defer adding members to structures or even converting
 * them during pass 1 and save that for pass 2. Adding all of the base
 * structures without any of their members helps deal with any circular
 * dependencies that we might encounter.
 *
 * Pass 2: This pass is used to do the first half of fixing up structures and
 * unions. Rather than walk the entire type space again, we actually walk the
 * list of structures and unions that we marked for later fixing up. Here, we
 * iterate over every structure and add members to the underlying ctf_file_t,
 * but not to the structs themselves. One might wonder why we don't, and the
 * main reason is that libctf requires a ctf_update() be done before adding the
 * members to structures or unions.
 *
 * Pass 3: This pass is used to do the second half of fixing up structures and
 * unions. During this part we always go through and add members to structures
 * and unions that we added to the container in the previous pass. In addition,
 * we set the structure and union's actual size, which may have additional
 * padding added by the compiler, it isn't simply the last offset. DWARF always
 * guarantees an attribute exists for this. Importantly no ctf_id_t's change
 * during pass 2.
 *
 * Pass 4: The next phase is to add CTF entries for all of the symbols and
 * variables that are present in this die. During pass 1 we added entries to a
 * map for each variable and function. During this pass, we iterate over the
 * symbol table and when we encounter a symbol that we have in our lists of
 * translated information which matches, we then add it to the ctf_file_t.
 *
 * Pass 5: Here we go and look for any weak symbols and functions and see if
 * they match anything that we recognize. If so, then we add type information
 * for them at this point based on the matching type.
 *
 * Pass 6: This pass is actually a variant on a merge. The traditional merge
 * process expects there to be no duplicate types. As such, at the end of
 * conversion, we do a dedup on all of the types in the system. The
 * deduplication process is described in lib/libctf/common/ctf_merge.c.
 *
 * Once pass 6 is done, we've finished processing the individual compilation
 * unit.
 *
 * The following steps reflect the general process of doing a conversion.
 *
 * 1) Walk the dwarf section and determine the number of compilation units
 * 2) Create a ctf_cu_t for each compilation unit
 * 3) Add all ctf_cu_t's to a workq
 * 4) Have the workq process each die with ctf_dwarf_convert_one. This itself
 *    is comprised of several steps, which were already enumerated.
 * 5) If we have multiple cu's, we do a ctf merge of all the dies. The mechanics
 *    of the merge are discussed in lib/libctf/common/ctf_merge.c.
 * 6) Free everything up and return a ctf_file_t to the user. If we only had a
 *    single compilation unit, then we give that to the user. Otherwise, we
 *    return the merged ctf_file_t.
 *
 * Threading
 * ---------
 *
 * The process has been designed to be amenable to threading. Each compilation
 * unit has its own type stream, therefore the logical place to divide and
 * conquer is at the compilation unit. Each ctf_cu_t has been built to be able
 * to be processed independently of the others. It has its own libdwarf handle,
 * as a given libdwarf handle may only be used by a single thread at a time.
 * This allows the various ctf_cu_t's to be processed in parallel by different
 * threads.
 *
 * All of the ctf_cu_t's are loaded into a workq which allows for a number of
 * threads to be specified and used as a thread pool to process all of the
 * queued work. We set the number of threads to use in the workq equal to the
 * number of threads that the user has specified.
 *
 * After all of the compilation units have been drained, we use the same number
 * of threads when performing a merge of multiple compilation units, if they
 * exist.
 *
 * While all of these different parts do support and allow for multiple threads,
 * it's important that when only a single thread is specified, that it be the
 * calling thread. This allows the conversion routines to be used in a context
 * that doesn't allow additional threads, such as rtld.
 *
 * Common DWARF Mechanics and Notes
 * --------------------------------
 *
 * At this time, we really only support DWARFv2, though support for DWARFv4 is
 * mostly there. There is no intent to support DWARFv3.
 *
 * Generally types for something are stored in the DW_AT_type attribute. For
 * example, a function's return type will be stored in the local DW_AT_type
 * attribute while the arguments will be in child DIEs. There are also various
 * times when we don't have any DW_AT_type. In that case, the lack of a type
 * implies, at least for C, that its C type is void. Because DWARF doesn't emit
 * one, we have a synthetic void type that we create and manipulate instead and
 * pass it off to consumers on an as-needed basis. If nothing has a void type,
 * it will not be emitted.
 *
 * Architecture Specific Parts
 * ---------------------------
 *
 * The CTF tooling encodes various information about the various architectures
 * in the system. Importantly, the tool assumes that every architecture has a
 * data model where long and pointer are the same size. This is currently the
 * case, as the two data models illumos supports are ILP32 and LP64.
 *
 * In addition, we encode the mapping of various floating point sizes to various
 * types for each architecture. If a new architecture is being added, it should
 * be added to the list. The general design of the ctf conversion tools is to be
 * architecture independent. eg. any of the tools here should be able to convert
 * any architecture's DWARF into ctf; however, this has not been rigorously
 * tested and more importantly, the ctf routines don't currently write out the
 * data in an endian-aware form, they only use that of the currently running
 * library.
 */

#include <libctf_impl.h>
#include <sys/avl.h>
#include <sys/debug.h>
#include <gelf.h>
#include <libdwarf.h>
#include <dwarf.h>
#include <libgen.h>
#include <workq.h>
#include <errno.h>

#define	DWARF_VERSION_TWO	2
#define	DWARF_VERSION_FOUR	4
#define	DWARF_VARARGS_NAME	"..."

/*
 * Dwarf may refer recursively to other types that we've already processed. To
 * see if we've already converted them, we look them up in an AVL tree that's
 * sorted by the DWARF id.
 */
typedef struct ctf_dwmap {
	avl_node_t	cdm_avl;
	Dwarf_Off	cdm_off;
	Dwarf_Die	cdm_die;
	ctf_id_t	cdm_id;
	boolean_t	cdm_fix;
} ctf_dwmap_t;

typedef struct ctf_dwvar {
	ctf_list_t	cdv_list;
	char		*cdv_name;
	ctf_id_t	cdv_type;
	boolean_t	cdv_global;
} ctf_dwvar_t;

typedef struct ctf_dwfunc {
	ctf_list_t	cdf_list;
	char		*cdf_name;
	ctf_funcinfo_t	cdf_fip;
	ctf_id_t	*cdf_argv;
	boolean_t	cdf_global;
} ctf_dwfunc_t;

typedef struct ctf_dwbitf {
	ctf_list_t	cdb_list;
	ctf_id_t	cdb_base;
	uint_t		cdb_nbits;
	ctf_id_t	cdb_id;
} ctf_dwbitf_t;

/*
 * The ctf_cu_t represents a single top-level DWARF die unit. While generally,
 * the typical object file has only a single die, if we're asked to convert
 * something that's been linked from multiple sources, multiple dies will exist.
 */
typedef struct ctf_die {
	Elf		*cu_elf;	/* shared libelf handle */
	char		*cu_name;	/* basename of the DIE */
	ctf_merge_t	*cu_cmh;	/* merge handle */
	ctf_list_t	cu_vars;	/* List of variables */
	ctf_list_t	cu_funcs;	/* List of functions */
	ctf_list_t	cu_bitfields;	/* Bit field members */
	Dwarf_Debug	cu_dwarf;	/* libdwarf handle */
	Dwarf_Die	cu_cu;		/* libdwarf compilation unit */
	Dwarf_Off	cu_cuoff;	/* cu's offset */
	Dwarf_Off	cu_maxoff;	/* maximum offset */
	Dwarf_Half	cu_vers;	/* Dwarf Version */
	Dwarf_Half	cu_addrsz;	/* Dwarf Address Size */
	ctf_file_t	*cu_ctfp;	/* output CTF file */
	avl_tree_t	cu_map;		/* map die offsets to CTF types */
	char		*cu_errbuf;	/* error message buffer */
	size_t		cu_errlen;	/* error message buffer length */
	size_t		cu_ptrsz;	/* object's pointer size */
	boolean_t	cu_bigend;	/* is it big endian */
	boolean_t	cu_doweaks;	/* should we convert weak symbols? */
	uint_t		cu_mach;	/* machine type */
	ctf_id_t	cu_voidtid;	/* void pointer */
	ctf_id_t	cu_longtid;	/* id for a 'long' */
} ctf_cu_t;

static int ctf_dwarf_offset(ctf_cu_t *, Dwarf_Die, Dwarf_Off *);
static int ctf_dwarf_convert_die(ctf_cu_t *, Dwarf_Die);
static int ctf_dwarf_convert_type(ctf_cu_t *, Dwarf_Die, ctf_id_t *, int);

static int ctf_dwarf_function_count(ctf_cu_t *, Dwarf_Die, ctf_funcinfo_t *,
    boolean_t);
static int ctf_dwarf_convert_fargs(ctf_cu_t *, Dwarf_Die, ctf_funcinfo_t *,
    ctf_id_t *);

/*
 * This is a generic way to set a CTF Conversion backend error depending on what
 * we were doing. Unless it was one of a specific set of errors that don't
 * indicate a programming / translation bug, eg. ENOMEM, then we transform it
 * into a CTF backend error and fill in the error buffer.
 */
static int
ctf_dwarf_error(ctf_cu_t *cup, ctf_file_t *cfp, int err, const char *fmt, ...)
{
	va_list ap;
	int ret;
	size_t off = 0;
	ssize_t rem = cup->cu_errlen;
	if (cfp != NULL)
		err = ctf_errno(cfp);

	if (err == ENOMEM)
		return (err);

	ret = snprintf(cup->cu_errbuf, rem, "die %s: ", cup->cu_name);
	if (ret < 0)
		goto err;
	off += ret;
	rem = MAX(rem - ret, 0);

	va_start(ap, fmt);
	ret = vsnprintf(cup->cu_errbuf + off, rem, fmt, ap);
	va_end(ap);
	if (ret < 0)
		goto err;

	off += ret;
	rem = MAX(rem - ret, 0);
	if (fmt[strlen(fmt) - 1] != '\n') {
		(void) snprintf(cup->cu_errbuf + off, rem,
		    ": %s\n", ctf_errmsg(err));
	}
	va_end(ap);
	return (ECTF_CONVBKERR);

err:
	cup->cu_errbuf[0] = '\0';
	return (ECTF_CONVBKERR);
}

/*
 * DWARF often opts to put no explicit type to describe a void type. eg. if we
 * have a reference type whose DW_AT_type member doesn't exist, then we should
 * instead assume it points to void. Because this isn't represented, we
 * instead cause it to come into existence.
 */
static ctf_id_t
ctf_dwarf_void(ctf_cu_t *cup)
{
	if (cup->cu_voidtid == CTF_ERR) {
		ctf_encoding_t enc = { CTF_INT_SIGNED, 0, 0 };
		cup->cu_voidtid = ctf_add_integer(cup->cu_ctfp, CTF_ADD_ROOT,
		    "void", &enc);
		if (cup->cu_voidtid == CTF_ERR) {
			(void) snprintf(cup->cu_errbuf, cup->cu_errlen,
			    "failed to create void type: %s\n",
			    ctf_errmsg(ctf_errno(cup->cu_ctfp)));
		}
	}

	return (cup->cu_voidtid);
}

/*
 * There are many different forms that an array index may take. However, we just
 * always force it to be of a type long no matter what. Therefore we use this to
 * have a single instance of long across everything.
 */
static ctf_id_t
ctf_dwarf_long(ctf_cu_t *cup)
{
	if (cup->cu_longtid == CTF_ERR) {
		ctf_encoding_t enc;

		enc.cte_format = CTF_INT_SIGNED;
		enc.cte_offset = 0;
		/* All illumos systems are LP */
		enc.cte_bits = cup->cu_ptrsz * 8;
		cup->cu_longtid = ctf_add_integer(cup->cu_ctfp, CTF_ADD_NONROOT,
		    "long", &enc);
		if (cup->cu_longtid == CTF_ERR) {
			(void) snprintf(cup->cu_errbuf, cup->cu_errlen,
			    "failed to create long type: %s\n",
			    ctf_errmsg(ctf_errno(cup->cu_ctfp)));
		}

	}

	return (cup->cu_longtid);
}