html/man_s2c.1.html

   1 <!-- manual page source format generated by PolyglotMan v3.0.7, -->
   2 <!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
   3
   4 <HTML>
   5 <HEAD>
   6 <TITLE>Man page for s2c.1</TITLE>
   7 </HEAD>
   8 <BODY bgcolor=white>
   9 <A HREF="#toc">Table of Contents</A><P>
  10
  11 <H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
  12
  13 <P>
  14 s2c - convert a SUIF file to C
  15
  16 <H2><A NAME="sect1" HREF="#toc1"><B>Synopsis</B></A></H2>
  17
  18 <P>
  19 <B>s2c</B> [ <I>options</I> ] SUIF-file [C-file]
  20
  21 <H2><A NAME="sect2" HREF="#toc2"><B>Description</B></A></H2>
  22
  23 <P>
  24 The <I>s2c</I> program reads the specified SUIF file and prints
  25 out its translation into the Standard C language, if possible.
  26 If the <I>C-file</I> specification is given, it is used
  27 for output, otherwise the C code is written to standard
  28 output.
  29 <P>
  30 The output conforms to the ANSI/ISO specifications for
  31 Standard C. Each output file is self contained and does
  32 not use <I>#include</I> to include any other files. The output
  33 is <I>not</I> machine independent, however. The SUIF system
  34 determines the sizes of all data types and the locations
  35 of fields in structures and elements in arrays. To produce
  36 C output that retains type information for debugging,
  37 readability of the C code, and to allow for easier optimizations
  38 by the back-end C compiler, SUIF structures and
  39 arrays are translated into the corresponding C types, and
  40 direct structure and array accesses are translated into
  41 their C versions. In doing all of this, <I>s2c</I> makes assumptions
  42 about how the back-end C compiler will lay out and
  43 align the data within structures and arrays. It also must
  44 make assumptions about sizes of all types when doing
  45 pointer arithmetic or array indexing.
  46 <P>
  47 For these reasons, the C compiler used as a back end must
  48 use the same data size, alignment, and layout rules used
  49 by <I>snoot,</I> the SUIF C front end. If a particular existing
  50 C compiler is to be used as a back end for SUIF, <I>snoot</I>
  51 must have its configuration parameters set up to match
  52 that compiler. See the <I>snoot</I> documentation for more
  53 information.
  54
  55 <H2><A NAME="sect3" HREF="#toc3"><B>Options</B></A></H2>
  56
  57 <P>
  58 <B>-logic-simp</B><BR>
  59
  60 Do simple logical simplification on the resulting C
  61 code before writing it.
  62
  63 <DL>
  64
  65 <DT><B>-pseudo</B></DT></DT>
  66 <DD>
  67 Write pseudo-C code if the SUIF code cannot be represented
  68 by correct C code. This can happen, for
  69 example, if the SUIF code uses integer types with a
  70 size different from any of those available in the
  71 target C compiler. The default is to abort if correct
  72 C code cannot be written. In either case, a
  73 diagnostic message is printed to standard output.
  74 </DD>
  75 </DL>
  76 <P>
  77 The pseudo-C written sticks as close to C as possible.
  78 The idea is that even if the C code can't be
  79 run, the pseudo-C provides an easy-to-read way of
  80 looking at the contents of a SUIF file.
  81
  82 <DL>
  83
  84 <DT><B>-keep-casts</B></DT></DT>
  85 <DD>
  86 Put a C type cast everywhere there was a SUIF convert
  87 instruction. The default is to fold type
  88 casts away where C would implicitly do type conversion
  89 anyway.
  90 </DD>
  91
  92 <DT><B>-omit-header</B></DT></DT>
  93 <DD>
  94 Omit the header comment that normally comes at the
  95 very top of the output C file. By default this
  96 header is inserted to record when the file was created
  97 and exactly what version of <I>s2c</I> created it.
  98 </DD>
  99
 100 <DT><B>-no-warn</B></DT></DT>
 101 <DD>
 102 Do not issue any warning messages.
 103 </DD>
 104
 105 <DT><B>-always-intnum</B></DT></DT>
 106 <DD>
 107 When writing integer types, never use C types,
 108 always use pseudo-types of the form <B>int</B><I>n</I> where <I>n</I> is
 109 the size in bits, e.g. <B>int8</B> instead of <B>char.</B>
 110 </DD>
 111
 112 <DT><B>-array-exprs</B></DT></DT>
 113 <DD>
 114 Write out SUIF array expressions directly as if C
 115 allowed array expressions. By default, SUIF
 116 expressions with array type are handled by casting
 117 their locations to pointers to dummy structures of
 118 the appropriate size and then using the structure
 119 type to access them. The semantics of C turn anything
 120 with array type into a pointer and implicitly
 121 take the location of it, so expressions of array
 122 type cannot exist in real C code. With this
 123 option, the output is not valid C, and cannot even
 124 be evaluated with any consistent semantics, because
 125 both arrays and locations of arrays are written the
 126 same way and cannot be distinguished. This flag
 127 exists to make certain unusual kinds of SUIF code
 128 more readable.
 129 </DD>
 130
 131 <DT><B>-annotes-all</B></DT></DT>
 132 <DD>
 133 Write out all annotations on the SUIF code as C
 134 comments. Annotations used internally by <I>s2c</I> cannot
 135 be written out as comments, but all others will
 136 be.
 137 </DD>
 138
 139 <DT><B>-annotes-named</B> <I>name</I></DT></DT>
 140 <DD>
 141 Write out all annotations with the annotation name
 142 <I>name.</I> No other annotations will be written unless
 143 they are specified by other command-line options.
 144 </DD>
 145
 146 <DT><B>-annotes-opcode</B> <I>opcode</I></DT></DT>
 147 <DD>
 148 Write out all annotations on instructions with
 149 opcode <I>opcode.</I>
 150 </DD>
 151
 152 <DT><B>-annotes-object-kind</B> <I>kind</I></DT></DT>
 153 <DD>
 154 Write out all the annotations on one specific kind
 155 of object, where <I>kind</I> is one of the following:
 156 </DD>
 157 </DL>
 158 <P>
 159 <B>fses</B> -- all file set entries
 160 <P>
 161 <B>nodes</B> -- all tree nodes (except tree_instr nodes,
 162 because no permanent annotations are allowed on
 163 tree_instrs)
 164 <P>
 165 <B>loops</B> -- all ``loop'' nodes
 166 <P>
 167 <B>fors</B> -- all ``for'' nodes
 168 <P>
 169 <B>ifs</B> -- all ``if'' nodes
 170 <P>
 171 <B>blocks</B> -- all ``block'' nodes
 172 <P>
 173 <B>all-instrs</B> -- all instructions
 174 <P>
 175 <B>symtabs</B> -- all symbol tables
 176 <P>
 177 <B>all-syms</B> -- all symbols
 178 <P>
 179 <B>vars</B> -- all variable symbols
 180 <P>
 181 <B>proc-syms</B> -- all procedure symbols
 182 <P>
 183 <B>labels</B> -- all label symbols
 184 <P>
 185 <B>var-defs</B> -- all variable definitions
 186 <P>
 187 <B>types</B> -- all types
 188
 189 <DL>
 190
 191 <DT><B>-gcc-bug</B></DT></DT>
 192 <DD>
 193 Write C code that uses a work-around to avoid a bug
 194 in the way gcc handles initialization of unnamed
 195 bit-fields. The ANSI rules say that unnamed bit
 196 fields are to be ignored in initialization of
 197 structures, and <I>s2c</I> assumes this when writing output
 198 code. Currect versions of gcc, however, try to
 199 assign initializers to the unnamed bit fields and
 200 all the initializers get assigned to the wrong
 201 fields, resulting in compile-time warnings and
 202 errors, and run-time failures. The work-around
 203 causes <I>s2c</I> to put in named fields to replace
 204 unnamed bit fields whenever possible.
 205 </DD>
 206
 207 <DT><B>-drop-bounds</B></DT></DT>
 208 <DD>
 209 Make for bounds into temporary variables if they
 210 contain loads, uses of symbols with their addresses
 211 possibly taken, including global variables, or SUIF
 212 intrinsics that might be turned into control-flow,
 213 such as io_max instructions or io_gen macros. The
 214 idea is to make sure it is clear to the back-end C
 215 compiler that the bounds are loop invariant, so
 216 loop optimizations such as software pipelining may
 217 be done.
 218 </DD>
 219
 220 <DT><B>-ll-suffix</B></DT></DT>
 221 <DD>
 222 If the type of an integer constant is ``long long''
 223 use the suffix ``ll'' and if the type is ``unsigned
 224 long long'' use the suffix ``ull'' instead of trying
 225 to cast the constant to the given type. This
 226 is an extension to the ANSI ``l'' and ``ul'' suffixes
 227 on integer constants. Since ``long long''
 228 types are not part of the ANSI C standard, the
 229 standard says nothing of suffixes for integer constants
 230 to get these types. This is left as an
 231 optional switch because some implementations that
 232 accept ``long long'' might not accept these two new
 233 suffixes. The idea is to keep the default behavior
 234 as portable as possible.
 235 </DD>
 236
 237 <DT><B>-explicit-zero-init</B></DT></DT>
 238 <DD>
 239 Make all initializations to zero explicit. Normally,
 240 static data that is initiailized to zero is
 241 given no explicit initialization unless it's the
 242 initialization of a structure or array with nonzero
 243 initializers to come, in which case some zero
 244 initializers are needed to position the non-zero
 245 initializers properly. This takes advantage of the
 246 fact that ANSI C guarantees all static data is
 247 implicitly initialized to zero if there is no
 248 explicit initialization. This flag overrides that
 249 feature to force explicit initialization even when
 250 the data is zero. This flag may be useful under
 251 some circumstances when using a Solaris C compiler
 252 as a back-end compiler, because the Solaris compiler
 253 reportedly puts explicitly and implicitly
 254 initialized data in different segments. This
 255 causes the source code to bison to break because
 256 bison redefines optind, which is also in libc, and
 257 which segment optind is in determines which version
 258 of optind the linker tries to use.
 259 </DD>
 260
 261 <DT><B>-limit-escape-sequences</B></DT></DT>
 262 <DD>
 263 Do not produce simple alphabetic escape sequences
 264 other than \n in string constants or string literals.
 265 That is, no \a, \b, \f, \r, \t, or \v.
 266 Instead, other representations, such as \007, are
 267 used. This is a work-around for some back-end compilers
 268 that don't recognize all the ANSI C required
 269 alphabetic escape sequences. The DEC OSF 3.2 cc
 270 compiler, for example, doesn't recognize \a.
 271 </DD>
 272
 273 <DT><B>-fill-field-space-with-char-arrays</B></DT></DT>
 274 <DD>
 275 Use character arrays to pad structures instead of
 276 bit fields, when possible. This is a work-around
 277 for back-end compilers that lay out bit fields differently.
 278 </DD>
 279 </DL>
 280
 281 <H2><A NAME="sect4" HREF="#toc4"><B>Annotations</B></A></H2>
 282
 283 <P>
 284 The <I>s2c</I> program reserves all annotations names beginning
 285 with the prefix ``s2c `' for its own use. Some annotations
 286 it uses internally, and some are recognized on input
 287 files and may be used to affect the behavior of <I>s2c.</I> The
 288 following are the annotations <I>s2c</I> recognizes on its input.
 289 <P>
 290 <B>``s2c</B> <B>comments''</B><BR>
 291
 292 This annotation is used to specify comments to be
 293 inserted into the C code. Its data should be a
 294 list of any number of strings, each of which is
 295 interpreted as a separate comment. Each comment
 296 should consist of all the text between the ``/*''
 297 and ``*/'' markers. Comments can be put on SUIF
 298 ``mark'' instructions, in which case they will be
 299 put on lines of their own, or they may be put on
 300 any other SUIF object and they will be put in the C
 301 code near the C code that most directly results
 302 from that SUIF object.
 303 <P>
 304 <B>``s2c</B> <B>pragma''</B><BR>
 305
 306 This annotation is used to specify pragmas to be
 307 inserted into the C code. <I>s2c</I> looks for this annotation
 308 on file_set_entries, symbol tables, and
 309 io_mrk instructions. There may be multiple pragma
 310 annotations on an object. Each such annotation
 311 generates one pragma line in the output.
 312 <P>
 313 The exact form of the output line is the string
 314 ``#pragma'' followed by a space followed by the
 315 printed representations of the immeds in the annotation,
 316 separated by a space if there are multiple
 317 immeds. Strings are printed without extra quotes
 318 around them or any other interpretation, so a
 319 pragma annotation with a single string immed as its
 320 data allows the form of the pragma line to be specified
 321 exactly. All other immeds are printed in
 322 natural ways.
 323 <P>
 324 An example of the use of this annotation would be
 325 with a global symbol table containing an annotation
 326 of
 327 <P>
 328 pragma": \x01no side effects\x02 &lt;sqrt,0&gt;]
 329 <P>
 330 which would give this output line:
 331 <P>
 332 <B>``s2c</B> <B>preamble</B> <B>pragma''</B><BR>
 333
 334 This annotation is is just like the ``s2c pragma''
 335 annotation except that it only has an effect when
 336 it is placed on the global symbol table and the
 337 pragmas for this annotation are printed before the
 338 declarations for the global symbol table instead of
 339 after those declarations.
 340 <P>
 341 <B>``s2c</B> <B>pound</B> <B>line''</B><BR>
 342
 343 This annotation provides a general way to insert
 344 pre-processing directives into the C code. They
 345 are similar to ``s2c pragma'' annotation except
 346 that instead of beginning with ``#pragma'' and a
 347 space, the lines in the C code begin with only
 348 ``#'' and no space, followed directly by the
 349 immeds.    This allows ``#define'', ``#ifdef'',
 350 ``#line'', or any other pre-processing directives
 351 at all to be inserted into the code. Whoever creates
 352 these annotations is of course responsible for
 353 insuring that they are valid pre-processing directives
 354 and that they interact properly with whatever
 355 else <I>s2c</I> puts in the C file.
 356 <P>
 357 An example of the use of this annotation would be
 358 with an io_mrk instruction containing an annotation
 359 of
 360 <P>
 361 pound line": \x01line\x02 37 \x01\"file.c\""]
 362 <P>
 363 which would give this output line:
 364 <P>
 365 <B>``s2c</B> <B>genop</B> <B>format''</B><BR>
 366
 367 This annotation may be used on the global symbol
 368 table to specify the way that SUIF ``io_genop''
 369 instructions    will be written.    Note that
 370 ``io_genop'' instructions cannot in general be
 371 translated to valid C code, so this annotation is
 372 useful only with the <I>-pseudo</I> command-line option.
 373 In that case, <I>s2c</I> functions to make the SUIF code
 374 easy to read for a human. To that end, this annotation
 375 allows flexibility in the way ``io_genop''
 376 instructions are written.
 377 <P>
 378 There are two forms that are recognized for the
 379 data of this annotation. The first is two strings.
 380 The first string specifies the name of a ``genop''
 381 and the other is a format string for printing the
 382 ``genop''. The other form for the data is a
 383 string, then an integer, then another string. In
 384 this case the first and last string have the same
 385 meanings as before, but the integer specifies the
 386 number of arguments, and only ``genop''s with that
 387 number of arguments use that format string.
 388 <P>
 389 For each ``genop'' to be printed, if there is a
 390 format annotation specifying the right number of
 391 arguments, that is used. Otherwise, if there is a
 392 format annotations not specifying anything about
 393 arguments, that is used. If neither of these cases
 394 apply, the default method of printing ``genop''
 395 instructions is used: they are printed as function
 396 calls with the name of the ``genop'' as the function
 397 name.
 398 <P>
 399 Each format string is interpreted as follows. The
 400 ``%'' character is used as an escape in the format
 401 string -- other characters are generally printed
 402 directly. The following escape sequences are recognized:
 403
 404 <DL>
 405
 406 <DT>* %% </DT></DT>
 407 <DD>        -- print one ``%'' character
 408 </DD>
 409
 410 <DT>* %a </DT></DT>
 411 <DD>        -- print one of the arguments
 412 * %n <I>text</I> %m -- print all remaining unmatched
 413 arguments,
 414 separated by <I>text</I> if there is
 415 more than
 416 one, or nothing if there are
 417 no unmatched
 418 arguments
 419 </DD>
 420 </DL>
 421 <P>
 422 Note that there can be any number of ``%a'' directives,
 423 possibly before and after the ``%n'' directive,
 424 but there may only be one ``%n'' directive.
 425 Arguments to all ``%a'' directives are matched
 426 first, either from the beginning of the argument
 427 list for those preceeding a ``%n'' directive or
 428 from the end for those coming after one. It is an
 429 error for there to be too few arguments to match
 430 all ``%a'' directives, but it is not an error to
 431 have too many arguments.
 432 <P>
 433 Within a ``%n'' directive, the <I>text</I> string may
 434 include ``%%'', which translates to one ``%'', but
 435 no other occurances of ``%''.
 436 <P>
 437 Note that the default format if nothing else is
 438 given is equivalent to ``&lt;name&gt;(%n, %)'' if there
 439 are any arguments or ``&lt;name&gt;'' if there are no
 440 arguments, where &lt;name&gt; is the name of the generic
 441 instruction.
 442
 443 <DL>
 444
 445 <DT>EXAMPLES:</DT></DT>
 446 <DD>
 447 </DD>
 448
 449 <DT>Format </DT></DT>
 450 <DD>                   output
 451 </DD>
 452
 453 <DT>\x01fun(%n, %)\x02 </DT></DT>
 454 <DD>\x01fun()\x02 \x01<A HREF="man_fun.op1.html">fun(op1)</A>
 455 \x02 \x01fun(op1, op2)"
 456 \x01fun(op1, op2, op3)"
 457 </DD>
 458
 459 <DT>\x01fun()\x02 </DT></DT>
 460 <DD>       \x01fun()\x02 \x01fun()\x02    \x01fun()"
 461 \x01fun()"
 462 \x01{%a: %n, %m}\x02 &lt;error&gt; \x01{op1: }\x02 \x01{op1: op2}"
 463 \x01{op1: op2, op3}"
 464 </DD>
 465
 466 <DT>\x01%a ? %a : %a\x02 &lt;error&gt; &lt;error&gt; </DT></DT>
 467 <DD>   &lt;error&gt;
 468 \x01op1 ? op2 : op3"
 469 </DD>
 470 </DL>
 471
 472 <H2><A NAME="sect5" HREF="#toc5"><B>See</B> <B>Also</B></A></H2>
 473
 474 <P>
 475 <A HREF="man_snoot.1.html">snoot(1)</A>
 476
 477
 478 <H2><A NAME="sect6" HREF="#toc6"><B>History</B></A></H2>
 479
 480 <P>
 481 Robert French wrote an <I>s2c</I> program for an earlier version
 482 of the SUIF system. Due primarily to limitations of the
 483 SUIF format of that time, the output of the early version
 484 wasn't quite correct C code, but instead provided a useful
 485 way to format a SUIF file for easy reading. Todd Smith
 486 updated portions of the code to compensate for drastic
 487 changes in the SUIF system. Chris Wilson made more
 488 updates and rewrote parts of the program to produce correct
 489 C output.
 490 <P>
 491
 492 <HR><P>
 493 <A NAME="toc"><B>Table of Contents</B></A><P>
 494 <UL>
 495 <LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
 496 <LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
 497 <LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
 498 <LI><A NAME="toc3" HREF="#sect3">Options</A></LI>
 499 <LI><A NAME="toc4" HREF="#sect4">Annotations</A></LI>
 500 <LI><A NAME="toc5" HREF="#sect5">See Also</A></LI>
 501 <LI><A NAME="toc6" HREF="#sect6">History</A></LI>
 502 </UL>
 503 </BODY></HTML>