xref: /illumos-gate/usr/src/cmd/sgs/include/rtc.h (revision fec04708)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_RTC_H
27 #define	_RTC_H
28 
29 /*
30  * Global include file for the runtime configuration support.
31  */
32 #include <time.h>
33 #include <machdep.h>
34 
35 #ifdef	__cplusplus
36 extern "C" {
37 #endif
38 
39 /*
40  * Linker configuration files are designed to be mapped into memory
41  * and accessed directly. Hence, the layout of the data must follow
42  * byte order and alignment rules for the program examining it.
43  *
44  * From its initial design through the release of Solaris 10, runtime
45  * linker configuration files started with a configuration header (Rtc_head).
46  * The role of Rtc_head is to provide a table of contents to the remainder
47  * of the file. It tells what information is contained in the file,
48  * and the offset (relative to the base of the Rtc_head structure)
49  * within the file at which each item can be found. These offsets are
50  * 32-bit values. Linker configuration files are 32-bit limited, even
51  * for 64-bit platforms.
52  *
53  * It should be noted that Rtc_head contains no information that can be
54  * used to identify the type of program that created the file (byte order,
55  * elf class, and machine architecture). This leads to some difficulties:
56  *	- Interpreting a config file using a program with the opposite
57  *	  byte order can crash the program.
58  *	- Structure layout differences can cause a 64-bit version of the
59  *	  program to fail to read a 32-bit config file correctly, or
60  *	  vice versa. This was not an issue on sparc (both 32 and 64-bit
61  *	  happen to lay out the same way). However, 32 and 64-bit X86
62  *	  have differing alignment rules.
63  *	- The file command cannot easily identify a linker configuration
64  *	  file, and simply reports them as "data".
65  * Initially, the design of of these files assumed that a given file
66  * would be readable by any system. Experience shows that this is wrong.
67  * A linker config file is ABI specific, much like an object file. It should
68  * only be interpreted by a compatible program.
69  *
70  * Linker configuration files now start with an Rtc_id structure, followed
71  * immediately by Rtc_head. Rtc_id provides the information necessary to
72  * detect the type of program that wrote the file, in a manner that allows
73  * backwards compatibility with pre-existing config files:
74  *	- We can detect an old config file, because they do not start
75  *	  with the characters "\077RLC". In this case, we assume the
76  *	  file is compatible with the program interpreting it, and that
77  *	  Rtc_head is the first thing in the file.
78  *	- Solaris 10 and older will refuse to handle a config
79  *	  file that has an Rtc_id, because they will interpret
80  *	  the "\077RLC" signature as the ch_version field of Rtc_head,
81  *	  and will reject the version as being invalid.
82  *	- Rtc_id is specified such that its size will be 16 bytes
83  *	  on all systems, sufficient to align Rtc_head on any system, and
84  *	  to provide future expansion room.
85  *	- Offsets to data in the file continue to be specified relative
86  *	  to the Rtc_head address, meaning that existing software will
87  *	  continue to work with little or no modification.
88  */
89 
90 /*
91  * Identification header.
92  *
93  * This is defined in usr/src/common/sgsrtcid/sgsrtcid.h
94  * so that file(1) can also access it.
95  */
96 #include <sgsrtcid.h>
97 
98 /*
99  * Configuration header.
100  *
101  * AOUT sections (ch_adlibpath, ch_aslibpath) are obsolete and retained only
102  * for file-format compatibility.
103  */
104 typedef struct {
105 	Word	ch_version;		/* version of config file */
106 	Word	ch_cnflags;		/* configuration flags */
107 	Word	ch_dlflags;		/* dldump() flags used */
108 	Word	ch_app;			/* application that this config file */
109 					/*	is specific to */
110 	Word	ch_hash;		/* hash table offset */
111 	Word	ch_obj;			/* object table offset */
112 	Word	ch_str;			/* string table offset */
113 	Word	ch_file;		/* file entries */
114 	Word	ch_dir;			/* directory entries */
115 	Word	ch_edlibpath;		/* ELF default library path offset */
116 	Word	ch_adlibpath;		/* AOUT default library path offset */
117 	Word	ch_eslibpath;		/* ELF secure library path offset */
118 	Word	ch_aslibpath;		/* AOUT secure library path offset */
119 	Lword	ch_resbgn;		/* memory reservation required to map */
120 	Lword	ch_resend;		/*	alternative objects defined */
121 					/*	by the configuration info */
122 	Word	ch_env;			/* environment variables */
123 	Word	ch_fltr;		/* filter table entries */
124 	Word	ch_flte;		/* filtee table entries */
125 } Rtc_head;
126 
127 #define	RTC_HDR_IGNORE	0x0001		/* ignore config information */
128 #define	RTC_HDR_ALTER	0x0002		/* alternative objects are defined - */
129 					/*	these may exist without a */
130 					/*	memory reservation (see -a) */
131 #define	RTC_HDR_64	0x0004		/* 64-bit objects used */
132 #define	RTC_HDR_UPM	0x0008		/* includes unified process model */
133 
134 /*
135  * Object descriptor.
136  */
137 typedef struct {
138 	Lword	co_info;		/* validation information */
139 	Word	co_name;		/* object name (directory or file) */
140 	Word	co_hash;		/* name hash value */
141 	Half	co_id;			/* directory identifier */
142 	Half	co_flags;		/* various flags */
143 	Word	co_alter;		/* alternative object file */
144 } Rtc_obj;
145 
146 #define	RTC_OBJ_DIRENT	0x0001		/* object defines a directory */
147 #define	RTC_OBJ_ALLENTS	0x0002		/* directory was scanned for all */
148 					/*	containing objects */
149 #define	RTC_OBJ_NOEXIST	0x0004		/* object does not exist */
150 #define	RTC_OBJ_EXEC	0x0008		/* object identifies executable */
151 #define	RTC_OBJ_ALTER	0x0010		/* object has an alternate */
152 #define	RTC_OBJ_DUMP	0x0020		/* alternate created by dldump(3C) */
153 #define	RTC_OBJ_REALPTH	0x0040		/* object identifies real path */
154 #define	RTC_OBJ_NOALTER	0x0080		/* object can't have an alternate */
155 #define	RTC_OBJ_GROUP	0x0100		/* object was expanded as a group */
156 #define	RTC_OBJ_APP	0x0200		/* object indicates app which makes */
157 					/*	configuration file specific */
158 #define	RTC_OBJ_CMDLINE	0x0400		/* object specified from command line */
159 #define	RTC_OBJ_FILTER	0x0800		/* object identifies a filter */
160 #define	RTC_OBJ_FILTEE	0x1000		/* object identifies a filtee */
161 #define	RTC_OBJ_OPTINAL	0x2000		/* object alternative is optional */
162 
163 /*
164  * Directory and file descriptors.  The configuration cache (cd_dir) points to
165  * an array of directory descriptors, this in turn point to their associated
166  * arrays of file descriptors.  Both of these provide sequential access for
167  * configuration file validation (directory, and possible file stat()'s).
168  */
169 typedef struct {
170 	Word	cd_obj;			/* index to Rtc_obj */
171 	Word	cd_file;		/* index to Rtc_file[] */
172 } Rtc_dir;
173 
174 typedef	struct {
175 	Word	cf_obj;			/* index to Rtc_obj */
176 } Rtc_file;
177 
178 
179 #define	RTC_VER_NONE	0
180 #define	RTC_VER_ONE	1		/* original version */
181 #define	RTC_VER_TWO	2		/* updated for -u use */
182 #define	RTC_VER_THREE	3		/* updated for -e/-E use */
183 #define	RTC_VER_FOUR	4		/* updated for filter/filtees */
184 #define	RTC_VER_CURRENT RTC_VER_FOUR
185 #define	RTC_VER_NUM	5
186 
187 /*
188  * Environment variable descriptor.  The configuration cache (ch_env) points to
189  * an array of these descriptors.
190  */
191 typedef struct {
192 	Word	env_str;		/* index into string table */
193 	Word	env_flags;		/* various flags */
194 } Rtc_env;
195 
196 #define	RTC_ENV_REPLACE	0x0001		/* replaceable string definition */
197 #define	RTC_ENV_PERMANT	0x0002		/* permanent string definition */
198 #define	RTC_ENV_CONFIG	0x1000		/* string originates from config file */
199 
200 /*
201  * Filter descriptor.  The configuration cache (ch_flt) points to an array of
202  * these descriptors.
203  */
204 typedef struct {
205 	Word	fr_filter;		/* filter name, and filtee string */
206 	Word	fr_string;		/*	as indexs into string table */
207 	Word	fr_filtee;		/* index into filtee array */
208 } Rtc_fltr;
209 
210 typedef struct {
211 	Word	fe_filtee;
212 } Rtc_flte;
213 
214 #ifdef	__cplusplus
215 }
216 #endif
217 
218 #endif	/* _RTC_H */
219