1
0

libmach.ms 24 KB

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