libmach.ms 24 KB

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