1179193Sjb/* 2179193Sjb * CDDL HEADER START 3179193Sjb * 4179193Sjb * The contents of this file are subject to the terms of the 5179193Sjb * Common Development and Distribution License, Version 1.0 only 6179193Sjb * (the "License"). You may not use this file except in compliance 7179193Sjb * with the License. 8179193Sjb * 9179193Sjb * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10179193Sjb * or http://www.opensolaris.org/os/licensing. 11179193Sjb * See the License for the specific language governing permissions 12179193Sjb * and limitations under the License. 13179193Sjb * 14179193Sjb * When distributing Covered Code, include this CDDL HEADER in each 15179193Sjb * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16179193Sjb * If applicable, add the following below this CDDL HEADER, with the 17179193Sjb * fields enclosed by brackets "[]" replaced with your own identifying 18179193Sjb * information: Portions Copyright [yyyy] [name of copyright owner] 19179193Sjb * 20179193Sjb * CDDL HEADER END 21179193Sjb */ 22179193Sjb/* 23179193Sjb * Copyright 2005 Sun Microsystems, Inc. All rights reserved. 24179193Sjb * Use is subject to license terms. 25179193Sjb */ 26254744Sdelphij/* 27267941Srpaulo * Copyright (c) 2013, Joyent, Inc. All rights reserved. 28254744Sdelphij */ 29179193Sjb 30179193Sjb/* 31179193Sjb * This header file defines the interfaces available from the CTF debugger 32179193Sjb * library, libctf, and an equivalent kernel module. This API can be used by 33179193Sjb * a debugger to operate on data in the Compact ANSI-C Type Format (CTF). 34179193Sjb * This is NOT a public interface, although it may eventually become one in 35179193Sjb * the fullness of time after we gain more experience with the interfaces. 36179193Sjb * 37179193Sjb * In the meantime, be aware that any program linked with this API in this 38179193Sjb * release of Solaris is almost guaranteed to break in the next release. 39179193Sjb * 40179193Sjb * In short, do not user this header file or the CTF routines for any purpose. 41179193Sjb */ 42179193Sjb 43179193Sjb#ifndef _CTF_API_H 44179193Sjb#define _CTF_API_H 45179193Sjb 46179193Sjb#include <sys/types.h> 47179193Sjb#include <sys/param.h> 48179193Sjb#include <sys/elf.h> 49179193Sjb#include <sys/ctf.h> 50179193Sjb 51179193Sjb#ifdef __cplusplus 52179193Sjbextern "C" { 53179193Sjb#endif 54179193Sjb 55179193Sjb/* 56179193Sjb * Clients can open one or more CTF containers and obtain a pointer to an 57179193Sjb * opaque ctf_file_t. Types are identified by an opaque ctf_id_t token. 58179193Sjb * These opaque definitions allow libctf to evolve without breaking clients. 59179193Sjb */ 60179193Sjbtypedef struct ctf_file ctf_file_t; 61179193Sjbtypedef long ctf_id_t; 62179193Sjb 63179193Sjb/* 64179193Sjb * If the debugger needs to provide the CTF library with a set of raw buffers 65179193Sjb * for use as the CTF data, symbol table, and string table, it can do so by 66179193Sjb * filling in ctf_sect_t structures and passing them to ctf_bufopen(): 67179193Sjb */ 68179193Sjbtypedef struct ctf_sect { 69223262Sbenl const char *cts_name; /* section name (if any) */ 70179193Sjb ulong_t cts_type; /* section type (ELF SHT_... value) */ 71179193Sjb ulong_t cts_flags; /* section flags (ELF SHF_... value) */ 72277300Ssmh#ifdef illumos 73179193Sjb const void *cts_data; /* pointer to section data */ 74179198Sjb#else 75179198Sjb void *cts_data; /* pointer to section data */ 76179198Sjb#endif 77179193Sjb size_t cts_size; /* size of data in bytes */ 78179193Sjb size_t cts_entsize; /* size of each section entry (symtab only) */ 79179193Sjb off64_t cts_offset; /* file offset of this section (if any) */ 80179193Sjb} ctf_sect_t; 81179193Sjb 82179193Sjb/* 83179193Sjb * Encoding information for integers, floating-point values, and certain other 84179193Sjb * intrinsics can be obtained by calling ctf_type_encoding(), below. The flags 85179193Sjb * field will contain values appropriate for the type defined in <sys/ctf.h>. 86179193Sjb */ 87179193Sjbtypedef struct ctf_encoding { 88179193Sjb uint_t cte_format; /* data format (CTF_INT_* or CTF_FP_* flags) */ 89179193Sjb uint_t cte_offset; /* offset of value in bits */ 90179193Sjb uint_t cte_bits; /* size of storage in bits */ 91179193Sjb} ctf_encoding_t; 92179193Sjb 93179193Sjbtypedef struct ctf_membinfo { 94179193Sjb ctf_id_t ctm_type; /* type of struct or union member */ 95179193Sjb ulong_t ctm_offset; /* offset of member in bits */ 96179193Sjb} ctf_membinfo_t; 97179193Sjb 98179193Sjbtypedef struct ctf_arinfo { 99179193Sjb ctf_id_t ctr_contents; /* type of array contents */ 100179193Sjb ctf_id_t ctr_index; /* type of array index */ 101179193Sjb uint_t ctr_nelems; /* number of elements */ 102179193Sjb} ctf_arinfo_t; 103179193Sjb 104179193Sjbtypedef struct ctf_funcinfo { 105179193Sjb ctf_id_t ctc_return; /* function return type */ 106179193Sjb uint_t ctc_argc; /* number of typed arguments to function */ 107179193Sjb uint_t ctc_flags; /* function attributes (see below) */ 108179193Sjb} ctf_funcinfo_t; 109179193Sjb 110179193Sjbtypedef struct ctf_lblinfo { 111179193Sjb ctf_id_t ctb_typeidx; /* last type associated with the label */ 112179193Sjb} ctf_lblinfo_t; 113179193Sjb 114179193Sjb#define CTF_FUNC_VARARG 0x1 /* function arguments end with varargs */ 115179193Sjb 116179193Sjb/* 117179193Sjb * Functions that return integer status or a ctf_id_t use the following value 118179193Sjb * to indicate failure. ctf_errno() can be used to obtain an error code. 119179193Sjb */ 120179193Sjb#define CTF_ERR (-1L) 121179193Sjb 122179193Sjb/* 123179193Sjb * The CTF data model is inferred to be the caller's data model or the data 124179193Sjb * model of the given object, unless ctf_setmodel() is explicitly called. 125179193Sjb */ 126179193Sjb#define CTF_MODEL_ILP32 1 /* object data model is ILP32 */ 127179193Sjb#define CTF_MODEL_LP64 2 /* object data model is LP64 */ 128179193Sjb#ifdef _LP64 129179193Sjb#define CTF_MODEL_NATIVE CTF_MODEL_LP64 130179193Sjb#else 131179193Sjb#define CTF_MODEL_NATIVE CTF_MODEL_ILP32 132179193Sjb#endif 133179193Sjb 134179193Sjb/* 135179193Sjb * Dynamic CTF containers can be created using ctf_create(). The ctf_add_* 136179193Sjb * routines can be used to add new definitions to the dynamic container. 137179193Sjb * New types are labeled as root or non-root to determine whether they are 138179193Sjb * visible at the top-level program scope when subsequently doing a lookup. 139179193Sjb */ 140179193Sjb#define CTF_ADD_NONROOT 0 /* type only visible in nested scope */ 141179193Sjb#define CTF_ADD_ROOT 1 /* type visible at top-level scope */ 142179193Sjb 143179193Sjb/* 144179193Sjb * These typedefs are used to define the signature for callback functions 145179193Sjb * that can be used with the iteration and visit functions below: 146179193Sjb */ 147179193Sjbtypedef int ctf_visit_f(const char *, ctf_id_t, ulong_t, int, void *); 148179193Sjbtypedef int ctf_member_f(const char *, ctf_id_t, ulong_t, void *); 149179193Sjbtypedef int ctf_enum_f(const char *, int, void *); 150179193Sjbtypedef int ctf_type_f(ctf_id_t, void *); 151179193Sjbtypedef int ctf_label_f(const char *, const ctf_lblinfo_t *, void *); 152179193Sjb 153179193Sjbextern ctf_file_t *ctf_bufopen(const ctf_sect_t *, const ctf_sect_t *, 154179193Sjb const ctf_sect_t *, int *); 155179193Sjbextern ctf_file_t *ctf_fdopen(int, int *); 156179193Sjbextern ctf_file_t *ctf_open(const char *, int *); 157179193Sjbextern ctf_file_t *ctf_create(int *); 158267941Srpauloextern ctf_file_t *ctf_dup(ctf_file_t *); 159179193Sjbextern void ctf_close(ctf_file_t *); 160179193Sjb 161179193Sjbextern ctf_file_t *ctf_parent_file(ctf_file_t *); 162179193Sjbextern const char *ctf_parent_name(ctf_file_t *); 163179193Sjb 164179193Sjbextern int ctf_import(ctf_file_t *, ctf_file_t *); 165179193Sjbextern int ctf_setmodel(ctf_file_t *, int); 166179193Sjbextern int ctf_getmodel(ctf_file_t *); 167179193Sjb 168179193Sjbextern void ctf_setspecific(ctf_file_t *, void *); 169179193Sjbextern void *ctf_getspecific(ctf_file_t *); 170179193Sjb 171179193Sjbextern int ctf_errno(ctf_file_t *); 172179193Sjbextern const char *ctf_errmsg(int); 173179193Sjbextern int ctf_version(int); 174179193Sjb 175179193Sjbextern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *); 176179193Sjbextern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *); 177179193Sjb 178179193Sjbextern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *); 179179193Sjbextern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t); 180179193Sjb 181179193Sjbextern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t); 182179193Sjbextern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t); 183179193Sjbextern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t); 184267941Srpauloextern char *ctf_type_qname(ctf_file_t *, ctf_id_t, char *, size_t, 185267941Srpaulo const char *); 186179193Sjbextern ssize_t ctf_type_size(ctf_file_t *, ctf_id_t); 187179193Sjbextern ssize_t ctf_type_align(ctf_file_t *, ctf_id_t); 188179193Sjbextern int ctf_type_kind(ctf_file_t *, ctf_id_t); 189179193Sjbextern ctf_id_t ctf_type_reference(ctf_file_t *, ctf_id_t); 190179193Sjbextern ctf_id_t ctf_type_pointer(ctf_file_t *, ctf_id_t); 191179193Sjbextern int ctf_type_encoding(ctf_file_t *, ctf_id_t, ctf_encoding_t *); 192179193Sjbextern int ctf_type_visit(ctf_file_t *, ctf_id_t, ctf_visit_f *, void *); 193179193Sjbextern int ctf_type_cmp(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t); 194179193Sjbextern int ctf_type_compat(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t); 195179193Sjb 196179193Sjbextern int ctf_member_info(ctf_file_t *, ctf_id_t, const char *, 197179193Sjb ctf_membinfo_t *); 198179193Sjbextern int ctf_array_info(ctf_file_t *, ctf_id_t, ctf_arinfo_t *); 199179193Sjb 200179193Sjbextern const char *ctf_enum_name(ctf_file_t *, ctf_id_t, int); 201179193Sjbextern int ctf_enum_value(ctf_file_t *, ctf_id_t, const char *, int *); 202179193Sjb 203179193Sjbextern const char *ctf_label_topmost(ctf_file_t *); 204179193Sjbextern int ctf_label_info(ctf_file_t *, const char *, ctf_lblinfo_t *); 205179193Sjb 206179193Sjbextern int ctf_member_iter(ctf_file_t *, ctf_id_t, ctf_member_f *, void *); 207179193Sjbextern int ctf_enum_iter(ctf_file_t *, ctf_id_t, ctf_enum_f *, void *); 208179193Sjbextern int ctf_type_iter(ctf_file_t *, ctf_type_f *, void *); 209179193Sjbextern int ctf_label_iter(ctf_file_t *, ctf_label_f *, void *); 210179193Sjb 211179193Sjbextern ctf_id_t ctf_add_array(ctf_file_t *, uint_t, const ctf_arinfo_t *); 212179193Sjbextern ctf_id_t ctf_add_const(ctf_file_t *, uint_t, ctf_id_t); 213179193Sjbextern ctf_id_t ctf_add_enum(ctf_file_t *, uint_t, const char *); 214179193Sjbextern ctf_id_t ctf_add_float(ctf_file_t *, uint_t, 215179193Sjb const char *, const ctf_encoding_t *); 216179193Sjbextern ctf_id_t ctf_add_forward(ctf_file_t *, uint_t, const char *, uint_t); 217179193Sjbextern ctf_id_t ctf_add_function(ctf_file_t *, uint_t, 218179193Sjb const ctf_funcinfo_t *, const ctf_id_t *); 219179193Sjbextern ctf_id_t ctf_add_integer(ctf_file_t *, uint_t, 220179193Sjb const char *, const ctf_encoding_t *); 221179193Sjbextern ctf_id_t ctf_add_pointer(ctf_file_t *, uint_t, ctf_id_t); 222179193Sjbextern ctf_id_t ctf_add_type(ctf_file_t *, ctf_file_t *, ctf_id_t); 223179193Sjbextern ctf_id_t ctf_add_typedef(ctf_file_t *, uint_t, const char *, ctf_id_t); 224179193Sjbextern ctf_id_t ctf_add_restrict(ctf_file_t *, uint_t, ctf_id_t); 225179193Sjbextern ctf_id_t ctf_add_struct(ctf_file_t *, uint_t, const char *); 226179193Sjbextern ctf_id_t ctf_add_union(ctf_file_t *, uint_t, const char *); 227179193Sjbextern ctf_id_t ctf_add_volatile(ctf_file_t *, uint_t, ctf_id_t); 228179193Sjb 229179193Sjbextern int ctf_add_enumerator(ctf_file_t *, ctf_id_t, const char *, int); 230179193Sjbextern int ctf_add_member(ctf_file_t *, ctf_id_t, const char *, ctf_id_t); 231179193Sjb 232179193Sjbextern int ctf_set_array(ctf_file_t *, ctf_id_t, const ctf_arinfo_t *); 233179193Sjb 234254744Sdelphijextern int ctf_delete_type(ctf_file_t *, ctf_id_t); 235254744Sdelphij 236179193Sjbextern int ctf_update(ctf_file_t *); 237179193Sjbextern int ctf_discard(ctf_file_t *); 238179193Sjbextern int ctf_write(ctf_file_t *, int); 239179193Sjb 240179193Sjb#ifdef _KERNEL 241179193Sjb 242179193Sjbstruct module; 243179193Sjbextern ctf_file_t *ctf_modopen(struct module *, int *); 244179193Sjb 245179193Sjb#endif 246179193Sjb 247179193Sjb#ifdef __cplusplus 248179193Sjb} 249179193Sjb#endif 250179193Sjb 251179193Sjb#endif /* _CTF_API_H */ 252