libmach.html 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910
  1. <html>
  2. <title>
  3. data
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>Adding Application Support for a New Architecture in Plan 9
  7. </H1>
  8. <DL><DD><I>Bob Flandrena<br>
  9. bobf@plan9.bell-labs.com<br>
  10. </I></DL>
  11. <H4>Introduction
  12. </H4>
  13. <br>&#32;<br>
  14. Plan 9 has five classes of architecture-dependent software:
  15. headers, kernels, compilers and loaders, the
  16. <TT>libc</TT>
  17. system library, and a few application programs. In general,
  18. architecture-dependent programs
  19. consist of a portable part shared by all architectures and a
  20. processor-specific portion for each supported architecture.
  21. The portable code is often compiled and stored in a library
  22. associated with
  23. each architecture. A program is built by
  24. compiling the architecture-specific code and loading it with the
  25. library. Support for a new architecture is provided
  26. by building a compiler for the architecture, using it to
  27. compile the portable code into libraries,
  28. writing the architecture-specific code, and
  29. then loading that code with
  30. the libraries.
  31. <br>&#32;<br>
  32. This document describes the organization of the architecture-dependent
  33. code and headers on Plan 9.
  34. The first section briefly discusses the layout of
  35. the headers and the source code for the kernels, compilers, loaders, and the
  36. system library,
  37. <TT>libc</TT>.
  38. The second section provides a detailed
  39. discussion of the structure of
  40. <TT>libmach</TT>,
  41. a library containing almost
  42. all architecture-dependent code
  43. used by application programs.
  44. The final section describes the steps required to add
  45. application program support for a new architecture.
  46. <H4>Directory Structure
  47. </H4>
  48. <P>
  49. Architecture-dependent information for the new processor
  50. is stored in the directory tree rooted at <TT>/</TT><I>m</I>
  51. where
  52. <I>m</I>
  53. is the name of the new architecture (e.g.,
  54. <TT>mips</TT>).
  55. The new directory should be initialized with several important
  56. subdirectories, notably
  57. <TT>bin</TT>,
  58. <TT>include</TT>,
  59. and
  60. <TT>lib</TT>.
  61. The directory tree of an existing architecture
  62. serves as a good model for the new tree.
  63. The architecture-dependent
  64. <TT>mkfile</TT>
  65. must be stored in the newly created root directory
  66. for the architecture. It is easiest to copy the
  67. mkfile for an existing architecture and modify
  68. it for the new architecture. When the mkfile
  69. is correct, change the
  70. <TT>OS</TT>
  71. and
  72. <TT>CPUS</TT>
  73. variables in the
  74. <TT>/sys/src/mkfile.proto</TT>
  75. to reflect the addition of the new architecture.
  76. </P>
  77. <H4>Headers
  78. </H4>
  79. <br>&#32;<br>
  80. Architecture-dependent headers are stored in directory
  81. <TT>/&lt;I&gt;m&lt;/I&gt;/include</TT>
  82. where
  83. <I>m</I>
  84. is the name of the architecture (e.g.,
  85. <TT>mips</TT>).
  86. Two header files are required:
  87. <TT>u.h</TT>
  88. and
  89. <TT>ureg.h</TT>.
  90. The first defines fundamental data types,
  91. bit settings for the floating point
  92. status and control registers, and
  93. <TT>va_list</TT>
  94. processing which depends on the stack
  95. model for the architecture. This file
  96. is best built by copying and modifying the
  97. <TT>u.h</TT>
  98. file from an architecture
  99. with a similar stack model.
  100. The
  101. <TT>ureg.h</TT>
  102. file
  103. contains a structure describing the layout
  104. of the saved register set for
  105. the architecture; it is defined by the kernel.
  106. <br>&#32;<br>
  107. Header file
  108. <TT>/sys/include/a.out.h</TT>
  109. contains the definitions of the magic
  110. numbers used to identify executables for
  111. each architecture. When support for a new
  112. architecture is added, the magic number
  113. for the architecture must be added to this file.
  114. <br>&#32;<br>
  115. The header format of a bootable executable is defined by
  116. each manufacturer. Header file
  117. <TT>/sys/include/bootexec.h</TT>
  118. contains structures describing the headers currently
  119. supported. If the new architecture uses a common header
  120. such as COFF,
  121. the header format is probably already defined,
  122. but if the bootable header format is non-standard,
  123. a structure defining the format must be added to this file.
  124. <br>&#32;<br>
  125. <H4>Kernel
  126. </H4>
  127. <br>&#32;<br>
  128. Although the kernel depends critically on the properties of the underlying
  129. hardware, most of the
  130. higher-level kernel functions, including process
  131. management, paging, pseudo-devices, and some
  132. networking code, are independent of processor
  133. architecture. The portable kernel code
  134. is divided into two parts: that implementing kernel
  135. functions and that devoted to the boot process.
  136. Code in the first class is stored in directory
  137. <TT>/sys/src/9/port</TT>
  138. and the portable boot code is stored in
  139. <TT>/sys/src/9/boot</TT>.
  140. Architecture-dependent kernel code is stored in the
  141. subdirectories of
  142. <TT>/sys/src/9</TT>
  143. named for each architecture.
  144. <br>&#32;<br>
  145. The relationship between the kernel code and the boot code
  146. is convoluted and subtle. The portable boot code
  147. is compiled into a library for each architecture. An architecture-specific
  148. main program is loaded with the appropriate library and the resulting
  149. executable is compiled into the kernel where it is executed as
  150. a user process during the final stages of kernel initialization. The boot process
  151. performs authentication, attaches the name space root to the appropriate
  152. file system and starts the
  153. <TT>init</TT>
  154. process.
  155. <br>&#32;<br>
  156. The organization of the portable kernel source code differs from that
  157. of most other architecture-specific code.
  158. Instead of storing the portable code in a library
  159. and loading it with the architecture-specific
  160. code, the portable code is compiled directly into
  161. the directory containing the architecture-specific code
  162. and linked with the object files built from the source in that directory.
  163. <br>&#32;<br>
  164. <H4>Compilers and Loaders
  165. </H4>
  166. <br>&#32;<br>
  167. The compiler source code conforms to the usual
  168. organization: portable code is compiled into a library
  169. for each architecture
  170. and the architecture-dependent code is loaded with
  171. that library.
  172. The common compiler code is stored in
  173. <TT>/sys/src/cmd/cc</TT>.
  174. The
  175. <TT>mkfile</TT>
  176. in this directory compiles the portable source and
  177. archives the objects in a library for each architecture.
  178. The architecture-specific compiler source
  179. is stored in a subdirectory of
  180. <TT>/sys/src/cmd</TT>
  181. with the same name as the compiler (e.g.,
  182. <TT>/sys/src/cmd/vc</TT>).
  183. <br>&#32;<br>
  184. There is no portable code shared by the loaders.
  185. Each directory of loader source
  186. code is self-contained, except for
  187. a header file and an instruction name table
  188. included from the
  189. directory of the associated
  190. compiler.
  191. <br>&#32;<br>
  192. <H4>Libraries
  193. </H4>
  194. <br>&#32;<br>
  195. Most C library modules are
  196. portable; the source code is stored in
  197. directories
  198. <TT>/sys/src/libc/port</TT>
  199. and
  200. <TT>/sys/src/libc/9sys</TT>.
  201. Architecture-dependent library code
  202. is stored in the subdirectory of
  203. <TT>/sys/src/libc</TT>
  204. named the same as the target processor.
  205. Non-portable functions not only
  206. implement architecture-dependent operations
  207. but also supply assembly language implementations
  208. of functions where speed is critical.
  209. Directory
  210. <TT>/sys/src/libc/9syscall</TT>
  211. is unusual because it
  212. contains architecture-dependent information
  213. for all architectures.
  214. It holds only a header file defining
  215. the names and numbers of system calls
  216. and a
  217. <TT>mkfile</TT>.
  218. The
  219. <TT>mkfile</TT>
  220. executes an
  221. <TT>rc</TT>
  222. script that parses the header file, constructs
  223. assembler language functions implementing the system
  224. call for each architecture, assembles the code,
  225. and archives the object files in
  226. <TT>libc</TT>.
  227. The assembler language syntax and the system interface
  228. differ for each architecture.
  229. The
  230. <TT>rc</TT>
  231. script in this
  232. <TT>mkfile</TT>
  233. must be modified to support a new architecture.
  234. <br>&#32;<br>
  235. <H4>Applications
  236. </H4>
  237. <br>&#32;<br>
  238. Application programs process two forms of architecture-dependent
  239. information: executable images and intermediate object files.
  240. Almost all processing is on executable files.
  241. System library
  242. <TT>libmach</TT>
  243. provides functions that convert
  244. architecture-specific data
  245. to a portable format so application programs
  246. can process this data independent of its
  247. underlying representation.
  248. Further, when a new architecture is implemented
  249. almost all code changes
  250. are confined to the library;
  251. most affected application programs need only be reloaded.
  252. The source code for the library is stored in
  253. <TT>/sys/src/libmach</TT>.
  254. <br>&#32;<br>
  255. An application program running on one type of
  256. processor must be able to interpret
  257. architecture-dependent information for all
  258. supported processors.
  259. For example, a debugger must be able to debug
  260. the executables of
  261. all architectures, not just the
  262. architecture on which it is executing, since
  263. <TT>/proc</TT>
  264. may be imported from a different machine.
  265. <br>&#32;<br>
  266. A small part of the application library
  267. provides functions to
  268. extract symbol references from object files.
  269. The remainder provides the following processing
  270. of executable files or memory images:
  271. <DL><DD>
  272. <br>&#32;<br>
  273. <DL COMPACT>
  274. <DT>*<DD>
  275. Header interpretation.
  276. <DT>*<DD>
  277. Symbol table interpretation.
  278. <DT>*<DD>
  279. Execution context interpretation, such as stack traces
  280. and stack frame location.
  281. <DT>*<DD>
  282. Instruction interpretation including disassembly and
  283. instruction size and follow-set calculations.
  284. <DT>*<DD>
  285. Exception and floating point number interpretation.
  286. <DT>*<DD>
  287. Architecture-independent read and write access through a
  288. relocation map.
  289. </DL>
  290. </dl>
  291. <br>&#32;<br>
  292. Header file
  293. <TT>/sys/include/mach.h</TT>
  294. defines the interfaces to the
  295. application library. Manual pages
  296. <A href="/magic/man2html/2/mach"><I>mach</I>(2),
  297. </A><A href="/magic/man2html/2/symbol"><I>symbol</I>(2),
  298. </A>and
  299. <A href="/magic/man2html/2/object"><I>object</I>(2)
  300. </A>describe the details of the
  301. library functions.
  302. <br>&#32;<br>
  303. Two data structures, called
  304. <TT>Mach</TT>
  305. and
  306. <TT>Machdata</TT>,
  307. contain architecture-dependent parameters and
  308. a jump table of functions.
  309. Global variables
  310. <TT>mach</TT>
  311. and
  312. <TT>machdata</TT>
  313. point to the
  314. <TT>Mach</TT>
  315. and
  316. <TT>Machdata</TT>
  317. data structures associated with the target architecture.
  318. An application determines the target architecture of
  319. a file or executable image, sets the global pointers
  320. to the data structures associated with that architecture,
  321. and subsequently performs all references indirectly through the
  322. pointers.
  323. As a result, direct references to the tables for each
  324. architecture are avoided and the application code intrinsically
  325. supports all architectures (though only one at a time).
  326. <br>&#32;<br>
  327. Object file processing is handled similarly: architecture-dependent
  328. functions identify and
  329. decode the intermediate files for the processor.
  330. The application indirectly
  331. invokes a classification function to identify
  332. the architecture of the object code and to select the
  333. appropriate decoding function. Subsequent calls
  334. then use that function to decode each record. Again,
  335. the layer of indirection allows the application code
  336. to support all architectures without modification.
  337. <br>&#32;<br>
  338. Splitting the architecture-dependent information
  339. between the
  340. <TT>Mach</TT>
  341. and
  342. <TT>Machdata</TT>
  343. data structures
  344. allows applications to choose
  345. an appropriate level of service. Even though an application
  346. does not directly reference the architecture-specific data structures,
  347. it must load the
  348. architecture-dependent tables and code
  349. for all architectures it supports. The size of this data
  350. can be substantial and many applications do not require
  351. the full range of architecture-dependent functionality.
  352. For example, the
  353. <TT>size</TT>
  354. command does not require the disassemblers for every architecture;
  355. it only needs to decode the header.
  356. The
  357. <TT>Mach</TT>
  358. data structure contains a few architecture-specific parameters
  359. and a description of the processor register set.
  360. The size of the structure
  361. varies with the size of the register
  362. set but is generally small.
  363. The
  364. <TT>Machdata</TT>
  365. data structure contains
  366. a jump table of architecture-dependent functions;
  367. the amount of code and data referenced by this table
  368. is usually large.
  369. <H4>Libmach Source Code Organization
  370. </H4>
  371. <br>&#32;<br>
  372. The
  373. <TT>libmach</TT>
  374. library provides four classes of functionality:
  375. <br>&#32;<br>
  376. <DL COMPACT>
  377. <DT>Header and Symbol Table Decoding - <DD>
  378. Files
  379. <TT>executable.c</TT>
  380. and
  381. <TT>sym.c</TT>
  382. contain code to interpret the header and
  383. symbol tables of
  384. an executable file or executing image.
  385. Function
  386. <TT>crackhdr</TT>
  387. decodes the header,
  388. reformats the
  389. information into an
  390. <TT>Fhdr</TT>
  391. data structure, and points
  392. global variable
  393. <TT>mach</TT>
  394. to the
  395. <TT>Mach</TT>
  396. data structure of the target architecture.
  397. The symbol table processing
  398. uses the data in the
  399. <TT>Fhdr</TT>
  400. structure to decode the symbol table.
  401. A variety of symbol table access functions then support
  402. queries on the reformatted table.
  403. <DT>Debugger Support - <DD>
  404. Files named
  405. <TT>&lt;I&gt;m&lt;/I&gt;.c</TT>,
  406. where
  407. <I>m</I>
  408. is the code letter assigned to the architecture,
  409. contain the initialized
  410. <TT>Mach</TT>
  411. data structure and the definition of the register
  412. set for each architecture.
  413. Architecture-specific debugger support functions and
  414. an initialized
  415. <TT>Machdata</TT>
  416. structure are stored in
  417. files named
  418. <TT>&lt;I&gt;m&lt;/I&gt;db.c</TT>.
  419. Files
  420. <TT>machdata.c</TT>
  421. and
  422. <TT>setmach.c</TT>
  423. contain debugger support functions shared
  424. by multiple architectures.
  425. <DT>Architecture-Independent Access - <DD>
  426. Files
  427. <TT>map.c</TT>,
  428. <TT>access.c</TT>,
  429. and
  430. <TT>swap.c</TT>
  431. provide accesses through a relocation map
  432. to data in an executable file or executing image.
  433. Byte-swapping is performed as needed. Global variables
  434. <TT>mach</TT>
  435. and
  436. <TT>machdata</TT>
  437. must point to the
  438. <TT>Mach</TT>
  439. and
  440. <TT>Machdata</TT>
  441. data structures of the target architecture.
  442. <DT>Object File Interpretation - <DD>
  443. These files contain functions to identify the
  444. target architecture of an
  445. intermediate object file
  446. and extract references to symbols. File
  447. <TT>obj.c</TT>
  448. contains code common to all architectures;
  449. file
  450. <TT>&lt;I&gt;m&lt;/I&gt;obj.c</TT>
  451. contains the architecture-specific source code
  452. for the machine with code character
  453. <I>m</I>.
  454. </dl>
  455. <br>&#32;<br>
  456. The
  457. <TT>Machdata</TT>
  458. data structure is primarily a jump
  459. table of architecture-dependent debugger support
  460. functions. Functions select the
  461. <TT>Machdata</TT>
  462. structure for a target architecture based
  463. on the value of the
  464. <TT>type</TT>
  465. code in the
  466. <TT>Fhdr</TT>
  467. structure or the name of the architecture.
  468. The jump table provides functions to swap bytes, interpret
  469. machine instructions,
  470. perform stack
  471. traces, find stack frames, format floating point
  472. numbers, and decode machine exceptions. Some functions, such as
  473. machine exception decoding, are idiosyncratic and must be
  474. supplied for each architecture. Others depend
  475. on the compiler run-time model and several
  476. architectures may share code common to a model. For
  477. example, many architectures share the code to
  478. process the fixed-frame stack model implemented by
  479. several of the compilers.
  480. Finally, some
  481. functions, such as byte-swapping, provide a general capability and
  482. the jump table need only select an implementation appropriate
  483. to the architecture.
  484. <br>&#32;<br>
  485. <H4>Adding Application Support for a New Architecture
  486. </H4>
  487. <br>&#32;<br>
  488. This section describes the
  489. steps required to add application-level
  490. support for a new architecture.
  491. We assume
  492. the kernel, compilers, loaders and system libraries
  493. for the new architecture are already in place. This
  494. implies that a code-character has been assigned and
  495. that the architecture-specific headers have been
  496. updated.
  497. With the exception of two programs,
  498. application-level changes are confined to header
  499. files and the source code in
  500. <TT>/sys/src/libmach</TT>.
  501. <br>&#32;<br>
  502. <DL COMPACT>
  503. <DT>1.<DD>
  504. Begin by updating the application library
  505. header file in
  506. <TT>/sys/include/mach.h</TT>.
  507. Add the following symbolic codes to the
  508. <TT>enum</TT>
  509. statement near the beginning of the file:
  510. <DL><DD>
  511. <DT>*<DD>
  512. The processor type code, e.g.,
  513. <TT>MSPARC</TT>.
  514. <DT>*<DD>
  515. The type of the executable. There are usually
  516. two codes needed: one for a bootable
  517. executable (i.e., a kernel) and one for an
  518. application executable.
  519. <DT>*<DD>
  520. The disassembler type code. Add one entry for
  521. each supported disassembler for the architecture.
  522. <DT>*<DD>
  523. A symbolic code for the object file.
  524. </DL>
  525. </dl>
  526. <br>&#32;<br>
  527. <DL COMPACT>
  528. <DT>2.<DD>
  529. In a file name
  530. <TT>/sys/src/libmach/&lt;I&gt;m&lt;/I&gt;.c</TT>
  531. (where
  532. <I>m</I>
  533. is the identifier character assigned to the architecture),
  534. initialize
  535. <TT>Reglist</TT>
  536. and
  537. <TT>Mach</TT>
  538. data structures with values defining
  539. the register set and various system parameters.
  540. The source file for a similar architecture
  541. can serve as template.
  542. Most of the fields of the
  543. <TT>Mach</TT>
  544. data structure are obvious
  545. but a few require further explanation.
  546. <DL><DD>
  547. <DT>&lt;TT&gt;kbase&lt;/TT&gt; - <DD>
  548. This field
  549. contains the address of the kernel
  550. <TT>ublock</TT>.
  551. The debuggers
  552. assume the first entry of the kernel
  553. <TT>ublock</TT>
  554. points to the
  555. <TT>Proc</TT>
  556. structure for a kernel thread.
  557. <DT>&lt;TT&gt;ktmask&lt;/TT&gt; - <DD>
  558. This field
  559. is a bit mask used to calculate the kernel text address from
  560. the kernel
  561. <TT>ublock</TT>
  562. address.
  563. The first page of the
  564. kernel text segment is calculated by
  565. ANDing
  566. the negation of this mask with
  567. <TT>kbase</TT>.
  568. <DT>&lt;TT&gt;kspoff&lt;/TT&gt; - <DD>
  569. This field
  570. contains the byte offset in the
  571. <TT>Proc</TT>
  572. data structure to the saved kernel
  573. stack pointer for a suspended kernel thread. This
  574. is the offset to the
  575. <TT>sched.sp</TT>
  576. field of a
  577. <TT>Proc</TT>
  578. table entry.
  579. <DT>&lt;TT&gt;kpcoff&lt;/TT&gt; - <DD>
  580. This field contains the byte offset into the
  581. <TT>Proc</TT>
  582. data structure
  583. of
  584. the program counter of a suspended kernel thread.
  585. This is the offset to
  586. field
  587. <TT>sched.pc</TT>
  588. in that structure.
  589. <DT>&lt;TT&gt;kspdelta&lt;/TT&gt; and &lt;TT&gt;kpcdelta&lt;/TT&gt; - <DD>
  590. These fields
  591. contain corrections to be added to
  592. the stack pointer and program counter, respectively,
  593. to properly locate the stack and next
  594. instruction of a kernel thread. These
  595. values bias the saved registers retrieved
  596. from the
  597. <TT>Label</TT>
  598. structure named
  599. <TT>sched</TT>
  600. in the
  601. <TT>Proc</TT>
  602. data structure.
  603. Most architectures require no bias
  604. and these fields contain zeros.
  605. <DT>&lt;TT&gt;scalloff&lt;/TT&gt; - <DD>
  606. This field
  607. contains the byte offset of the
  608. <TT>scallnr</TT>
  609. field in the
  610. <TT>ublock</TT>
  611. data structure associated with a process.
  612. The
  613. <TT>scallnr</TT>
  614. field contains the number of the
  615. last system call executed by the process.
  616. The location of the field varies depending on
  617. the size of the floating point register set
  618. which precedes it in the
  619. <TT>ublock</TT>.
  620. </DL>
  621. </dl>
  622. <br>&#32;<br>
  623. <DL COMPACT>
  624. <DT>3.<DD>
  625. Add an entry to the initialization of the
  626. <TT>ExecTable</TT>
  627. data structure at the beginning of file
  628. <TT>/sys/src/libmach/executable.c</TT>.
  629. Most architectures
  630. require two entries: one for
  631. a normal executable and
  632. one for a bootable
  633. image. Each table entry contains:
  634. <DL><DD>
  635. <DT>*<DD>
  636. Magic Number -
  637. The big-endian magic number assigned to the architecture in
  638. <TT>/sys/include/a.out.h</TT>.
  639. <DT>*<DD>
  640. Name -
  641. A string describing the executable.
  642. <DT>*<DD>
  643. Executable type code -
  644. The executable code assigned in
  645. <TT>/sys/include/mach.h</TT>.
  646. <DT>*<DD>
  647. <TT>Mach</TT> pointer -
  648. The address of the initialized
  649. <TT>Mach</TT>
  650. data structure constructed in Step 2.
  651. You must also add the name of this table to the
  652. list of
  653. <TT>Mach</TT>
  654. table definitions immediately preceding the
  655. <TT>ExecTable</TT>
  656. initialization.
  657. <DT>*<DD>
  658. Header size -
  659. The number of bytes in the executable file header.
  660. The size of a normal executable header is always
  661. <TT>sizeof(Exec)</TT>.
  662. The size of a bootable header is
  663. determined by the size of the structure
  664. for the architecture defined in
  665. <TT>/sys/include/bootexec.h</TT>.
  666. <DT>*<DD>
  667. Byte-swapping function -
  668. The address of
  669. <TT>beswal</TT>
  670. or
  671. <TT>leswal</TT>
  672. for big-endian and little-endian
  673. architectures, respectively.
  674. <DT>*<DD>
  675. Decoder function -
  676. The address of a function to decode the header.
  677. Function
  678. <TT>adotout</TT>
  679. decodes the common header shared by all normal
  680. (i.e., non-bootable) executable files.
  681. The header format of bootable
  682. executable files is defined by the manufacturer and
  683. a custom function is almost always
  684. required to decode it.
  685. Header file
  686. <TT>/sys/include/bootexec.h</TT>
  687. contains data structures defining the bootable
  688. headers for all architectures. If the new architecture
  689. uses an existing format, the appropriate
  690. decoding function should already be in
  691. <TT>executable.c</TT>.
  692. If the header format is unique, then
  693. a new function must be added to this file.
  694. Usually the decoding function for an existing
  695. architecture can be adopted with minor modifications.
  696. </DL>
  697. </dl>
  698. <br>&#32;<br>
  699. <DL COMPACT>
  700. <DT>4.<DD>
  701. Write an object file parser and
  702. store it in file
  703. <TT>/sys/src/libmach/&lt;I&gt;m&lt;/I&gt;obj.c</TT>
  704. where
  705. <I>m</I>
  706. is the identifier character assigned to the architecture.
  707. Two functions are required: a predicate to identify an
  708. object file for the architecture and a function to extract
  709. symbol references from the object code.
  710. The object code format is obscure but
  711. it is often possible to adopt the
  712. code of an existing architecture
  713. with minor modifications.
  714. When these
  715. functions are in hand, insert their addresses
  716. in the jump table at the beginning of file
  717. <TT>/sys/src/libmach/obj.c</TT>.
  718. </dl>
  719. <br>&#32;<br>
  720. <DL COMPACT>
  721. <DT>5.<DD>
  722. Implement the required debugger support functions and
  723. initialize the parameters and jump table of the
  724. <TT>Machdata</TT>
  725. data structure for the architecture.
  726. This code is conventionally stored in
  727. a file named
  728. <TT>/sys/src/libmach/&lt;I&gt;m&lt;/I&gt;db.c</TT>
  729. where
  730. <I>m</I>
  731. is the identifier character assigned to the architecture.
  732. The fields of the
  733. <TT>Machdata</TT>
  734. structure are:
  735. <DL><DD>
  736. <DT>&lt;TT&gt;bpinst&lt;/TT&gt; and &lt;TT&gt;bpsize&lt;/TT&gt; - <DD>
  737. These fields
  738. contain the breakpoint instruction and the size
  739. of the instruction, respectively.
  740. <DT>&lt;TT&gt;swab&lt;/TT&gt; - <DD>
  741. This field
  742. contains the address of a function to
  743. byte-swap a 16-bit value. Choose
  744. <TT>leswab</TT>
  745. or
  746. <TT>beswab</TT>
  747. for little-endian or big-endian architectures, respectively.
  748. <DT>&lt;TT&gt;swal&lt;/TT&gt; - <DD>
  749. This field
  750. contains the address of a function to
  751. byte-swap a 32-bit value. Choose
  752. <TT>leswal</TT>
  753. or
  754. <TT>beswal</TT>
  755. for little-endian or big-endian architectures, respectively.
  756. <DT>&lt;TT&gt;ctrace&lt;/TT&gt; - <DD>
  757. This field
  758. contains the address of a function to perform a
  759. C-language stack trace. Two general trace functions,
  760. <TT>risctrace</TT>
  761. and
  762. <TT>cisctrace</TT>,
  763. traverse fixed-frame and relative-frame stacks,
  764. respectively. If the compiler for the
  765. new architecture conforms to one of
  766. these models, select the appropriate function. If the
  767. stack model is unique,
  768. supply a custom stack trace function.
  769. <DT>&lt;TT&gt;findframe&lt;/TT&gt; - <DD>
  770. This field
  771. contains the address of a function to locate the stack
  772. frame associated with a text address.
  773. Generic functions
  774. <TT>riscframe</TT>
  775. and
  776. <TT>ciscframe</TT>
  777. process fixed-frame and relative-frame stack
  778. models.
  779. <DT>&lt;TT&gt;ufixup&lt;/TT&gt; - <DD>
  780. This field
  781. contains the address of a function to adjust
  782. the base address of the register save area.
  783. Currently, only the
  784. 68020 requires this bias
  785. to offset over the active
  786. exception frame.
  787. <DT>&lt;TT&gt;excep&lt;/TT&gt; - <DD>
  788. This field
  789. contains the address of a function to produce a
  790. text
  791. string describing the
  792. current exception.
  793. Each architecture stores exception
  794. information uniquely, so this code must always be supplied.
  795. <DT>&lt;TT&gt;bpfix&lt;/TT&gt; - <DD>
  796. This field
  797. contains the address of a function to adjust an
  798. address prior to laying down a breakpoint.
  799. <DT>&lt;TT&gt;sftos&lt;/TT&gt; - <DD>
  800. This field
  801. contains the address of a function to convert a single
  802. precision floating point value
  803. to a string. Choose
  804. <TT>leieeesftos</TT>
  805. for little-endian
  806. or
  807. <TT>beieeesftos</TT>
  808. for big-endian architectures.
  809. <DT>&lt;TT&gt;dftos&lt;/TT&gt; - <DD>
  810. This field
  811. contains the address of a function to convert a double
  812. precision floating point value
  813. to a string. Choose
  814. <TT>leieeedftos</TT>
  815. for little-endian
  816. or
  817. <TT>beieeedftos</TT>
  818. for big-endian architectures.
  819. <DT>&lt;TT&gt;foll&lt;/TT&gt;, &lt;TT&gt;das&lt;/TT&gt;, &lt;TT&gt;hexinst&lt;/TT&gt;, and &lt;TT&gt;instsize&lt;/TT&gt; - <DD>
  820. These fields point to functions that interpret machine
  821. instructions.
  822. They rely on disassembly of the instruction
  823. and are unique to each architecture.
  824. <TT>Foll</TT>
  825. calculates the follow set of an instruction.
  826. <TT>Das</TT>
  827. disassembles a machine instruction to assembly language.
  828. <TT>Hexinst</TT>
  829. formats a machine instruction as a text
  830. string of
  831. hexadecimal digits.
  832. <TT>Instsize</TT>
  833. calculates the size in bytes, of an instruction.
  834. Once the disassembler is written, the other functions
  835. can usually be implemented as trivial extensions of it.
  836. </dl>
  837. <br>&#32;<br>
  838. It is possible to provide support for a new architecture
  839. incrementally by filling the jump table entries
  840. of the
  841. <TT>Machdata</TT>
  842. structure as code is written. In general, if
  843. a jump table entry contains a zero, application
  844. programs requiring that function will issue an
  845. error message instead of attempting to
  846. call the function. For example,
  847. the
  848. <TT>foll</TT>,
  849. <TT>das</TT>,
  850. <TT>hexinst</TT>,
  851. and
  852. <TT>instsize</TT>
  853. jump table slots can be zeroed until a
  854. disassembler is written.
  855. Other capabilities, such as
  856. stack trace or variable inspection,
  857. can be supplied and will be available to
  858. the debuggers but attempts to use the
  859. disassembler will result in an error message.
  860. </DL>
  861. <DL COMPACT>
  862. <DT>6.<DD>
  863. Update the table named
  864. <TT>machines</TT>
  865. near the beginning of
  866. <TT>/sys/src/libmach/setmach.c</TT>.
  867. This table binds the
  868. file type code and machine name to the
  869. <TT>Mach</TT>
  870. and
  871. <TT>Machdata</TT>
  872. structures of an architecture.
  873. The names of the initialized
  874. <TT>Mach</TT>
  875. and
  876. <TT>Machdata</TT>
  877. structures built in steps 2 and 5
  878. must be added to the list of
  879. structure definitions immediately
  880. preceding the table initialization.
  881. If both Plan 9 and
  882. native disassembly are supported, add
  883. an entry for each disassembler to the table. The
  884. entry for the default disassembler (usually
  885. Plan 9) must be first.
  886. <DT>7.<DD>
  887. Add an entry describing the architecture to
  888. the table named
  889. <TT>trans</TT>
  890. near the end of
  891. <TT>/sys/src/cmd/prof.c</TT>.
  892. </DL>
  893. <DT>8.<DD>
  894. Add an entry describing the architecture to
  895. the table named
  896. <TT>objtype</TT>
  897. near the start of
  898. <TT>/sys/src/cmd/pcc.c</TT>.
  899. </DL>
  900. <DT>9.<DD>
  901. Recompile and install
  902. all application programs that include header file
  903. <TT>mach.h</TT>
  904. and load with
  905. <TT>libmach.a</TT>.
  906. </dl>
  907. <br>&#32;<br>
  908. <A href=http://www.lucent.com/copyright.html>
  909. Copyright</A> &#169; 2002 Lucent Technologies Inc. All rights reserved.
  910. </body></html>