............................Contents


1. SBus Cards and FCode	1
..FCode PROM Format	2
..Interpreting FCode	2
..Device Identification	2
..Creating and Executing FCode Definitions	3
2. PCI FCode Information	5
..PCI FCode PROM Header Format	5
..The PCI Expansion PROM Header Format	6
..PCI Expansion PROM Data Structure Format	6
..Format of Physical Address in "`reg`" Property	7
..CPU PROM-Generated Properties	8
..Adding a PCI Header to a PROM	10
3. Elements of FCode Programming	11
..Colon Definitions	12
..Stack Operations	13


..Programming Style	14
....Commenting Code	14
..Coding Style	15
....Definition Length	15
....Stack Comments	16
..A Minimal FCode Program	18
..FCode Classes	19
..Primitive FCode Functions	20
..System FCode Functions	21
..Interface FCode Functions	21
..Local FCode Functions	22
4. Debugging and Testing
..FCode Programs	23
..Packaging PCI FCode	23
..System Flags and FCode Debugging	24
..FCode Source	25
..Tokenizing FCode Source	25
..FCode Binary Format	27
..Testing FCode Programs on the Target Machine	27
..Configuring the Target Machine	28
....Setting Appropriate Configuration Parameters	28
....Modifying the Expansion Bus Probe Sequence	29
....Getting to the Forth Monitor	30
..Using the Command Line Editor of the Forth Monitor	30


..Using the Forth Monitor to Test FCode Programs	30
....Using `dload` to Load from Ethernet	31
....Using `dlbin` to Load From Serial Port A	32
....Using `boot` to Load From Hard Disk, Diskette, or Ethernet	32
..Using `dl` to Load Forth Over Serial Port A	33
..Using the Forth Monitor to Interpret an FCode Program	34
..Using the Forth Monitor to Browse a Device Node	36
..Using the Forth Monitor to Test a Device Driver	38
....Device Node Methods	38
........Using `select-dev`	38
........Using `begin-select-dev`	40
........Using `execute-device-method`	41
........Using `apply`	42
..Testing FCode Programs in Source Form	42
..Producing an FCode PROM	42
..Exercising an Installed FCode PROM	43
..`select-dev`-Generated Errors	43
5. Helpful Testing and Debugging Hints	45
..Accessing a PCI Device's Configuration Space Registers	45
..Base Address Register Setting	45
..System Cache Line Size	45
..Sun Ultra-30 UPA/PCI-Related Nodes	46
..Finding and Using Physical Addresses	47
..Controlling PCI Slot Probing on an Ultra-30 UPA/PCI System	49


..Using 3.x Tokenizer and 3.x CPU PROMs	50
..PCI Device Configuration Register Access	51
..Boot Software Roles	51
..Enabling Access to a PCI Device's Memory Space Locations .	52
..Expansion FCode PROM	53
..Packaging Error with Ethernet FCode	54
6. Packages	57
..Package Instances	58
....Package Data	61
....Static and Instance-specific Methods	62
....Execution Tokens	63
....Intra-package Calling Methods	63
....Accessing Other Packages	64
....Inter-package Calling Methods	66
....`execute-device-method` and `apply`	69
..Plug-in Device Drivers	70
..Common Package Methods	71
....Basic Methods	71
........open	71
........close	71
....Recommended Methods	72
........reset	72
........selftest	72
..Package Data Definitions	73


..Instance Arguments and Parameters	74
....Package Addresses	76
....Package Mappings	77
....`nvramrc`	77
....Modifying Package Properties	78
..Standard Support Packages	78
....Sun Disk-Label Support Package	79
....TFTP Booting Support Package	80
....Deblocker Support Package	81
7. Properties	83
..Standard FCode Properties	85
....Standard Property Names	86
....Display Device Properties	86
....Network Device Properties	87
....Memory Device Properties	87
....General Properties For Parent Nodes	87
....Properties For PCI Parent Nodes	88
....Properties for PCI Child Nodes	88
..Detailed Descriptions of Standard Properties	89
....#address-cells	89
....#size-cells	89
....address	90
....address-bits	90
....alternate-reg	91


....mac-address	100
....max-frame-size	101
....max-latency	101
....min-grant	102
....model	102
....name	102
....page-size	103
....power-consumption	104
....ranges	105
....reg	110
....revision-id	113
....slot-names	113
....status	114
....translations	114
....vendor-id	115
....width	115
..Manipulating Properties	115
....Property Creation and Modification	115
....Property Values	115
....Property Encoding	116
....Property Retrieval	116
....Property Decoding	117
..Property-Specific FCodes	118
8. Block and Byte Devices	121


..Block Devices	121
..Byte Devices	122
..Required Methods	122
....`block-size` ( -- block-len )	122
....`load` ( addr -- size )	122
....m`ax-transfer` ( -- max-len )	123
....`read` ( addr len -- actual )	123
....`read-blocks` ( addr block# #blocks -- #read )	123
....`seek` ( poslow poshigh -- status ) for block; ( offset file# -- error?
.......) for byte	123
....`write` ( addr len -- actual )	124
....`write-blocks` ( addr block# #blocks -- #written )	124
..Required Properties	125
..Device Driver Examples	125
....Simple Block Device Driver	126
....Extended Block Device Driver	126
....Complete Block and Byte Device Driver	134
9. Display Devices	145
..Required Methods	145
..Required Properties	146
..Device Driver Examples	146
....Simple Display Device Driver	146
....Extended Display Device Driver	147
..Complete Display Device Drive	151


10. Memory-Mapped Buses	157
..Required Methods	157
.....`decode-unit` ( addr len -- phys.lo ... phys.hi )	157
.....`dma-alloc` ( size -- virt )	158
.....`dma-free` ( virt size -- )	158
.....`dma-map-in` ( virt size cacheable? -- devaddr )	159
.....`dma-map-out` ( virt devaddr size -- )	159
.....`dma-sync` ( virt devaddr size -- )	160
.....`probe-self` ( arg-addr arg-len reg-addr reg-len fcode-addr
........fcode-len -- )	160
.....`map-in` ( phys.lo ... phys.hi size -- virt )	161
.....`map-out` ( virt size -- )	161
..SBus Addressing	161
..SBus Required Properties	162
..Device Driver Examples	162
.....Basic Hierarchical Device Driver	163
.....Extended Hierarchical Device Driver	165
.....Complete Hierarchical Device Driver	173
11. Network Devices	191
..Required Methods	192
.....`load` ( addr -- len )	192
.....`read` ( addr len -- actual )	193
.....`write` ( addr len -- actual )	193
..Required Device Properties	193


..Optional Device Properties	193
..Device Driver Examples	194
.....Simple Network Device Example	194
.....Sample Driver With Test and Debugging Methods	196
.....Bootable Network Device Driver Example	209
12. Serial Devices	237
..Required Methods	237
.....`install-abort` ( -- )	237
.....`read` ( addr len -- actual )	237
.....`remove-abort` ( -- )	238
.....`write` ( addr len -- actual )	238
..Required Properties	238
..Device Driver Examples	238
..Simple Serial FCode Program	239
.....Extended Serial FCode Program	239
.....Complete Serial FCode Program	241
13. PCI FCode Driver Example	247
14. FCode Dictionary	255
A. FCode Reference	399
..FCode Primitives	399
..FCodes by Function	399
..FCodes by Byte Value	424
..FCodes by Name	440
B. FCode Memory Allocation	457


C. Coding Style	459
..Typographic Conventions	459
..Use of Spaces	459
..`if...then...else`	460
..`do...loop`	461
..`begin...while...repeat`	461
..`begin...until...again`	462
..Block Comments	462
..Stack Comments	462
..Return Stack Comments	463
..Numbers	463
D. Differences Between FCode 2.x and 3.x	465