Sun FCode program User manual

PDF

Dokument

Annonce

SunSoft, Inc.

A Sun Microsystems, Inc. Business

2550 Garcia Avenue

Mountain View, CA 94043

U.S.A.

Part No: 802-6287-10

Revision A, November 1997

Writing FCode 3.x Programs

Please

Recycle

This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.

Portions of this product may be derived from the UNIX

system, licensed from Novell, Inc., and from the Berkeley BSD system, licensed from the University of California. UNIX is a registered trademark in the United States and other countries and is exclusively licensed by X/Open Company Ltd. Third-party software, including font technology in this product, is protected by copyright and licensed from Sun’s suppliers.

RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227-

14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-3(a).

Sun, Sun Microsystems, the Sun logo, SunSoft, SunDocs, SunExpress, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the United States and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK

and Sun™ Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees.

Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

Contents

1. SBus Cards and FCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode PROM Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Interpreting FCode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Device Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating and Executing FCode Definitions . . . . . . . . . . . . . . . .

2. PCI FCode Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PCI FCode PROM Header Format. . . . . . . . . . . . . . . . . . . . . . . .

The PCI Expansion PROM Header Format . . . . . . . . . . . . . . . .

PCI Expansion PROM Data Structure Format . . . . . . . . . . . . . .

Format of Physical Address in "

reg

" Property . . . . . . . . . . . . .

CPU PROM-Generated Properties. . . . . . . . . . . . . . . . . . . . . . . .

Adding a PCI Header to a PROM . . . . . . . . . . . . . . . . . . . . . . . .

3. Elements of FCode Programming . . . . . . . . . . . . . . . . . . . . . . .

Colon Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stack Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13 iii

Programming Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Commenting Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Coding Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Definition Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stack Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A Minimal FCode Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Primitive FCode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System FCode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Interface FCode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Local FCode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4. Debugging and Testing

FCode Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Packaging PCI FCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

System Flags and FCode Debugging. . . . . . . . . . . . . . . . . . . . . .

FCode Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Tokenizing FCode Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode Binary Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Testing FCode Programs on the Target Machine . . . . . . . . . . . .

Configuring the Target Machine . . . . . . . . . . . . . . . . . . . . . . . . .

Setting Appropriate Configuration Parameters . . . . . . . . . .

Modifying the Expansion Bus Probe Sequence . . . . . . . . . .

Getting to the Forth Monitor . . . . . . . . . . . . . . . . . . . . . . . . .

Using the Command Line Editor of the Forth Monitor . . . . . .

Writing FCode 3.x Programs —November 1997

Using the Forth Monitor to Test FCode Programs . . . . . . . . . . .

Using

dload

to Load from Ethernet . . . . . . . . . . . . . . . . . . .

Using

dlbin

to Load From Serial Port A . . . . . . . . . . . . . . .

Using

boot

to Load From Hard Disk, Diskette, or Ethernet 32

Using

dl

to Load Forth Over Serial Port A . . . . . . . . . . . . . . . .

Using the Forth Monitor to Interpret an FCode Program . . . . .

Using the Forth Monitor to Browse a Device Node. . . . . . . . . .

Using the Forth Monitor to Test a Device Driver. . . . . . . . . . . .

Device Node Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using

select-dev

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using

begin-select-dev

. . . . . . . . . . . . . . . . . . . . .

Using

execute-device-method

. . . . . . . . . . . . . . .

Using

apply

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Testing FCode Programs in Source Form . . . . . . . . . . . . . . . . . .

Producing an FCode PROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Exercising an Installed FCode PROM . . . . . . . . . . . . . . . . . . . . .

select-dev

-Generated Errors . . . . . . . . . . . . . . . . . . . . . . . . . .

5. Helpful Testing and Debugging Hints . . . . . . . . . . . . . . . . . . .

Accessing a PCI Device’s Configuration Space Registers . . . . .

Base Address Register Setting . . . . . . . . . . . . . . . . . . . . . . . . . . .

System Cache Line Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sun Ultra-30 UPA/PCI-Related Nodes . . . . . . . . . . . . . . . . . . . .

Finding and Using Physical Addresses. . . . . . . . . . . . . . . . . . . .

Controlling PCI Slot Probing on an Ultra-30 UPA/PCI System 49

Contents

Using 3.x Tokenizer and 3.x CPU PROMs . . . . . . . . . . . . . . . . .

PCI Device Configuration Register Access . . . . . . . . . . . . . . . . .

Boot Software Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Enabling Access to a PCI Device’s Memory Space Locations .

Expansion FCode PROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Packaging Error with Ethernet FCode. . . . . . . . . . . . . . . . . . . . .

6. Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Package Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Package Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Static and Instance-specific Methods. . . . . . . . . . . . . . . . . . .

Execution Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Intra-package Calling Methods . . . . . . . . . . . . . . . . . . . . . . .

Accessing Other Packages . . . . . . . . . . . . . . . . . . . . . . . . . . .

Inter-package Calling Methods . . . . . . . . . . . . . . . . . . . . . . .

execute-device-method

and

apply

. . . . . . . . . . . . . . . .

Plug-in Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Common Package Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Basic Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

71 open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

71 close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Recommended Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

72 reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

72 selftest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Package Data Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Writing FCode 3.x Programs —November 1997

Instance Arguments and Parameters. . . . . . . . . . . . . . . . . . . . . .

Package Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Package Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

nvramrc

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Modifying Package Properties . . . . . . . . . . . . . . . . . . . . . . . .

Standard Support Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Sun Disk-Label Support Package. . . . . . . . . . . . . . . . . . . . . .

TFTP Booting Support Package . . . . . . . . . . . . . . . . . . . . . . .

Deblocker Support Package . . . . . . . . . . . . . . . . . . . . . . . . . .

7. Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Standard FCode Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Standard Property Names . . . . . . . . . . . . . . . . . . . . . . . . . . .

Display Device Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Network Device Properties . . . . . . . . . . . . . . . . . . . . . . . . . .

Memory Device Properties . . . . . . . . . . . . . . . . . . . . . . . . . . .

General Properties For Parent Nodes . . . . . . . . . . . . . . . . . .

Properties For PCI Parent Nodes . . . . . . . . . . . . . . . . . . . . . .

Properties for PCI Child Nodes . . . . . . . . . . . . . . . . . . . . . . .

Detailed Descriptions of Standard Properties . . . . . . . . . . . . . .

#address-cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

#size-cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

89 address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

90 address-bits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

90 alternate-reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

vii

viii assigned-addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

91 available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

92 big-endian-aperture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

92 bus-range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

93 big-endian-aperture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

93 character-set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

93 class-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

93 compatible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

94 class-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

94 depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

94 device-id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

95 device-id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

95 device_type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

95 devsel-speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

96 existing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

96 fast-back-to-back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

97 has-fcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

97 fast-back-to-back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

97 has-fcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

97 height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

97 interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

98 linebytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

99 little-endian-aperture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

100 local-mac-address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

100

Writing FCode 3.x Programs —November 1997

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

Contents

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

Writing FCode 3.x Programs —November 1997

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

Contents

xii

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

Writing FCode 3.x Programs —November 1997

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

Contents

xiii

xiv Writing FCode 3.x Programs —November 1997

Figures

Figure 6-1 An Instance Chain for

/iommu/sbus/SUNW,cgsix

. . . . . . .

Figure 6-2 An Instance Chain for

/iommu/sbus/ledma/le with obp-tftp

Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figure 8-1 Sample Device Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

125

Figure 11-1 QED Device Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

192 xv

xvi Writing FCode 3.x Programs —November 1997

Tables

Table 4-3

Table 4-4

Table 6-1

Table 6-2

Table 6-3

Table 6-4

Table 6-5

Table 6-6

Table 2-1

Table 2-2

Table 2-3

Table 2-4

Table 3-1

Table 3-2

Table 4-1

Table 4-2

PCI FCode PROM Header Format . . . . . . . . . . . . . . . . . . . . . . .

PCI Expansion PROM Header Format. . . . . . . . . . . . . . . . . . . .

PCI Expansion PROM Data Structure . . . . . . . . . . . . . . . . . . . .

Format of Physical Address in

“reg”

Property . . . . . . . . . . . .

Stack Parameter Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode Source Word Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode Binary Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

FCode Header Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Common Package-related Commands. . . . . . . . . . . . . . . . . . . .

Commands for Browsing the Device Tree . . . . . . . . . . . . . . . . .

Packaage Access FCodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Manipulating phandles

and ihandles

. . . . . . . . . . . . . . . . .

Functions Enabling Calling Other Packages’ Methods . . . . . .

Sun Disk Label Package Methods . . . . . . . . . . . . . . . . . . . . . . . .

TFTP Package Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Deblocker Package Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6 xvii

xviii

Table 7-1

Table 7-2

Table 7-3

Table 7-4

Standard Device Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

interrupts Property Value Encoding. . . . . . . . . . . . . . . . . . . . . .

Child-Parent Address Relationships . . . . . . . . . . . . . . . . . . . . .

106

Child-Parent Address Relationships for a PCI Node in a

PPCRP Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

108

Table 7-5

Table 7-6

Table 8-1

Table 9-1 status Property values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

114

Property-specific FCodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

118

Required Properties of Block and Byte Devices . . . . . . . . . . . .

125

Required Display Device Properties. . . . . . . . . . . . . . . . . . . . . .

146

Table 10-1 SBus Required Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

162

Table 11-1 Required Network Device Properties. . . . . . . . . . . . . . . . . . . . .

193

Table 11-2 Optional Network Device Properties . . . . . . . . . . . . . . . . . . . . .

193

Table 12-1 Serial Driver Required Properties . . . . . . . . . . . . . . . . . . . . . . . .

238

Table 14-1

Table A-1

Table A-2

Table A-3

Table A-4

Table A-5

Table A-6

Table A-7

Escape Sequences in Text Strings . . . . . . . . . . . . . . . . . . . . . . . .

Stack Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Memory Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Atomic Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Data Exception Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Comparison Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Text Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

256

399

400

402

403

404

Table A-8

Table A-9

ASCII Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

405

Numeric Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

405

Table A-10 Numeric Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

405

Table A-11 Numeric Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

406

Table A-12 General-purpose Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

406

Writing FCode 3.x Programs —November 1997

Table A-13 Formatted Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

407

Table A-14 begin

Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

407

Table A-15 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

407

Table A-16 Case Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

408

Table A-17 do

Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

408

Table A-18 Control Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

408

Table A-19 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

409

Table A-20 Defining Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

409

Table A-21 Dictionary Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

410

Table A-22 Dictionary Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

410

Table A-23 Conversion Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

410

Table A-24 64-bit Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

411

Table A-25 Memory Buffers Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

412

Table A-26 Miscellaneous Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

412

Table A-27 Internal Operators (invalid for program text) . . . . . . . . . . . . . .

413

Table A-28 Virtual Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

415

Table A-29 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

415

Table A-30 Commonly-used Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

416

Table A-31 System Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . .

417

Table A-32 Device Activation Vector Setup. . . . . . . . . . . . . . . . . . . . . . . . . .

417

Table A-33 Self-test Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

417

Table A-34 Time Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

417

Table A-35 Machine-specific Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

418

Table A-36 User-set Terminal Emulation Values . . . . . . . . . . . . . . . . . . . . .

418

Table A-37 Terminal-set Terminal Emulation Values . . . . . . . . . . . . . . . . .

418

Tables

xix

Table A-38 Terminal Emulation Routines* . . . . . . . . . . . . . . . . . . . . . . . . . .

418

Table A-39 Frame Buffer Parameter Values* . . . . . . . . . . . . . . . . . . . . . . . . .

419

Table A-40 Font Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

420

Table A-41 One-bit Frame Buffer Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . .

420

Table A-42 eight-bit Frame Buffer Utilities . . . . . . . . . . . . . . . . . . . . . . . . . .

421

Table A-43 Package Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

421

Table A-44 Asynchronous Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423

Table A-45 Miscellaneous Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423

Table A-46 Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423

Table A-47 Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

423

Table A-48 FCodes by Byte Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

424

Table A-49 Tokenizer Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

436

Table A-50 FCodes and Tokenizer Directives by Name . . . . . . . . . . . . . . .

440

Table D-1 FCode Names Changed in Version 3.x. . . . . . . . . . . . . . . . . . . .

465

Table D-2 FCode 2.x Changed Names and

Equivalent FCode 3.x Names. . . . . . . . . . . . . . . . . . . . . . . . . . . .

467

Table D-3

Table D-4

Table D-5

Table D-6

Table D-7

FCode 2.x Commands Deleted in FCode 3.x . . . . . . . . . . . . . . .

467

New FCodes Added in 3.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

468

Differently Functioning 3.x FCodes

With Changed Byte Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

468

3.x FCodes Related to 64-bit Operations . . . . . . . . . . . . . . . . . .

469

Device-related User Interface Commands

Changed in 3.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

470

Writing FCode 3.x Programs —November 1997

Preface

This manual, Writing FCode 3.x Programs (802-6287), describes how to write, debug, and test FCode programs for SPARC-based systems and PCI or SBus interface card devices. It replaces all previous manuals describing how to write

FCode programs. IEEE Standard 1275-1994 is based on the Sun™ OpenBoot™

2.x implementation. OpenBoot 3.x from Sun is compliant with IEEE Standard

1275.

Throughout this book, the reference to FCode PROM might refer to any type of

ROM device (ROM, PROM, FlashPROM, etc.).

Who Should Use This Book

This manual is written for designers of PCI and SBus interface cards and other devices that use the FCode programming language. It is written for those designers who have some familiarity with PCI or SBus card design requirements and Forth programming. The sample code in this book is provided as is without any warranty.

The material in this manual is for developers of FCode applications for PCI or

SBus peripherals on OpenBoot 3.x. With proper programming precautions, these applications should run on OpenBoot 3.x and earlier versions. By following the IEEE 1275 standard, the same FCode application can also run on non-SPARC systems which are IEEE 1275-compliant. The FCode language is defined by IEEE Standard 1275-1994 Standard for Boot Firmware.

xxi

This manual is written for designers who have read and understood the corresponding SBus or PCI specifications and SBus or PCI binding to IEEE

Standard 1275-1994 1.2.

How This Book Is Organized

•

Chapter 1, “SBus Cards and FCode”

, introduces the basic relationships between FCode device drivers and the hardware that they control.

•

Chapter 2, “PCI FCode Information”

, basic information for developers writing FCode for use with PCI.

•

Chapter 3, “Elements of FCode Programming”

, introduces the basic elements of FCode, stack notation, and programming style.

•

Chapter 4, “Debugging and Testing FCode Programs”

, describes the process of producing FCode programs, from source files to testing working programs.

•

Chapter 5, “Helpful Testing and Debugging Hints”

, is information to consider when you are designing FCode code for PCI.

•

Chapter 6, “Packages”

, describes the basic units of FCode program function.

•

Chapter 7, “Properties”

, describes properties, which define how an FCode device driver program recognizes the hardware that it controls.

•

Chapter 8, “Block and Byte Devices”

, describes the required methods for nonvolatile and sequential-access mass storage devices.

•

Chapter 9, “Display Devices”,

describes writing FCode programs for display devices.

•

Chapter 10, “Memory-Mapped Buses”,

describes addressing and required properties for memory-mapped buses.

•

Chapter 11, “Network Devices”,

describes how to implement network device drivers.

•

Chapter 12, “Serial Devices”

, describes programming requirements for serial devices, and gives examples of serial device drivers.

•

Chapter 13, “PCI FCode Driver Example”

, shows a PCI FCode driver which is an example of a way of dealing with PCI-related registers in FCode.

•

Chapter 14, “FCode Dictionary”

, describes currently-defined FCode words and their functions and use, with brief programming examples.

xxii Writing FCode 3.x Programs —November 1997

Related Books

•

Appendix A, “FCode Reference”

, lists all currently-defined FCode words according to functional group, name, and byte value.

•

Appendix B, “FCode Memory Allocation”

, describes guidelines for memory allocation and de-allocation in FCode.

•

Appendix C, “Coding Style”

, contains an OpenBoot coding guideline.

•

Appendix D, “Differences Between FCode 2.x and 3.x”

, discusses the

FCodes and macros that have changed between FCode 2.x and FCode 3.x.

This manual does not cover all you need to know in order to write FCode drivers. The following sources are also useful.

For further information:

•

IEEE Standard 1275-1994 Standard for Boot (Initialization Configuration)

Firmware, Core Requirements and Practices

•

IEEE Standard 1275.1-1994 Standard for Boot (Initialization Configuration)

Firmware: Instruction Set Architecture (ISA) Supplement for IEEE 1754

•

IEEE Standard 1275.2-1994 Standard for Boot (Initialization Configuration)

Firmware: Bus Supplement for IEEE 1496 (SBus)

•

IEEE 1496-1993 Standard for Chip and Module Interconnect Bus:

SBus 1-55937-353-9

•

PCI Local Bus Spedification, rev. 2.1 available from PCI Special Interest group:

800-433-5177/503-797-4207 and http://www.pcisig.com

•

OpenBoot 2.x Command Reference (802-3241)

•

OpenBoot 3.x Command Reference (802-5837)

•

PCI -Bus Binding to IEEE STD 1275-1994 is available at http://playground.sun.com/1275

The on-line version of this manual and FCode tools are available at http://www.sun.com/developers/driver

Preface

xxiii

Forth and Forth Programming

For further information about Forth and Forth programming:

•

Mastering Forth, Anita Anderson and Martin Tracy, Brady Communications

Co., Inc., 1989

•

ANSI Forth X3J14

•

Forth: A Text and Reference, Mahlon G. Kelly and Nicholas Spies. Prentice-

Hall, 1986

•

Starting Forth, Leo Brody. Forth, Inc., second edition, 1987

•

Forth: The New Model, Jack Woehr. M & T Books, 1992

•

Forth Interest Group http://forth.org/fig.html

What Typographic Changes Mean

Typeface or

Symbol Meaning

AaBbCc123

The names of commands, files, and directories; on-screen computer output

Example

Edit your

.login

file.

Use ls -a

to list all files.

system% You have mail.

AaBbCc123

What you type, contrasted with on-screen computer output

AaBbCc123

Variable: replace with a real name or value system% su

Password:

To delete a file, type rm

filename

AaBbCc123

Book titles, new words or terms, or words to be emphasized

[optional] Optional command-line entry

Code samples are included in boxes and may display the following: ok

The OpenBoot Forth Monitor prompt ok

Read Chapter 6 in User’s Guide

These are called class options.

You must be root to do this.

lpr [-Pprinter]

UNIX C shell prompt

UNIX Bourne and Korn shell prompt

Superuser prompt, all shells system% system$ system# xxiv Writing FCode 3.x Programs —November 1997

Ordering Sun Documents

The SunDocs Order Desk is a distribution center for Sun Microsystems technical documentation. You can use major credit cards and company purchase orders. You can order documentation in the following ways:

In the U.S.A.

Call 1-800-247-0250

Outside the U.S.A.

Call 1-801-342-3450

Fax 1-801-373-6798 Fax 1-801-373-6798

World Wide Web:

http://www.sun.com/sundocs/catalog.html

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email or fax your comments to us. Please include the part number of your document in the subject line of your email or fax message.

•

Email: s [email protected]

•

Fax: SMCC Document Feedback

1-415-786-6443

Preface

xxv

xxvi Writing FCode 3.x Programs —November 1997

SBus Cards and FCode

Each SBus card must have a PROM whose contents identify the device and its characteristics.

The SBus card’s PROM may also include an optional software driver that lets you use the card as a boot device or a display device during booting.

In addition to designing hardware, the process of developing SBus devices may include writing, testing, and installing FCode drivers for the device. These drivers, if present, perform three functions:

•

Exercising the device during development, and verifying its functionality

•

Providing the necessary driver to be used by the system boot PROM during power-up

•

Providing device configuration information

In practice, these functions overlap substantially. The same code needed by the system boot PROM usually serves to significantly test the device as well, although additional code may be desired to fully verify proper behavior of the device. The PROM code is used before and during the boot sequence. After the boot sequence finishes, and while not using the OpenBoot Forth Monitor, most

SBus device use is through Solaris drivers.

SBus device PROMs must be written in the FCode programming language, which is similar to ANS Forth. FCode is described in more detail in Chapter 3,

“Elements of FCode Programming”.

FCode PROM Format

An FCode PROM begins at address

in the SBus card’s physical address space. Its size can range from 30 bytes up to 32K bytes. Typical sizes are 60 bytes (for a simple card that identifies itself but does not need a driver) and 5 to 15K bytes (for a card with a boot driver). It is good practice to make FCode boot drivers as short as is practical.

An FCode PROM must be organized as follows:

•

Header (8 bytes: consisting of magic number, version number, length, checksum).

•

Body (FCode program; 0 or more bytes).

•

End Token (either End0, a zero byte, or End1, an alternative all 1s byte).

Interpreting FCode

For each SBus slot, the FCode program is interpreted during bootup as follows:

•

Location 0 of the SBus PROM is read with an 8-bit or 32-bit access. If there is no response (as when there is no card in that slot), the slot is subsequently ignored.

•

If the high-order byte of the value returned from the first access is not the

FCode magic numbers

0xfd

0xf1

, the slot is subsequently ignored.

•

If the high-order byte is

0xfd

0xf1

, the PROM is assumed to contain a valid FCode program. The FCode is then interpreted by starting at location

and reading one byte at a time, executing a procedure associated with each FCode value.

•

Interpretation ceases when the FCode

0x00

0xff

(

End0

End1

) is encountered.

Device Identification

An FCode PROM must identify its device. This identification must include, at a minimum, the device name, used to link the device to its Solaris driver.

Identification information may include additional characteristics of the device for the benefit of the operating system and the CPU boot PROM.

Writing FCode 3.x Programs —November 1997

In most systems, the CPU’s FCode interpreter will store each device’s identification information in a device tree that has a node for each device. Each

device node has a property list that identifies and describes the device. The property list is created as a result of interpreting the program in the FCode

PROM.

Each property must have a name and a value. The name is a string and the value is an array of bytes, which may encode strings, numbers, and various other data types.

See Chapter 7, “Properties” for more information.

Creating and Executing FCode Definitions

Many FCode programs create executable routines, called colon definitions (or

methods) that typically read from and write to device locations to control device functions. These definitions are also stored in the device tree node for that device.

Once defined, these routines may typically be executed under any of the following circumstances:

•

Interactively at the OpenBoot ok

prompt

•

By the OpenBoot system (for using this boot or display system during system start-up)

•

Automatically during FCode interpretation (for power-on initialization or other purposes)

SBus Cards and FCode

4 Writing FCode 3.x Programs —November 1997

PCI FCode Information

This chapter contains basic information for developers writing FCode for use with PCI.

PCI FCode PROM Header Format

The PCI FCode PROM header format is as follows:

Table 2-1

PCI FCode PROM Header Format

Header

a.out

header

Format

32 bytes (needed by some utilities)

PCI expansion PROM header 28 bytes

PCI data structure 24 bytes

FCode (8 Byte FCode header + FCode code bytes)

The a.out

header is required in order to download an FCode image using dload

or boot

on a Solaris™ 1.x (SunOS 4.x) system if, for instance, during test/development of your FCode driver, you don’t want to use a physical

PROM.

If you are dload ing or boot ing your FCode image on a Solaris 2.x system, you must replace the a.out

header by an ELF header.

The fakeboot

utility can add either an a.out

or an ELF header based on parameters that you pass to fakeboot

The PCI Expansion PROM Header Format

The PCI expansion PROM header format (28 bytes) is as follows:

(Values are shown in hexadecimal.)

Table 2-2

PCI Expansion PROM Header Format

Byte Offset

02-03

04-17

18-19

1A-1B

Value

55(h) aa(h)

34 00 (h)

00 00

1c 00

00 00

Description

PROM signature byte one

PROM signature byte two

SPARC reserved value

Reserved for processor architecture-unique data

Pointer to PCI data structure (assuming PCI data structure follows immediately after PCI expansion

PROM Header)

Pad bytes

PCI Expansion PROM Data Structure Format

The PCI expansion PROM data structure (24 bytes) is as follows:

(Values are shown in hexadecimal.)

Table 2-3

PCI Expansion PROM Data Structure

10-11

Byte Offset

00-03

04-05

06-07

08-09

0A-0B

Description /(Hex. value)

Signature : P C I R (50 43 49 52)

Vendor id

Device id

Pointer to Vital Product Data

PCI data structure length (18 00)

PCI data structure revision.

Programming interface code

Subclass code

Class code

Image length in 512 bytes

Writing FCode 3.x Programs —November 1997

Table 2-3

PCI Expansion PROM Data Structure (Continued)

Byte Offset

12-13

16-17

Description /(Hex. value)

Revision level of code/data

Code type (01)

Indicator byte. For last image (80)

Reserved (00 00)

The following is a dump of initial bytes in a PCI FCode PROM with an a.out

header in the first 32 bytes.

Code Example 2-1

PCI FCode PROM Dump

00000

00010

00020

00030

00040

00050

01 03 01 07 00 00 46 98 00 00 00 00 00 00 00 00

00 00 00 00 00 00 40 00 00 00 00 00 00 00 00 00

55 aa 34 00 00 00 00 00 00 00 00 00 00 00 00 00

00 00 00 00 00 00 00 00 1c 00 00 00 50 43 49 52

8e 10 01 10 00 c0 18 00 00 00 00 02 7e 00 00 01

01 80 00 00 f1 03 18 6e 00 00 46 64 xx xx xx xx

For the PROM above, the vendor id is 0x108e, the device id is 0x1001, the pointer to Vital Product Data is 0xc000, class code is 0x02, subclass code is 0, programming interface code is 0, image length (in 512 bytes) is 0x7e, FCode length is 0x4664 bytes, xx..... are FCode data.

Format of Physical Address in "

reg

" Property

For PCI, the " reg

" property value has 5 32-bit numbers phys.hi

, phys.mid

, phys.lo

, size.hi

, size.lo

. The size.hi

and size.lo

are values for a register size of which the address and type are defined by phys.hi

, phys.mid

, and phys.low

PCI FCode Information

The format of the physical address in the “ reg”

property is as follows:

Table 2-4

Format of Physical Address in

“reg”

Property phys.hi cell: phys.mid cell: phys.low cell: npt000ss bbbbbbbb dddddfff rrrrrrrr hhhhhhhh hhhhhhhh hhhhhhhh hhhhhhhh

LLLLLLLL LLLLLLLL LLLLLLLL LLLLLLLL where

•

is 0 if the address is relocatable; 1 otherwise.

•

is 1 if the addressable region is prefetchable; 0 otherwise.

•

is 1 if the address is aliased (for non-relocatable I/O), below 1MByte (for memory), or below 64KBytes (for relocatable I/O).

•

=00 ==> configuration space.

•

=01 ==> I/O space.

•

=10 ==> 32 bit memory space.

•

=11 ==> 64 bit memory space.

•

bbbbbbbb

is an 8-bit bus number (assigned by the CPU PROM at probe time).

•

ddddd

is a 5-bit device number.

•

fff

is a 3-bit function number.

•

rrrrrrrr

is an 8-bit register number.

•

hh..hh

is a 32-bit unsigned number, most significant bits.

•

LL..LL

is a 32-bit unsigned number, least significant bits.

CPU PROM-Generated Properties

This section describes the properties created by the motherboard CPU PROM from the information in the configuration space registers of the PCI device.

The CPU PROM normally generates the following properties in a PCI device node:

•

vendor-id

Writing FCode 3.x Programs —November 1997

•

device-id

•

revision-id

•

class-code

It also generates devsel-speed

from the information from the configuration space registers. The

"interrupts"

property is present if the Interrupt Pin register is non-zero. The following properties are present only if the corresponding capability is available from the device or if the corresponding value was non-zero as indicated in the configuration space registers:

•

66mhz-capable

•

udf-supported

•

cache-line-size

•

fast-back-to-back

•

subsystem-id

•

subsystem-vendor-id

The min-grant

and max-latency

properties are created unless the header type is 01. The CPU PROM also creates the

"assigned-addresses" property, with entries for each address base register for which an address is assigned.

PCI FCode Information

Adding a PCI Header to a PROM

You can see an example in test-pci.fth or add a PCI header using the following example: tokenizer[

\ to add vendor id, device id and class code h# 108e h# 1001 h# 020000 pci-header

\ to add vital product data h# c000 pci-vpd-offset

\ to add pci-code-revision h# 1234 pci-code-revision

]tokenizer fcode-version3

-----

----end0

10 Writing FCode 3.x Programs —November 1997

Elements of FCode Programming

FCode is a computer programming language defined by IEEE Standard 1275-

1994 Standard for Boot Firmware. FCode is semantically similar to ANS Forth, but is encoded as a sequence of binary byte codes representing a defined set of

Forth definitions.

FCode has these characteristics:

•

The source format is machine and system independent.

•

The binary format (FCode) is machine, system, and position independent.

•

The binary format is compact.

•

The binary format can be interpreted easily and efficiently.

•

Programs are easy to develop and debug.

•

The source format can easily be translated to binary format.

•

The binary format can be translated back to source format.

Forth commands are called words, and are roughly analogous to procedures in other languages. Unlike other languages, such as C, which have operators, syntactic characters and procedures, in Forth every word is a procedure.

A Forth word is named by a sequence of between one to 31 printable characters. A Forth program is written as a sequence of Forth word names separated by one or more white space characters (such as spaces, tabs, or line

Colon Definitions

12 terminators). Forth uses a left-to-right reverse Polish notation, like some scientific calculators. The basic structure of Forth is: do this, now do that, now do something else, and so on.

New Forth words are defined as sequences of previously existing words.

Subsequently, new words may be used to create still more words.

FCode is a byte-coded translation of a Forth program. Translating Forth source code to FCode involves replacing the Forth word names (stored as text strings) with their equivalent FCode numbers. The tokenized FCode takes up less space in PROM than the text form of the Forth program from which it was derived, and can be interpreted more easily and rapidly than the text form.

For purposes of this manual, the term FCode indicates both binary-coded

FCode and the Forth programs written as ASCII text files for later conversion to binary-coded FCode.

Except where a distinction between the two forms is explicitly stated, the use of FCode in this manual can be assumed to apply equally to both FCode and

Forth.

Three concepts are critical to understanding FCode (or Forth):

•

A colon definition creates a new word with the same behavior as a sequence of existing words. A colon definition begins with a colon and ends with a semicolon.

•

Once a new word has been created, it is immediately available, either for direct execution or for use in future colon definitions.

•

Most parameter passing is done through a pushdown, last-in, first-out stack.

Normally, the action associated with an FCode Function is performed when the

FCode Function is encountered. This is called interpret state. However, the state may switch between interpret state to compile state.

In interpret state, FCode Functions are executed as they are encountered.

Interpret state operates until encountering a “:”. The word “:” does the following:

•

Allocates an FCode Number and associates it with the name immediately following the colon.

Writing FCode 3.x Programs —November 1997

•

Switches to compile state.

In compile state, FCodes are saved for later execution, rather than being executed immediately. The sequence thus compiled is installed in the action table as a new word, and can be used later in the same way as if it were a builtin word.

Compile state continues until a “;” is read. The word “;” does the following:

•

Compiles an end-of-procedure FCode word

•

Switches to interpret state

After compilation, the newly-assigned FCode word can be either interpreted or compiled as part of yet another new word.

If you define a new word having the same spelling as an existing word, the new definition supersedes the older one(s), but only for subsequent usages of that word.

Here’s an example of a colon definition for a new FCode word dac!

: dac! ( data offset -- ) dac + rl! ;

Stack Operations

Each FCode word is specified by its effect on the stack and any side effects, such as accessing memory. Many FCode words affect the stack, by removing arguments from it, performing some operation, and putting the result(s) back on the stack.

A stack comment, included in the colon definition, describes the effect on the stack of the execution of an FCode word.

In the previous example, the stack comment, beginning with “

(

” and ending with “

)

”, shows that dac!

takes two parameters from the stack, and doesn’t replace them with anything when it’s done.

Stack comments can be put anywhere in a colon definition. They should be included wherever their use will enhance the clarity of the definition.

Elements of FCode Programming

The rightmost argument is on top of the stack, with any preceding arguments

“under it”. In other words, arguments are pushed onto the stack in left to right order, leaving the most recent argument (the rightmost one in the stack diagram) on the top.

In a stack diagram, parameters shown to the left of the double dashes are expected to be on the stack prior to the execution of the word. Parameters shown to the right of the double dashes are those which are left on the stack after execution of the word. Stack comments use the same convention but detail changes to the stack during execution of the word.

Stack comments and stack diagrams are essentially the same thing. Stack diagrams show the net effect to the stack of any Forth word. Stack comments are embedded in the definition of a word and are used to convey intermediate stack results or changes.

A series of words that describe the behavior of dac!

follow the stack comment in the preceding example. Executing

dac!

is the same as executing the list of words in its colon definition.

Note that FCode words are separated by spaces, tabs, or newlines, so in the previous example, “

( data

” is not the same as “

(data

”

Any visible character is part of a word, and not a separator.

Programming Style

Some people have described Forth as a write-only language. While it sometimes ends up that way due to poorly-written or uncommented code, it is possible to write Forth (and FCode) programs that can be read easily and understood. Well-written Forth programs will meet these criteria. See

Appendix C, “Coding Style” for detailed information about the style used in the existing OpenBoot FCode source base.

Although case is not significant, by convention FCode is written in lower case.

Commenting Code

Comment code extravagantly, then consider adding more comments. The comments will help with maintenance of the code, and don’t add to the final size of the resulting FCode PROM.

14 Writing FCode 3.x Programs —November 1997

Adopt the useful convention of using “

( )

” for stack comments and “

” for other descriptive text and comments.

In comments, describe the purpose of the Forth words, any interface assumptions and requirements, and unusual aspects of the algorithm you used. Try to avoid simply translating low-level details of the code into English.

Comments like, “increment the variable” are rarely helpful.

Coding Style

By studying the examples in this book, you can note the indentation and phrasing style that is widely used in OpenBoot source code. Adoption of this style will allow your Forth code to be read more easily by the many programmers who are accustomed to the style.

Definition Length

Keep word definitions short. If your definition exceeds half a page, it should be rewritten as two or more smaller definitions. This will help to make each definition more readable. Readable code is easier to maintain.

A good size for a word definition is one or two lines of code. Keeping definitions short and limited in functionality improves readability, speeds debugging and increases the likelihood that the word will be reusable.

Remember: reuse of Forth words is a principal contributor to compact PROM images.

Elements of FCode Programming

Notation

???

…

< > <space> a-addr

Stack Comments

Always include stack comments in word definitions. It can be useful to compare intended function with what the code really does. Here’s an example of a word definition with acceptable style.

\ xyz-map establishes a virtual-to-physical mapping for each of the

\ useful addressable regions on the board

0 value status-register

: xyz-map ( -- )

\ Base-address Size create-mapping then save virtual address

my-address 4 map-low

to status-register

my-address 10.0000 d+ frame-buf-size map-low

to frame-buffer-adr

;

( virtaddr )

( )

( virtaddr )

( )

Note the stack diagram following the word xyz-map

, and the use of stack comments in the word’s definition code.

Stack diagrams are generally written using descriptive parameter names to clarify correct usage. See the table below for stack parameter abbreviations used in this manual

Table 3-1

Stack Parameter Abbreviations

Description

Alternate stack results shown with space, e.g. (input -- addr len false | result true).

Alternate stack items shown without space, e.g. (input -- addr len|0 result).

Unknown stack item(s)

Unknown stack item(s). If used on both sides of a stack comment, means the same stack items are present on both sides.

Space delimiter. Leading spaces are ignored.

Variable-aligned address

16 Writing FCode 3.x Programs —November 1997

Table 3-1

Stack Parameter Abbreviations (Continued)

Notation

addr addr len byte b char

xxx

Description

Memory address (generally a virtual address).

Address and length for memory region

8-bit value (low order byte in a 32-bit word).

7-bit value (low order byte), high bit unspecified.

Count or length cnt or

len or

size d

xxx

<eol> false ihandle

Double (extended-precision) numbers. 2 stack items, hi quadlet on top of stack.

End-of-line delimiter

0 (false flag)

Pointer for an instance of a package n or

n1 or

n2 or

n3 n

xxx

Normal signed values (32-bit) nu or

nu1

Signed or unsigned values (32-bit)

<nothing> phandle

Zero stack items

Pointer for a package phys phys.lo phys.hi

pstr quad qaddr true or

{text}

qxxx

"text<delim>”

Physical address (actual hardware address)

Lower/upper cell of physical address

Packed string

Quadlet (32-bit value)

Quadlet (32-bit) aligned address

Optional text. Causes default behavior if omitted.

Input buffer text, parsed when command is executed. Text delimiter is enclosed in <>.

-1 (true flag) u

xxx

virt waddr word x or or

w x.lo x.hi

xxx

Unsigned value, positive values (32-bit)

Virtual address (address used by software)

Doublet (16-bit) aligned address

Doublet (16-bit value, low order two bytes in a 32-bit word)

Arbitrary stack item

Low/high significant bits of a data item

Elements of FCode Programming

Notation

xt xxx?

xyz-str xyz-len xyz-sys

( C: -- )

( -- ) or

( E: -- )

( R: -- )

Table 3-1

Stack Parameter Abbreviations (Continued)

Description

Execution token

Flag. Name indicates usage (e.g.

done? ok? error?

Address and length for unpacked string

Control-flow stack items, implementation-dependent

Compilation stack diagram

Execution stack diagram

Return stack diagram

A Minimal FCode Program

If a peripheral bus card is not needed during the boot process, a minimal

FCode program that merely declares the name of the device and the location and size of on-board registers will often suffice.

A minimum program for an SBus device is: fcode-version1

" SUNW,bison" encode-string " name" property my-address h# 20.0000 + my-space encode-phys h# 100 encode-int encode+

" reg" property end0

Note the following about this SBus example:

•

my-address

and my-space

each leave only a single number on the stack representing the phys.lo phys.hi address representation of an SBus node. (The value of

#address-cells

is 2 for SBus which is reflected by this format.)

•

An offset of 0x200000 is being added to the value returned by my-address

•

The size argument of

“ reg”

is a single number (since

#size-cells

is 1 for SBus) reflecting SBus’s 32-bit address space.

18 Writing FCode 3.x Programs —November 1997

FCode Classes

The example program above creates a

“ name”

property that will be used to identify the device whose value is “

SUNW,bison

”. Begin the name

attribute’s value with an identification of your company. The preferred form of this identification is an organizationally unique identifier (OUI), a sequence of six uppercase hexadecimal digits assigned by the IEEE Registration Authority

Committee. OUIs are guaranteed to be unique world-wide. (For more information about obtaining an OUI, please see the glossary entry for name

IEEE Standard 1275-1994 Standard for Boot Firmware.)

As an alternative to the OUI, you may use a sequence of from one to five uppercase letters representing the stock symbol of your company on any stock exchange whose symbols do not conflict with the symbols of the New York

Stock Exchange and the NASDAQ Exchange. All stock exchanges in the United

States satisfy this requirement. If a non-US company’s stock is traded on US stock exchanges by “depository equivalents”, those symbols also satisfy this requirement.

The preceding SBus example program can also be written using the following shorthand form. The FCode program generated will be equivalent to the minimum SBus program given above.

fcode-version1

" SUNW,bison" name my-address h# 20.0000 + my-space h# 100 reg end0

There are four general classes of FCode source words:

Table 3-2

FCode Source Word Classes

Primitives These words generally correspond directly to conventional

Forth words, and implement functions such as addition, stack manipulation, and control structures.

Elements of FCode Programming

Table 3-2

FCode Source Word Classes

System

Interface

Local

These are extension words implemented in the boot PROMs, and implement functions such as memory allocation and device property reporting.

These are specific to particular types of devices, and implement functions such as draw-character

for a display device.

These are private words, implemented and used only by the device that created the definition.

Each FCode primitive is represented in a peripheral card’s PROM as a single byte. Other FCodes are represented in the PROM as two consecutive bytes. The first byte, a value from 1 to 0x0f, may be thought of as an escape code.

One-byte FCode numbers range in value from

0x10

0xfe

. Two-byte FCode numbers begin with a byte in the range

0x01

0x0f

, and end with a byte in the range

0x00

0xff

. The single-byte values

0x00

and

0xff

signify “end of program” (either value will do; conventionally, 0x00 is used).

Currently-defined FCodes are listed in functional groups, in alphabetic order by name and in numeric order by FCode value in Appendix A, “FCode

Reference”.

Primitive FCode Functions

There are more than 300 primitive FCode functions, most of which exactly parallel ANS Forth words, divided into three groups:

•

FCode words that generate a single FCode byte

•

tokenizer macros

•

tokenizer directives

Primitive FCode functions that have an exact parallel with standard ANS Forth words are given the same name as the equivalent ANS Forth word. Chapter 14,

“FCode Dictionary”, contains further descriptions of primitive FCodes.

There are about another 70 tokenizer macros, most of which also have direct

ANS Forth equivalents. These are convenient source code words translated by the tokenizer into short sequences of FCode primitives.

20 Writing FCode 3.x Programs —November 1997

Tokenizer directives are words that generate no FCodes, but are used to control the interpretation process. Tokenizer directives include the following words:

•

decimal

, hex

, and octal

•

, h#

, and o#

•

headers

and headerless

•

and

(

•

alias

System FCode Functions

System FCode functions are used by all classes of FCode drivers for various system-related functions. System FCode functions can be either service words or configuration words.

•

Service words are available to the device’s FCode driver when needed for functions such as memory mapping or diagnostic routines.

•

Configuration words are included in the driver to document characteristics of the driver itself. These properties are made available for use by the operating system.

Interface FCode Functions

Interface FCode functions are standard routines used by the workstation’s CPU to perform the functions of the peripheral card’s device. Different classes of devices will each use only the appropriate set of interface FCodes.

Elements of FCode Programming

For example, in order to display a character on the screen, OpenBoot calls the interface FCode draw-character

. Previously, the FCode driver for the device controlling that screen must have assigned a device-specific implementation to draw-character

. It does this as follows:

: my-draw ( char -- ) \ "local" word to draw a character.

…

;

\ Definition contents.

\ end of my-draw definition.

: my-install ( -- )

…

\ local word to install all interfaces.

['] my-draw to draw-character

…

;

When my-install

executes, draw-character

is assigned the behavior of my-draw

Local FCode Functions

Local FCode functions are assigned to words defined in the body of an FCode program. There are over 2000 FCode byte values allocated for local FCodes.

The byte values are meaningful only in the context of a particular driver.

Different drivers reuse the same set of byte values.

22 Writing FCode 3.x Programs —November 1997

Debugging and Testing

FCode Programs

Packaging PCI FCode

Example: In trying to test a new version of an FCode program, a developer creates a new package as follows: ok 4000 dload /stand/mydev.fcode ok 0 0 " 4,0" " /pci@1f,2000" begin-package ok 4020 1 byte-load ok end-package

However, when doing an ls

, it is obvious that there are now TWO packages corresponding to the card: ok ls ffd70c00 my-network@4,0 ffd6e860 my-network@4,0 ok

To get rid of or override the original package so that the downloaded code is executed, remove the PCI card PROM. The CPU PROM will still create a device node for the card, but the " name

" property will have a value of the form

"pci<DDDD>,<VVVV>"

Create a name property for your device in your downloaded code with a value different from the one created by the CPU PROM. Then refer to your device by its full device path.

System Flags and FCode Debugging

Example: When using Sun systems debugging flags to aid in debugging

FCode, set the NVRAM variable fcode-debug?

to true to keep the headers for those words in your source preceded by headers.

Also, some CPU PROMS have a variable named " fcode-verbose?

" to display each FCode as it is being read at probe time by your CPU PROM’s token interpreter. To turn it on, before you probe your FCode, do: ok true to fcode-verbose?

<probe-your-card>

To set it from NVRAMRC, do: ok nvedit

0: true to fcode-verbose?

ok nvstore ok setenv use-nvramrc? true ok reset-all

Some CPU PROMs have pcimsg?

and probemsg?

variables to give additional

PCI-related information. You can turn them ON in a way similar to that described above.

pcimsg?

controls the display of all accesses to PCI configuration space.

probemsg?

controls the display of probing status information, including physical allocation.

Note that not all CPU PROMs have pcimsg?

and probemsg?

. Also, in future

PROMs, the behavior of pcimsg?

, probemsg?

and fcode-verbose?

may change, including the possibility of deletion.

24 Writing FCode 3.x Programs —November 1997

FCode Source

An FCode source file is essentially a Forth language source code file. The basic

Forth words available to the programmer are listed in Chapter 14, “FCode

Dictionary”.

FCode programs have the following format:

\ Title comment describing the program that follows fcode-version3

< body of the FCode program > end0 fcode-version3

is a macro which directs the tokenizer to create an FCode header. For a description of the FCode header see “FCode Binary Format”.

fcode-version3 produces a header including the start1

FCode. The macros fcode-version3

and fcode-version2

produce a header containing the start1

FCode. Whereas fcode-version1

produces a header with version1

FCode. To use all IEEE 1275 compliant Fcodes, use fcodeversion3

. (Since OpenBoot version 1 systems only recognize version1, plug-in device FCode that must run in OpenBoot version 1 systems must use fcode-version1

.) end0 is an FCode that marks the end of an FCode program. It must be at the end of the program or erroneous results may occur.

The comment in the first line is not necessary in many cases but it is recommended since it allows some OpenBoot tools to recognize the file as a

Forth source file.

Tokenizing FCode Source

The process of converting FCode source to FCode binary is referred to as

tokenizing. A tokenizer program converts FCode source words to their corresponding byte-codes, as indicated in Chapter 14, “FCode Dictionary”. A tokenizer program with instructions describing its use is available from http://www.sun.com/developers/driver under the tools icon as Fcode tokenizer and tools.

Debugging and Testing FCode Programs

An FCode program’s source can reside in multiple files. The fload

tokenizer directive directs the tokenizer input stream to load another file.

fload

acts like an

#include

statement in C. When fload

is encountered, the tokenizer begins processing the file named by the fload

directive. When the named file is completed, tokenizing continues with the file that issued the fload

fload directives may be nested.

Typically, the tokenizer produces a file in the following format:

•

Header - 32 bytes

•

FCode header - 8 bytes

•

FCode binary - remainder of file

The header has the following format:

•

4 bytes - 0x01030107 (hexadecimal)

•

4 bytes - Size in bytes of the FCode binary

•

4 bytes - 0x0

•

4 bytes - 0x0

•

4 bytes - 0x0

•

4 bytes - Load point of the file

•

4 bytes - 0x0

•

4 bytes - 0x0

You can use this file to load either an FCode PROM or system memory for debugging as described in “Using the Forth Monitor to Test FCode Programs”.

The load point of the file is not used when burning an FCode PROM, but is used by Forth Monitor commands that load FCode files into system memory.

The tokenizer available from SunExpress sets the load point to be the recommended 0x4000 address.

Writing FCode 3.x Programs —November 1997

FCode Binary Format

Byte(s)

2 and 3

4 through 7

The format of FCode binary that is required by the OpenBoot FCode evaluator is as follows:

Table 4-1

FCode Binary Format

Element

FCode header

Body

End byte-code

Structure

Eight bytes

0 or more bytes

1 byte, the end0

byte-code

The format of the FCode header is:

Table 4-2

FCode Header Format

Content

One of the FCodes: start0

, start1

, start2

, start4,version1 reserved reserved count of bytes in the FCode binary image including the header

Testing FCode Programs on the Target Machine

Once you have created the FCode binary, you can test it using the OpenBoot

Forth Monitor. The Forth Monitor provides facilities to allow you to load your program into system memory and direct the FCode evaluator to interpret it from there. This allows you to debug your FCode without having to create a

PROM and attach it to your plug-in board for each FCode revision during the debug process. See the OpenBoot 3.x Command Reference for complete documentation of the use of the Forth Monitor.

The FCode testing process generally involves the following steps:

1. Configuring the target machine. This includes installing the hardware associated with the FCode program in the target machine and powering-up the machine to the Forth Monitor.

Debugging and Testing FCode Programs

2. Loading the FCode program into memory from a serial line, a network, a hard disk, or a floppy disk.

3. Interpreting the FCode program to create a device node(s) on the OpenBoot device tree.

4. Browsing the device node(s) to verify proper FCode interpretation.

5. Exercising the FCode program’s device driver methods compiled into the device node, if any.

If the FCode program does not include any methods which involve using the actual hardware (for example, a driver which only publishes properties) then the program can be tested without installing the hardware.

Configuring the Target Machine

Setting Appropriate Configuration Parameters

Before powering-down the target machine to install the target hardware, a few

NVRAM configuration variables should be set to appropriate values. You can set them from the Forth Monitor as follows: ok setenv auto-boot? false ok setenv fcode-debug? true

Setting auto-boot?

to false

tells OpenBoot not to boot the OS on a machine reset but rather to enter the Forth Monitor at the ok

prompt.

Setting fcode-debug?

to true

tells the OpenBoot FCode evaluator to save the names of words created by interpreting FCode words which were tokenized with headers

on. This is in addition to words defined after the tokenizer processed an external

directive (in other words, words whose names are always saved).

fcode-debug?

defaults to false

to conserve RAM space in normal machine operation.

28 Writing FCode 3.x Programs —November 1997

Modifying the Expansion Bus Probe Sequence

The start-up sequence in the machine’s OpenBoot implementation normally examines all expansion buses for the presence of plug-in devices and their onboard FCode PROM programs. It then invokes the FCode evaluator to interpret any programs found. This process is called probing.

When using the Forth Monitor to load and interpret an FCode program in system memory, it is better to configure OpenBoot to avoid probing that device automatically. The probing can then be done manually (as explained later) from the Forth Monitor.

Configuring an OpenBoot implementation to avoid probing a given slot on a given expansion bus can be done in various implementation-dependent ways.

That is, they will be different for different systems and different expansion buses.

Many machines with SBus have an NVRAM configuration variable named sbus-probe-list

. It defines which SBus card slots will be probed during start up and the order in which they will be probed.

For example, a machine with four SBus slots might have the sbus-probe-list

configuration variable set to a default value of 0123.

Setting sbus-probe-list

to 013 directs OpenBoot during start-up to probe first SBus slots 0, 1, and 3. This leaves SBus slot 2 unprobed, free for use by the device under development.

Methods to prevent probing a given slot for other types of expansion buses can involve using the NVRAMRC script

Among other uses, an NVRAMRC script can:

•

Patch an implementation-specific OpenBoot word that defines the bus’s probe sequence

•

Modify a property of the expansion bus’s device node that describes the sequence.

After the FCode program is debugged and programmed in PROM on the device, you can do a full system test (including automatic probing of the new device), by restoring the expansion bus probing configuration to the default.

Debugging and Testing FCode Programs

Getting to the Forth Monitor

After completing the configuration described above, power the machine down and install the device. Then power the system up. The display should stop scrolling at the ok

prompt, ready to accept Forth Monitor commands.

Using the Command Line Editor of the Forth Monitor

Refer to the OpenBoot 3.x Command Reference for a list and description of the line-editing commands available with the Forth Monitor.

Using the Forth Monitor to Test FCode Programs

Directions for using the Forth Monitor to download files to system memory are provided in the OpenBoot 3.x Command Reference. Common package-related commands are shown below.

Command

begin-package end-package open-dev device-end select-dev

Table 4-3

Common Package-related Commands

Stack Diagram Function

( arg-addr arg-len reg-addr reg-len path-addr path-len -- ) Initializes device tree for executing FCode.

( -- ) Completes a device tree entry and returns to the

Forth Monitor environment.

( path-addr path-len -- )

( -- )

( path-addr path-len -- )

Opens the specified device node and all of its parents.

Closes the current node and returns to the Forth

Monitor environment.

Opens the specified device node and all of its parents, and makes the device the current instance.

30 Writing FCode 3.x Programs —November 1997

Command

unselect-dev set-args execute-device-method

Table 4-3

Common Package-related Commands (Continued)

Stack Diagram

( -- )

( arg-addr arg-len reg-addr reg-len -- )

( … path-addr path-len cmd-addr cmd-len -- … ok? )

Function

Closes the specified device node and all of its parents, and unselects the active package and current instance leaving none selected.

Sets values returned by my-args

, my-space

and my-address

for the current node.

Executes the named command in the specified device tree node.

Using

dload

to Load from Ethernet

dload

loads files over Ethernet at a specified address, as shown below.

ok 4000 dload

filename

In the above example, filename must be relative to the server's root. Use

4000

(hex) as the address for dload

input.

Note –

One can use any value other than 4000 as long as it has been properly mapped.

FCode programs loaded with dload

must be in the format described in

“Tokenizing FCode Source”.

dload

uses the trivial file transfer protocol (TFTP), so the server may need to have its permissions adjusted for this to work.

Debugging and Testing FCode Programs

Using

dlbin

to Load From Serial Port A

dlbin may be used to load files over serial line A. Connect the target system's serial port A to a machine that is able to transfer a file on request. The following example assumes a tip window setup on a Sun system which will provide the FCode file. (See the OpenBoot 3.x Command Reference for information on setting tip

connections.)

1. At the ok

prompt, type: ok dlbin

2. In the tip

window of the other system, send the file:

~C (local command) cat

filename

( Away two seconds)

The ok

prompt will reappear on the screen of the target system.

FCode programs loaded with dlbin

must be in the format described in

“Tokenizing FCode Source”.

dlbin

loads the files at the entry point indicated in the file header. It is suggested that this address be 0x4000.

Using

boot

to Load From Hard Disk, Diskette, or Ethernet

You can also load an FCode program with boot

, the command normally used to boot the operating system. Use the following format: ok boot [

device-specifier

] [

filename

] -h

device-specifier is either a full device path or a device alias. See the OpenBoot 3.x

Command Reference for information on device path and aliases.

For a hard disk or diskette partition, filename is relative to the resident file system. See the OpenBoot 3.x Command Reference for information on creating a bootable diskette. For a network, filename is relative to the system's root partition on its root server. In both cases, the leading / must be omitted from the file path.

Writing FCode 3.x Programs —November 1997

The

-h

flag specifies that the program should be loaded, but not executed. This flag must be included since otherwise boot

will attempt to automatically execute the file assuming it is executable binary.

boot

uses intermediate booters to accomplish its task. When loading from a hard disk or diskette, the OpenBoot firmware first loads the disk's boot block, which in turn loads a second-level booter. When loading over a network, the firmware uses TFTP to load the second-level booter. In both cases, filename and

-h

are passed to these intermediate booters.

The output file produced by a tokenizer may need to be converted to the format required by the secondary boot program. For example, Solaris 2.x intermediate booters require ELF format.

fakeboot

, a program available from

SunExpress, may be useful in this process.

The location in memory where the FCode program is loaded depends on the secondary boot program and the fakeboot

program.

Using

dl

to Load Forth Over Serial Port A

Forth programs loaded with dl

must be ASCII files.

To load the file over the serial line, connect the system's serial port A to a machine that is able to transfer a file on request. One method is to set up a TIP window on another Sun system. (See OpenBoot 3.x Command Reference for information on this procedure.) The following example assumes a TIP window setup.

1. At the ok

prompt, type: ok dl

2. In the TIP window of the other system, send the file, and follow it with a

Control-D

to signal the end of the file.

~C (local command) cat

filename

( Away two seconds)

^-D

The ok

prompt appears on the screen of the system to which the file is loaded.

Debugging and Testing FCode Programs

normally loads the file at 4000 (hex). The file is automatically interpreted after it is loaded.

Using the Forth Monitor to Interpret an FCode Program

FCode program interpretation involves creating a device node on the device tree. Device nodes are also known as packages. Creating a device node from downloaded FCode involves the following steps:

1. Set up the environment with

begin-package

For example, a begin-package

call for creating a device node for a SBus card installed in SBus Slot 3 of a SPARCstation 2 looks like: ok 0 0 " 3,0" " /sbus" begin-package

In the example, the string,

/sbus

, indicates that the device node which will be created by the FCode program is to be a child node of the

/sbus

node in the device tree.

In general, parent nodes, which support child nodes, can be used as this argument to begin-package

. The device node defined by the FCode program will be created as a child of that node. Give the full device pathname from the root node. Other types of parent nodes define different address spaces. Another example of an SBus parent node is on a

SPARCstation 10 where its device pathname is

/iommu/sbus

In the example, the string,

" 3,0"

indicates the SBus slot number, 3 and byte-offset 0 in the slot’s address space where the device node is to be based.

In general, this string is a pair of values separated by a comma which identify the physical address associated with the expansion slot. The form of this physical address depends on the physical address space defined by the parent node. For children of an SBus node, the form is slot-number, byte-offset

. Other parent nodes will define different address spaces.

The physical address pair value is retrieved in the FCode program with both the my-address

and my-space

FCodes. The slot ID string is converted to a binary form consisting of three values. Those values can be retrieved with the FCode program by using my-address

for the phys.lo and phys.mid components and my-space

for the phys.hi component.

34 Writing FCode 3.x Programs —November 1997

In the preceding example, the initial

0 0

represents a null argument string passed to the FCode program.

This argument string is retrieved in the FCode program with the my-args

FCode. Generally, FCode programs do not take arguments at interpretation time so this will usually be the null string.

begin-package

is defined as:

: begin-package ( arg-addr arg-len reg-addr reg-len dev-addr dev-len -- )

select-dev new-device set-args

; select-dev

( parent-dev-addr parent-dev-len --

) opens the input device node (the parent node) and makes it the current instance. new-device

(

) initializes a new device node as a child of the currently active node and makes it the current instance.

set-args

( arg-addr arg-len reg-addr reg-len --

) sets the values returned by my-args

, my-space

, and my-address

for the current instance.

2. Interpret the loaded FCode with

byte-load byte-load

is the Forth Monitor command that invokes the FCode evaluator to compile the FCode program into the current instance.

For FCode programs downloaded with byte-load

use: ok <fcode-stat-address> ' c@ byte-load load-base

is the system default load address. The argument,

' c@

, tells byte-load

to use c@

as the access routine for reading the FCode.

3. Close the environment with

end-package end-package

finishes up the creation of the device tree node.

ok end-package

Debugging and Testing FCode Programs

It is defined as:

: end-package ( -- ) finish-device unselect-dev ; finish-device ( -- )

Completes the device tree node initialized by new-device

and changes the current instance to the parent node.

unselect-dev ( -- )

Closes the parent device tree node and returns to the normal Forth Monitor environment. That is, there is no longer a current instance or active package.

Using the Forth Monitor to Browse a Device Node

The Forth Monitor has many built-in commands to navigate the device tree.

Table 4-4 lists the Forth Monitor commands supporting device node browsing:

Table 4-4

Commands for Browsing the Device Tree

Command

.properties

dev

device-path

dev

node-name

dev

dev /

Description

Display the names and values of the current node’s properties.

Choose the indicated device node, making it the current node.

Search for a node with the given name in the subtree below the current node, and choose the first such node found.

Choose the device node that is the parent of the current node.

Choose the root machine node.

device-end

De-select the current device node, leaving no node selected.

device-path

" find-device

Choose device node, similar to dev

get-inherited-property get-my-property ls pwd see

wordname

show-devs [

device-path

] words

( name-addr name-len -- true | value-addr value-len false )

Return property value of current instance or its parents

( name-addr name-len -- true | value-addr value-len false )

Return property value of current instance.

Display the names of the current node’s children.

Display the device path that names the current node.

Decompile the specified word.

Display all the devices known to the system directly beneath a given level in the device hierarchy.

show-devs

used by itself shows the entire device tree.

Display the names of the current node’s methods.

36 Writing FCode 3.x Programs —November 1997

Once a device node has been created, you can use the Forth Monitor to browse the node. See the OpenBoot 3.x Command Reference for a more complete discussion. Here is a brief synopsis of the available commands:

•

show-devs

displays all known devices in the device tree.

•

dev

sets the active package to a named node so its contents can be viewed.

For example, to make the ACME company’s SBus device named

“ACME,widget” the active package: ok dev /sbus/ACME,widget

•

find-device

is essentially identical to dev

differing only in the way the input path is passed.

ok " /sbus/ACME,widget" find-device

•

.properties

displays the names and values of all the properties created for the active package.

•

get-my-property

returns the value of the specified property from the active package.

•

get-inherited-property

returns the location and length of the property value array of the specified property from the active package or its parents.

dump

can then be used to display the property value array.

•

displays the names of all child nodes, if any, of the active package.

•

words

shows the names of the device node methods, if any, created by the

FCode program. It shows all words which were defined with external and, if fcode-debug?

was true when the FCode was interpreted, the words defined with headers

•

see

wordname displays the source code (without comments) for wordname.

•

device-end

reverses the effects of the dev

or find-device

command.

•

pwd

displays the device path of the active package.

Debugging and Testing FCode Programs

Using the Forth Monitor to Test a Device Driver

The Forth Monitor provides the capability to test the methods of an FCode program by allowing you to execute individual methods from the Forth

Monitor prompt.

Device Node Methods

Using

select-dev

initializes an execution environment for the methods of the package specified by its stack arguments. It allows the user to subsequently execute the device node’s methods directly by name. For example: ok " /sbus/ACME,widget" select-dev select-dev

performs the following steps:

1. Effectively calls “ dev /sbus/ACME,widget

” to make the named device the active package. This enables the recognition of the device methods by the Forth Monitor.

2. Establishes a chained set of package instances for each node in the path. In particular, this makes the package’s instance-specific data items available to its methods.

3. Opens all device nodes in the path by calling the open method of each.

select-dev

assumes open (and close) methods in each node in the path, so the device node under test must have one.

Once these steps are performed, you can execute the methods of the current device node by typing their names at the prompt. For example: ok clear-widget-register ok fetch-widget-register .

38 Writing FCode 3.x Programs —November 1997

As is generally true of the Forth language, if execution of a method exposes an error in the code, the error can be isolated by executing the component words of the method step-by-step. Use see

to decompile the method, then type the component words individually until the error is apparent. For example: ok see clear-widget-register

: clear-widget-register

enable-register-write

0 widget-register rl!

disable-register-write

; ok enable-register-write ok 0 widget-register rl! ok disable-register-write

This process can be performed recursively by decompiling the component words and then individually executing their component words. This is much easier if most of the words were defined with the headers

directive, since see can then display the names of the component words instead of hexadecimal codes.

This process is also enhanced by executing showstack

showstack

causes the stack’s contents to be displayed prior to every ok

prompt. For example: ok 1 2 ok showstack

1 2 ok . clear 3 4

3 4 ok

Device nodes can also be modified as needed with any of the following techniques:

•

Entering new methods definitions. These methods are compiled into the device node like the methods in the FCode program that created the node.

Debugging and Testing FCode Programs

•

Redefining a method to include a function neglected in the first definition.

(Previously defined words using the original definition of the method are unaffected.) For example: ok : open open initialize-widget-register-2 ;

In general, such redefinitions affect only external uses of the named method

(for instance, calls from other packages via

$call-method

and the like) and interactive use via the Forth Monitor. Previously compiled calls to the method in the same package are unaffected unless the method is called by name (for example, with

$call-self

•

Use patch

to edit word definitions. Such patches affect all uses of the method, both internal and external. (See the OpenBoot 3.x Command Reference

Manual for information about using patch

•

Resetting the machine causes all such corrections to be lost. Consequently, once your words are debugged you’ll probably want to include any modifications in the FCode program source.

unselect-dev

reverses the effects of select-dev

by calling the close method of each device in the path of the current active node, destroying the package instance of each node, and returning to the normal Forth Monitor environment. Execute unselect-dev

as follows: ok unselect-dev

Using

begin-select-dev

Sometimes, select-dev

will not work because the open

method of a newlywritten package does not work correctly. In this case, begin-select-dev

can be used since it does everything that select-dev

does except for opening the last child node. For example: ok " /sbus/ACME,widget" begin-select-dev

Writing FCode 3.x Programs —November 1997

Using

execute-device-method

executes a method directly from the normal Forth

Monitor environment. That is, it is not necessary to manually make the device node the current instance before executing the method. For example: ok " /sbus/ACME,widget" " test-it" execute-device-method execute-device-method

returns false

if the method could not be executed; otherwise it returns true

on top of whatever results were placed on the stack by the successful execution of the method.

execute-device-method

performs the following steps:

1. Establishes a chained set of package instances for each node in the path. In particular, this makes an instance of all data items of the device node available to its methods.

2. Opens all device nodes in the named device path except the last device node in the pathname.

3. Invokes the named method.

4. Closes all the device nodes in the path (except the last one) destroying their package instances.

5. Restores the current instance to the one that was current prior to beginning this process.

6. Restores the active package to the one that was active prior to beginning this process.

7. Returns the results.

Note that, in contrast to select-dev

, execute-device-method

does not call the open

method of the last device node in the path. Consequently, any method invoked in this manner must not require any pre-established state which normally is created by open

In summary, execute-device-method

is provided to allow execution of device node methods designed to provide their own state initialization, and therefore to execute without previous execution of the open

method. A typical example is a selftest

method.

Debugging and Testing FCode Programs

Using

apply

provides an alternative manner of invoking execute-devicemethod

in that it takes its arguments from the input stream instead of from the stack. The above example would be invoked with apply

as follows: ok apply test-it /sbus/ACME,widget

Since apply

invokes execute-device-method

, all of the restrictions listed above for execute-device-method must be followed.

Testing FCode Programs in Source Form

The Forth Monitor enables you to skip the tokenizer and download FCode program source directly. This practice is not recommended since the only advantage is to save a small amount of time tokenizing the program. There are also some disadvantages:

•

It may cause problems in the long run since generally the Forth Monitor recognizes a larger number of words than the FCode evaluator does. So the

FCode program developer who tests with FCode source may develop and test a program only to find that some of the words used are not FCode words, and will not be accepted by the tokenizer and the FCode evaluator.

•

To load source you should comment out fcode-version1

and end0

•

Since the download commands accept only one file, replace fload with the actual file.

To load an ASCII Forth source file over serial line A, you use the command dl

In addition to loading the file over the serial line, dl

compiles the Forth source while it is loading, without requiring an extra command. Therefore, you must execute begin-package

before downloading. See “Using dl to Load Forth

Over Serial Port A” for details.

Producing an FCode PROM

The output of the tokenizer program is used to make an actual FCode PROM.

If your PROM burning tools do not accept the raw binary format of the tokenizer, you may need to develop a format conversion utility.

42 Writing FCode 3.x Programs —November 1997

Exercising an Installed FCode PROM

You can either let OpenBoot automatically evaluate the FCode program from the PROM or you can remove the device from the OpenBoot probing as discussed earlier in “Configuring the Target Machine”.

The same process discussed for testing FCode programs loaded to system memory can be used to test FCode programs already loaded into PROM on the device.

If you take the device out of the probing sequence, a device node can be built manually as in the following example for a device installed in SBus slot 1: ok 10000 constant rom-size ok " /sbus" select-dev ok " 1" decode-unit ok rom-size map-in ok new-device ok " " " 1,0" set-args ok dup 1 byte-load ok finish-device ok rom-size map-out ok unselect-dev

( phys.lo phys.mid phys.hi )

( virt )

This is essentially the same sequence as outlined for evaluating FCode loaded into system memory, except that you must map in and map out the FCode

PROM by using the decode-unit

, map-in

, and map-out

methods of the parent device node. For more information about these methods, see

Chapter 10, “Memory-Mapped Buses”.

You can browse the device node and exercise the device methods in the same way as described earlier. You can also define new methods and patch existing ones. Of course, these modifications will only remain until a system reset.

select-dev

-Generated Errors

To debug your FCode/device in the case of errors during the use of select-dev

on the device, do the following.

Debugging and Testing FCode Programs

Add a dummy open

method to your device node's FCode if you want to be able to select (open) the device to map the device in at the ok

prompt and look at the device registers, etc.:

ok dev /pci..../<device-node>

ok : open true ;

( This may generate a message about open not being unique)

ok device-end

Now you can use " select-dev

" to open/select your device. Then use

" map-in

$call-parent

to map in the device registers, and examine them.

The endianness may differ from what you think. Verify the way that the device is mapped with map?

Also, verify that rl@

and other register access words return the data in the way you expect.

44 Writing FCode 3.x Programs —November 1997

Helpful Testing and Debugging

Hints

This chapter contains information to consider when you are designing FCode code for PCI.

Accessing a PCI Device’s Configuration Space Registers

It isn’t necessary to do anything extra to access your device’s configuration space registers. They are always accessible.

Base Address Register Setting

The base address registers in the configuration space are set by the CPU

PROM.

The CPU PROM (not the PCI card's FCode PROM) allocates the base address for memory and/or I/O space on your PCI device and for the FCode PROM.

System Cache Line Size

To determine the system’s cache line size from the FCode to write into the cache-line-size configuration space register of your PCI device, look in the cache-line-size register in the configuration space; it refers to the cache line size supported by the PCI device.

Sun Ultra-30 UPA/PCI-Related Nodes

The PCI-related nodes on the Sun Ultra-30 UPA/PCI system are

/pci@1f,4000

and

/pci@1f,2000

pcia

and pcib

as needed for the

NVRAM variables pcia-probe-list

and pcib-probe-list

are determined in the following manner.

Each PCI bus has a property named " slot-names

" which gives information about slots on that PCI bus. It could sometimes indicate which NVRAM variable corresponds to it.

To get a human-readable value for that property, do the following: ok " </pci-bus-node>" select-dev ok " slot-names" get-my-property drop decode-int .h cr type

For example, for a PCI bus at

/pci@1f,2000

: ok " /pci@1f,2000" select-dev ok " slot-names" get-my-property drop decode-int .h cr type will display something like:

6 pcia slot 1pcia slot 2

This is an indication that devices under

/pci@1f,2000

relate to pcia

In a Sun Ultra-30 UPA/PCI with 4 plug-in PCI slots, only slot 1 is physically present for pci@1f,2000

. It can also support 66 Mhz., 64 bit PCI devices.

ok " /pci@1f,4000" select-dev ok " slot-names" get-my-property drop decode-int .h cr type

34 pcib slot 2pcib slot 4pcib slot 5

This is an indication that devices under

/pci@1f,4000

relate to

46 Writing FCode 3.x Programs —November 1997

pcib,

In a Sun Ultra-30 UPA/PCI with 4 plug-in PCI slots:

•

Slots 2, 4 and 5 under

/pci@1f,4000

support 33 Mhz., 32 bit PCI devices.

•

Slot 3 under

/pci@1f,4000

is for an on-board SCSI device.

Note that the value of the “ slot-names

" property differs for different systems. Some systems may not indicate which PCI bus is which by the value of the " slot-names

" property.

Also in different releases of the PROM for the same system, the value of the

" slot-names

" property may change. You may need to refer to the system documentation for details about PCI buses on the system.

Alternatively, you can find which NVRAM variable refers to which PCI bus by setting the NVRAM variables to different values and/or by plugging PCI card(s) in different slot(s).

Finding and Using Physical Addresses

To find and use physical addresses to access, for instance, configuration space registers on a Sun Ultra-30 UPA/PCI system, do MMU bypassing with the choice of the correct ASI space. The arguments for the space {c,d,w,l,x} command includes an address and ASI code (and data for a write operation.)

On Sun Ultra-30 UPA/PCI systems, a PCI device’s configuration registers are viewed using the following address:

1fe.0100.0000 + X where the 32-bit value of

is represented in bit format as:

0000.0000.bbbb.bbbb.dddd.dfff.rrrr.rrrr

where where bbbb.bbbb

is an eight bit bus number, dddd.d

is a five bit device number fff

is a three-bit function number rrrr.rrrr

is an eight-bit register number

So, if the bus number is 81, device number is 0 and function number is 1, then

X will be 81.0100, giving you a configuration register base.

Helpful Testing and Debugging Hints

So you'll access the 0th configuration register at 1fe.0181.0100 (physical address). On Sun Ultra-30 UPA/PCI systems, you can use ASI 0x15 for a noncacheable address being accessed by MMU bypass. If you are accessing a littleendian device, use ASI 0x1d.

You can get bus number, device number, and function number from my-space after selecting that device or from the " reg

" property value for that device.

Look in IEEE 1275/PCI binding for the " reg

" property format.

In general, for any system, to get physical addresses for registers in any space

(configuration space, 32- bit memory space, and others.) use the map-in command.

map-in

requires the phys.lo

, phys.mid

, phys.hi

, and length arguments.

Phys.lo

, phys.mid

, and phys.hi

numbers can be taken from the corresponding " reg

" property.

In the case of configuration space, getting the physical address is easy since phys.lo

and phys.mid

are always zero.

phys.hi

is just the configuration space address.

Here is an example of getting the physical address of the configuration space registers, using onboard ethernet on a Sun Ultra-30 UPA/PCI system: ok " /pci@1f,4000/network@1,1" begin-select-dev ok pwd

/pci@1f,4000/network@1,1 ok .properties

reg (Config Space ---->)00000900 00000000 00000000 00000000

00000000

(32bit memory space ---->) 02000910 00000000 00000000 00000000

00007020

ok 0 0 900 100 " map-in" $call-parent constant my-cfg-vaddr ok my-cfg-vaddr . fff80900 ok my-cfg-vaddr map? VA:fff80900

G:0 W:1 P:1 E:1 CV:0 CP:0 L:0 Soft1:1 PA[40:13]:ff00800

PA:1fe01000000

Diag:0 Soft2:0 IE:0 NFO:0 Size:0 V:1

PA:1fe01000900

Writing FCode 3.x Programs —November 1997

Hence the physical address for the base of configuration registers is

1fe.0100.0900 for this device. For plug-in PCI devices, the registers’ physical address may vary if the device is plugged into a different slot, or if other devices are present. Similarly, using the " reg

" entry for memory or I/O space, you can find a physical address for those spaces.

Controlling PCI Slot Probing on an Ultra-30 UPA/PCI System

You can control probing of PCI slots on your Sun Ultra-30 UPA/PCI system as follows. On Sun Ultra-30 UPA/PCI system, during normal system initialization, there are NVRAM variables which indicate to the CPU PROM what slots to probe and in what order. On the Sun Ultra-30 UPA/PCI system they are: pcia-probe-list

and pcib-probe-list

. The default value for pcia-probe-list is 1,2; for pcib-probe-list

, it is 3,2,4,5. To disable slot 4 probing on pcib

, during normal initialization after a reset, change pcib-probe-list

to: ok setenv pcib-probe-list 3,2,5

After a reset, to probe slot 4 on pcib

manually do: ok 4 probe-pci-slot /pci@1f,4000

Note that not all CPU PROMs have the probe-pci-slot

command. Also, in future PROMs, behavior of this command may change, including the possibility of its deletion.

Helpful Testing and Debugging Hints

Using 3.x Tokenizer and 3.x CPU PROMs

Here are some points to consider while using the 3.x tokenizer: While you are testing FCode under CPU OpenBoot PROM 3.x versions, make sure that you have OpenBoot PROMs version 3.1 or later. Pre-3.1 PROMs will need the following NVRAM patch: ok nvedit

0:: nl-move( src dst len -- ) rot n->l rot n->l rot n->l

(move);

1: ['] nl-move is move

2: ['] l>>a 2 la+ dup l@ h# 1000 invert and swap l!

3: ['] lrshift 2 la+ dup l@ h# 1000 invert and swap l!

4: ^C ok nvstore ok setenv use-nvramrc? true ok reset-all

Also, note that, while using the 2.x or 3.x tokenizer, literals or numbers that have bit 31 set to 1 will extend this bit (1) to bit 63 on 3.x CPU PROMs. For example:

8000.0000 constant xxx will in reality be giving a value as: ffff.ffff.8000.0000. When such words or constants are used in address manipulation or otherwise, your code should clip them to a 32 bit value:

Get a real 8000.0000 by: ff ff ff ff bljoin constant x-num

: clip-num ( n -- l ) x-num and ;

8000.0000 clip-num constant xxx or use xxx clip-num

wherever " xxx

" is being used.

50 Writing FCode 3.x Programs —November 1997

PCI Device Configuration Register Access

To find the address to use for configuration register access on your PCI device, look in the format for the physical address of the " reg

" property. Use the phys.hi

cell of the first entry in the " reg

" property as the base address for the configuration space. The first entry in the " reg

" property must be the configuration space entry ( bbbb.bbbb.dddd.dfff.0000.0000

binary).

Using this or any other method, obtain the values of bbbb.bbbb

, ddddd

and fff

for your device. Then use: ok "< parent-pci-bus-node>" select-dev ok <bbbb.bbbb.dddd.dfff>XX config-l@

(

is the offset for that register configuration.) For example, if the bus number is 1000.0001 (0x81), the device number is 0.0000, and the function number is

001 (0x01), then use ok " /pci@1f,2000" select-dev ok 81.0100 config-l@ ok 81.0104 config-w@ ok 81.0130 config-l@ register)

( to read device id and vendor id)

( to read command register )

( to read the expansion PROM base address

Boot Software Roles

Three types of software involved during a boot: the kernel, FCode, and the OS driver. This section describes the normal Solaris operating environment boot scenario, including the functions of each and the order in which they begin.

At power-on, the CPU PROM begins execution. It probes all on-board devices and plug-in cards, thus interpreting the FCodes on all FCode PROMs. In the

FCode probing process, FCode PROMs generate properties for devices. Some

FCode PROMs execute commands to reset the device and perform other initialization.

Helpful Testing and Debugging Hints

Then, the CPU PROM boots over the specified boot device (using its FCode boot driver), loads bootblk

(or inetboot

for network booting), and passes control to the bootblk

code. Then, the bootblk

code loads the kernel and modules, and passes control to the kernel. The kernel at some point starts to use the OS-device driver.

So, the order is:

•

CPU-PROM

•

FCode-PROM

•

bootblk

•

Kernel

•

OS driver.

Enabling Access to a PCI Device’s Memory Space Locations

If a developer is loading FCode and can’t access memory space locations, how should they go about enabling access to memory space locations for their PCI device?

Look in the format for the physical address of " reg

" property. Using that (or any other method), obtain the values of bbbb.bbbb

, ddddd

and fff

for your device. Then use ok " <parent-pci-bus-node>" select-dev ok 3 <bbbb.bbbb.dddd.dfff>04 config-w!

This will write to the configuration space command register and thus enable access to memory and I/O space. This sets bit[0] and bit[1] of the command register. In the same way, you may set other bits in the command register, if needed by your application. If the bus number is 1000.0001 (0x81), the device number is 0.0000, and the function no. is 001 (0x01), you will then use ok " /pci@1f,2000" select-dev ok 81.0104 config-w@ 3 or 81.0104 config-w!

52 Writing FCode 3.x Programs —November 1997

Normally, your FCode driver’s open

routine should enable such access.

FCode can use the value returned by my-space

and add an offset of 4 to get the address of the command register. Then it can set various bits in the command register to enable the desired access. The close

routine should disable that access.

Expansion FCode PROM

If a developer is unable to access his expansion FCode PROM, how can access to it be enabled?

To enable access, look in the format for the physical address of the " reg

" property. Using that (or any other method), obtain the values of bbbb.bbbb

, ddddd

and fff

for your device. Then use ok "< parent-pci-bus-node>" select-dev ok <bbbb.bbbb.dddd.dfff>04 config-w@ 3 or

<bbbb.bbbb.dddd.dfff>04 config-w!

ok <bbbb.bbbb.dddd.dfff>30 config-l@ 1 or

<bbbb.bbbb.dddd.dfff>30 config-l!

This will first enable memory and I/O space access. Then, it will read the value from the expansion PROM configuration space base address register (at offset 0x30) or 1 to it, and write the value in the expansion PROM base address register to enable access to your FCode PROM. This sets bit[0] of the expansion PROM base address register. In other words, if the bus number is

1000.0001 (0x81), the device number is 00000, and the function number is 001

(0x01), then use: ok " /pci@1f,2000" select-dev ok 81.0104 config-w@ 3 or 81.0104 config-w! ok 81.0130 config-l@ 1 or 81.0130 config-l!

If for any reason, (for example, to access Vital Product Data stored in the

PROM) the FCode needs to access PROM data, then the FCode should enable

PROM access by using the value returned by my-space

and adding an offset of 0x30 as the register address. The FCode should read the value from the address, or the value with 1, and write the result back to that address.

Helpful Testing and Debugging Hints

Also, since the FCode would have been copied in memory, devices' memory and I/O spaces may not be enabled. So, the FCode must enable them, using

FCode: ok my-space h# 30 + dup config-l@ 1 or swap config-l! ( enable

PROM access) ok my-space h# 4 + dup config-w@ 3 or swap config-w! ( enable

I/O, memory access)

Using the example above, you can disable expansion PROM access as: ok my-space h# 30 + dup config-l@ 1 invert and swap config-l!

( disable PROM access)

Packaging Error with Ethernet FCode

In trying to load the FCode from Ethernet, the code seems to load without errors; however, when the developer tries to build the package, she gets an error: ok 4000 dload /stand/cheerio.o

Boot device: /pci@1f,4000/network@1,1:,|stand|cheerio.o File and args: ok 0 0 " 0,1" " /pci@1f,2000" begin-package ok 4000 1 byte-load

Unimplemented FCode token before address 4004

Warning: FCode sequence resulted in a net stack depth change of 1 ok

The error may be due to either of these causes:

1. The PCI header is attached to the PROM image, or

my-address

is 2 32-bit numbers for PCI and only 1 32-bit number for SBus.

If the cause is 1, dump the download image beginning at 4000, for example

4000 60 dump

54 Writing FCode 3.x Programs —November 1997

and see where f1

or fd

starts. It is the beginning of the FCode data for the byte-load. For instance, if the FCode data starts at x

, use the address x

in ok X 1 byte-load f1

or fd

is the beginning of the FCode header, 8 bytes long, as: f1, <reserved byte>,<2 reserved bytes>,<4 bytes of FCode length>

Note –

If you begin your FCode source with fcode-version1

, the first FCode data is fd

, but if you use fcode-version2

or fcode-version3

, the first

FCode data is f1

If the cause is 2, change your FCode to handle two numbers returned from myaddress

One way to do this is: my-address constant my-bus-addr-mid constant my-bus-addr-low

: my-bus-addr ( -- paddr.low paddr.mid ) my-bus-addr-low my-bus-addr-mid

;

Then use my-bus-addr

in the creation of the " reg

" property.

Helpful Testing and Debugging Hints

56 Writing FCode 3.x Programs —November 1997

Packages

A package is the set of methods and properties that resides in a device node. A

support package is a group of functions or methods that implements a specific interface. A package implements a library of functions that may then be called by FCode programs.

For many devices, this is not particularly useful, but it will be useful for FCode programs that:

•

Implement bootable devices

•

Call functions or properties from other packages

•

Implement functions intended to be called from other packages

A plug-in package is a package that is not permanently resident in the main

OpenBoot PROM. Plug-in packages are written in FCode. Since FCode is represented with a machine-independent binary format, it lets the same plugin packages be used on machines with different CPU instruction sets.

During the linking process, a package’s references to OpenBoot PROM system functions are resolved and the functions defined by the package made available to other parts of OpenBoot . This occurs at run-time, when OpenBoot interprets (probes) the package. Thus, plug-in packages do not need to be prelinked with a particular OpenBoot implementation.

OpenBoot only needs the beginning address of the package in order to probe it.

Once probed, the package becomes a working part of OpenBoot, until the system is reset or turned off. A package exports its interface to OpenBoot, and to other packages, as a vocabulary of Forth words.

Package Instances

Many packages implement a specific interface; a standard set of functions.

Different packages may implement the same interface. For example, there may be two display device driver packages, each implementing the standard display device interface, but for two different display devices.

There may also be multiple instances of a single package. For example, a plugin disk driver may have as many instances as there are disks of that type.

A package consists of:

•

methods (software procedures)

•

properties (externally-visible information describing the package), and

•

data (information used internally by the package).

The active package is the package whose methods are currently visible.

dev and find-device

can be used to change the active package. However, they only make a package’s methods visible; they do not enable the execution of those methods.

Before a package’s methods may be executed, create an instance of the package. Think of an instance as a working copy of the package. An instance contains a working copy of all of the package’s private data.

An instance is created from a package by opening that package. The act of opening a package allocates memory for the instance’s data and sets the contents of that memory to the initial values stored in the package. The instance exists until it is terminated by closing it. When it is closed, the memory used to hold that instance’s private data is freed. Multiple instances may be created from the same package, and exist simultaneously.

The current instance is the instance whose private data and methods are available for direct use (i.e. directly by name without having to use

$call-method

When a package method accesses a data item, it refers to the copy of that data item associated with the current instance. The private data of the current instance is accessible; the private data of all other instances is inaccessible.

Furthermore, to use the methods of a package, an instance of that package must be (at least temporarily) the current instance.

Writing FCode 3.x Programs —November 1997

A package to be opened is described by a device path or device alias. The process of opening the package includes opening each of the nodes in the device path from the root to the specified device (i.e. from the top of the chain to the bottom). As each of these nodes is opened, an instance is created for the node and all of these instances are linked together in an instance chain as shown in Figure 6-1. When a method is accessed using the ihandle of the chain, each node in the chain is able to access the methods of its parent with

$call-parent

using the links provided by the instance chain.

Instance Chain Device Tree

/ ihandle data my-parent data my-parent data my-parent data iommu

/sbus

/SUNW,cgsix

Figure 6-1

An Instance Chain for

/iommu/sbus/SUNW,cgsix

When the chain is no longer needed, the individual instances of the chain may be closed or the entire chain may be closed. When closing the entire chain, the chain is closed from bottom to top to enable a given node’s close

method to use parental methods.

The current instance is a dynamic entity. It is changed in several different ways under several different circumstances. Specifically:

•

When a package is first created, new-device

•

Creates a new device node that is a child of the active package.

•

Makes that new node the active package.

•

Makes that new node’s instance the current instance.

This causes any instance data/methods that are subsequently created (prior to the execution of finish-device

) to be added to this node, and enables their later execution when an instance of this node is made current.

Packages

•

When open-dev

creates an instance chain, the current instance is repeatedly changed as each node of the instance chain is added to the instance chain (i.e. the root of the chain is first made current while it is being added to the instance chain, then the first child node is made current while it is added to the chain, and so on down to the leaf node). Immediately before terminating, open-dev

restores the value in my-self

to the value that my-self

contained prior to the execution of open-dev

open-dev returns the ihandle of the leaf node of the newly-created instance chain. By manipulating the current instance in this way, open-dev

is able to use instance-specific data as required.

•

To execute a method not contained in the current instance,

$call-method

(or one of its derivatives) is used.

$call-method

•

Saves the current value of my-self

•

Stores its ihandle argument in my-self

(thus changing the current instance).

•

Executes the specified method.

•

Restores the saved value of my-self

•

From the user interface, you can change the current instance by setting the value of my-self

directly. This is most useful in a debugging scenario when testing the methods of an opened package. (The select-dev

method discussed in Chapter 4, “Debugging and Testing FCode Programs” resets my-self

for just this purpose.)

If a package is in the node

/packages

$open-package

can be used to create an instance of the package. Unlike packages opened with open-dev

, packages opened with

$open-package

are opened without opening their ancestors.

Each time a package instance is created by

$open-package

, that instance is attached to the one that called

$open-package

. Figure 6-2 shows the modified instance chain that results when the

/iommu/sbus/ledma/le instance opens the obp-tftp

support package using

$open-package

60 Writing FCode 3.x Programs —November 1997

Notice that the only additional instance created is one for the obp-tftp package, and that this instance is linked to the

/iommu/sbus/ledma/le instance. If another instance of obp-tftp

were opened by an instance in another instance chain, the resulting instance of obp-tftp

would have no association with the instance shown in Figure 6-2.

ihandle

Instance Chain data my-parent data data my-parent sbus iommu

Device Tree

/ packages obp-tftp data data data le ledma

Figure 6-2

An Instance Chain for

/iommu/sbus/ledma/le

with obp-tftp

Support

Package Data

Package data is named, read/write RAM storage used by package methods.

Individual data items can be either initialized or zero-filled and either static or instance-specific.

Packages

•

Static data can be accessed at any time, regardless of whether or not the package has been opened. There is only one copy of each static data item, regardless of the number of currently-open instances of that package. The process of opening a package does not in itself alter the values of static data items (although you can, of course, write code to do so explicitly).

•

Instance-specific data can only be accessed when a previously-opened instance of its package is the current instance. The process of opening a package creates copies of its instance-specific data items and establishes their initial values.

•

Zero-filled data items are set to zero when a package is opened.

•

Initialized data items are set to possibly-non-zero initial values when a package is opened. The initial values are established during the creation of the package.

Initialized data items are created by the Forth defining words defer

, value and variable

. Uninitialized data items are created by buffer:

. Preceding the defining word with the Forth word instance

causes the defining word to create an instance-specific item; otherwise it creates a static data item.

Static data items are used for information that applies equally to all instances of the associated package. For example, virtual addresses of shared hardware resources, reference counts and hardware dependent configuration data are often stored as static data.

Instance-specific data items are used for information that differs between instances of the same package. For example, a package that provides a driver for a SCSI host adapter might have several simultaneous instances on behalf of several different target devices; each instance might need to maintain individual state information (e.g. the negotiated synchronous transfer rate) for its target.

Static and Instance-specific Methods

There are several different kinds of package methods, depending on the environment in which they are called and their use of static and instancespecific data.

Static methods do not:

Writing FCode 3.x Programs —November 1997

•

Access instance-specific data either directly or by calling other instancespecific methods.

•

Attempt to call methods of their parent.

Static methods can be called when there is no open instance of their package.

When there is no instance, there is also no parent instance (which is the reason for the prohibition about calling parent methods).

The most important example of static methods is the decode-unit

method which is called by the system during the process of searching the device tree without opening all of the nodes that are encountered.

Instance-specific methods are permitted to:

•

Use instance-specific data

•

Call the methods of their parent.

There is no structural difference between static and instance-specific methods.

The concept of static methods is just a terse way of saying that some methods have to obey the restrictions outlined above. Instance-specific methods are the usual case; the static methods restrictions apply only to a very small set of special-purpose methods.

Execution Tokens

A method is identified by its execution token, xt

. For words in the package being defined, the Forth word

[']

returns an execution token. The execution token is returned by find-method

for other packages. (See the following sections for more details.)

The execution token is used to execute a method in another package, and also to schedule a method for automatic, repeated execution by the system clock interrupt. See the alarm

FCode.

Intra-package Calling Methods

A package can call its own methods directly simply by naming the target method in a Forth colon definition. Such calls require neither a call-time name search nor a change of the current instance. The binding of name to execution behavior occurs at compile time, so subsequent redefinitions of a name do not affect previously-compiled references to old versions of that named method.

Packages

Infrequently, it may be desirable to call a method in the same package so that the name search happens at run-time. To do so, use either

$call-method

or find-method

/ call-package

with my-self

as the ihandle

argument.

(See the next section for details.)

Accessing Other Packages

Packages often use methods of other previously-defined packages. There are two types of packages whose methods can be used directly:

•

The parent of the package being defined.

•

Support packages in the

/packages

node of the device tree.

phandle

and

ihandle

A package definition is identified by its phandle

find-package

returns the phandle

of a package in the

/packages

node. The phandle

can then used to open that support package or to examine its properties. For example:

" deblocker" find-package returns either false

(package not found), or phandle true

Opening a support package with open-package

returns an ihandle

. This ihandle

is used primarily to call the methods of the support package, and to close the support package when it is no longer needed.

The ihandle

of the current instance is returned by my-self

. An instance argument string must be supplied when opening any package (it may be null).

The instance argument string can then be accessed from in the opened package with the my-args

FCode (see below for details). For example (assume that phandle

has already been found):

" 5,3,0" phandle open-package ( ihandle )

If the package cannot be opened, an ihandle

of 0 is returned.

Writing FCode 3.x Programs —November 1997

Name

find-package open-package

$open-package

includes the functions of find-package

and openpackage

. In most cases, it can be used in their place. The primitive functions find-package

and open-package

are rarely used directly, although findpackage

is sometimes used when it’s necessary to examine a support package’s properties without opening it.

The following FCode functions are used to find and open packages (in the

/packages

node):

Table 6-1

Packaage Access FCodes

Stack Diagram

( name-str name-len -- false | phandle true )

( arg-str arg-len phandle -- ihandle | false )

( arg-str arg-len name-addr name-len -- ihandle | false )

Description

Finds the package specified by the string name-str name-len in

/packages

. Returns the phandle of the package, or false if not found.

Opens an instance of the package

phandle. Returns ihandle for the opened package, or false if unsuccessful. The package is opened with an instance argument string specified by arg-str arg-len.

Shortcut word to find and open the package named name-str name-len in

/packages

in one operation.

Returns ihandle for the opened package, or false if unsuccessful.

Here is an example of using

$open-package

" 5,3,0" " deblocker" $open-package ( ihandle | 0 )

Packages

Name

my-self my-parent ihandle>phandle close-package

Table 6-2

Manipulating phandles

and ihandles

Stack Diagram

( -- ihandle )

Description

Return the instance handle of the currently-executing package instance.

( -- ihandle ) Return the instance handle of the parent of the currently-executing package instance.

( ihandle -- phandle ) Convert an instance handle to a package handle

( ihandle -- ) Close a package instance.

Don’t confuse phandle

with ihandle

. Here’s how to use them:

1. Open the package with

$open-package

which returns an

ihandle

2. Use the

ihandle

to call the methods of the package.

3. When done calling the methods of the package, use the

ihandle

to close the instance of the package with

close-package

A package’s phandle

is primarily used to access the package’s properties which are never instance-specific. Use ihandle>phandle

to find the phandle

of an open package.

my-self

and my-parent

return

ihandle s, which can be converted into phandle s with ihandle>phandle

Name

$call-method call-package

Inter-package Calling Methods

The following functions enable the calling of methods of other packages:

Table 6-3

Functions Enabling Calling Other Packages’ Methods

Stack Diagram

( … method-str method-len ihandle -- ??? )

( … xt ihandle -- ??? )

Description

Shortcut word that finds and executes the method

method-str method-len in the package instance

ihandle.

Executes the method xt in the instance ihandle.

66 Writing FCode 3.x Programs —November 1997

Name

$call-paren executedevice-method find-method

Table 6-3

Functions Enabling Calling Other Packages’ Methods

Stack Diagram

( … method-str method-len -- ??? )

( … dev-str dev-len method-str method-len

-- … false | ??? true )

( method-str method-len phandle

-- false | xt true )

Description

Executes the method method-str method-len in the parent’s package instance. Identical to calling my-parent $call-method

Executes the method method-str method-len in the package named dev-str dev-len. Returns false if the method could not be executed.

Finds the method named method-str method-len in the package phandle. Returns false if not found.

$call-parent

is used most-often, but is the least flexible of the above methods; it is exactly equivalent to the sequence

“ my-parent $call-method

”. Most inter-package method calling involves calling the methods of one’s parent;

$call-parent

conveniently encapsulates the process of doing so.

$call-method

can call methods of non-parent packages. It is most commonly used for calling methods of support packages. The ihandle argument of

$call-method

identifies the package instance whose method is to be called.

For example:

$call-parent

$open-package $call-method

Both

$call-parent

and

$call-method

identify their target method by name. The method-str method-len arguments denote a text string that

$callparent

$call-method

uses to search for a method of the same name in the target instance’s list of methods. Obviously, this run-time name search is not as fast as directly executing a method whose address is already known.

However:

1. Most packages have a relatively small number of methods,

2. Systems typically implement a reasonably-efficient name search mechanism, and

3. Inter-package calls tend to occur relatively infrequently.

Packages

Consequently, the length of time spent searching is usually not a limiting factor.

A more complete example demonstrates the use of

$open-package

and

$call-method

: add-offset ( x.byte# -- x.byte#' )

my-args " disk-label" $open-package( ihandle )

" offset" rot ( name-addr name-len ihandle )

$call-method

;

When method name search time is a limiting factor, use find-method

to perform the name search once. Then use call-package

repetitively thereafter.

find-method

returns, and call-package

expects, an execution

token by which a method can be called quickly.

A more complex example that is somewhat faster if called repeatedly:

0 value label-ihandle \ place to save the other package’s ihandle

0 value offset-method \ place to save found method's xt

: init ( -- )

my-args " disk-label" $open-package ( ihandle ) to label-ihandle

" offset" label-ihandle ihandle>phandle ( name-addr name-len phandle)

find-method if

( xt ) to offset-method

else ." Error: can't find method"

then

;

: add-offset ( d.byte# -- d.byte#' )

offset-method label-ihandle call-package

;

Because device access time often dominates I/O operations, the benefit of this extra code probably won’t be noticed. It is only justified if the particular method will be called often.

Writing FCode 3.x Programs —November 1997

Another use of find-method

is to determine whether or not a package has a method with a particular name. This allows you to add new methods to an existing package interface definition without requiring version numbers to denote which new or optional methods a package implements.

With

$call-method

and

$call-parent

, the method name search is performed on every call. Consequently, if a new method (either one with a new name or with the same name as a previously-existing name) is created, any subsequent uses of

$call-method

$call-parent

naming that method will find the new one. On the other hand, find-method

binds a name to an execution token and subsequent redefinitions of that name do not affect the previous execution token, so subsequent uses of

$call-method

continue to call the previous definition. In practice, this difference is rarely important, since it is quite unusual for new methods to be created when a package is already open. The one case where methods are routinely redefined under these circumstances is when a programmer does it explicitly during a debugging session; making such redefinitions is a powerful debugging technique.

All of the method calling functions described above change the current instance to the instance of the callee for the duration of the call, restoring it to the instance of the caller on return.

execute-device-method

and

apply

In addition to the inter- and intra-package method calling techniques just described, there is another way of calling methods.

execute-device-method

and its variant apply

allow a user to invoke a method of a particular package as a self-contained operation without explicitly opening and closing the package as separate operations.

execute-device-method

first opens all the package’s parents, then calls the named method, and then closes all the parents.

apply

performs the same functions as execute-device-method

, but it takes its arguments from the command line instead of from the Forth stack.

execute-device-method

and apply

are most often used for methods like selftest

selftest

methods are usually called with the test

user interface command, which is usually implemented with execute-device-method

Methods that are intended to be called with execute-device-method

or its equivalent must not assume that the package’s open

method has been called, because execute-device-method

does not call the open

method of the

Packages

package containing the target method although it opens all of the package’s parents. Consequently, the target method must explicitly perform whatever initialization actions it requires, perhaps by calling the open

method in the same package, or by executing some sub-sequence thereof. Before exiting, the target method must perform the corresponding close

actions to undo its initialization actions.

execute-device-method

was intentionally designed not to call the target’s open

and close

methods automatically since the complete initialization sequence of open

is not always appropriate for methods intended for use with execute-device-method

. In particular, an open

method usually puts its device in a fully operational state, while methods like selftest

often need to perform a partial initialization of selected device functions.

Plug-in Device Drivers

Plug-in device drivers are plug-in packages implementing simple device drivers.

The interfaces to these drivers are designed to provide basic I/O capability.

Plug-in drivers are used for such functions as booting the operating system from a device or displaying text on a device before the operating system has activated its own drivers. Plug-in drivers are added to the device tree during the probing phase of the OpenBoot PROM start-up sequence.

Plug-in drivers must be programmed to handle portability issues, such as hardware alignment restrictions and byte ordering of external devices. With care, you can write a driver so that it is portable to all of the systems in which the device could be used.

Plug-in drivers are usually stored in PROM located on the device itself, so that the act of installing the device automatically makes its plug-in driver available to the OpenBoot PROM.

For devices with no provision for such a plug-in driver PROM, the plug-in driver can be located elsewhere, perhaps in PROM located on a different device or in an otherwise unused portion of the main OpenBoot PROM.

However, use of such a strategy limits such a device to certain systems and/or system configurations.

70 Writing FCode 3.x Programs —November 1997

Common Package Methods

Different packages have different collections of methods depending on the job(s) that the packages have to do. The following four methods are found in many device drivers. None of them can be considered to be required, however, since the nature of a given driver governs the methods that the driver needs.

open

and close

are found in many drivers, but even they are not universally required.

open

and close

are needed only if the device will be used with open-dev

or another method that calls open-dev

. Any device that has read and/or write

methods needs open

and close

, as does any parent device whose children could possibly be opened.

Another way of looking at this is that open

and close

are needed for devices that are used to perform a series of related operations distributed over a period of time, relative to some other calling package.

open

initializes the device state that is maintained during the series of later operations, and close

destroys that state after the series is complete.

To illustrate, a series of write

calls generated by another package is such a series. Conversely, selftest

is not such a series; selftest

happens

“atomically” as an indivisible self-contained operation.

Basic Methods open

( -- ok? )

Prepares a package for subsequent use.

open

typically allocates resources, maps, initializes devices, and performs a brief sanity check (making no check at all may be acceptable).

true

is returned if successful, false

if not. When open

is called, the parent instance chain has already been opened, so this method may call its parent’s methods.

close

( -- )

Packages

Restores a package to its “not in use” state.

typically turns off devices, unmaps, and de-allocates resources.

is executed before the package’s parent is closed, so the parent’s methods are available to close

. It is an error to close a package which is not open.

Recommended Methods

The following methods are highly recommended.

reset

( -- )

Put the package into a “quiet” state.

reset

is primarily for packages that do not automatically assume a quiet state after a hardware reset, such as devices that turn on with interrupt requests asserted.

selftest

( -- error# )

Test the package.

selftest

is invoked by the OpenBoot test

word. It returns

0 if no error is found or a package-specific error number if a failure is noticed.

test

does not open the package before executing selftest

, so selftest

is responsible for establishing any state necessary to perform its function prior to starting the tests, and for releasing any resources allocated after completing the tests. There should be no user interaction with selftest

, as the word may be called from a program with no user present.

If the device was already open when selftest

is called, a new instance will still be created and destroyed. A well-written selftest

should handle this possibility correctly, if appropriate.

If the device is already open, but it is not possible to perform a complete selftest without destroying the state of the device, the integrity of the open device should take precedence, and the selftest process should test only those aspects of the device that can be tested without destroying device state. The inability to fully test the device should not be reported as an error result; an error result should occur only if selftest

actually finds a device fault.

Writing FCode 3.x Programs —November 1997

The "device already open" case happens most commonly for display devices, which are often used as the console output device, and thus remain open for long periods of time. When testing a display device that is already open, it is not necessary to preserve text that may already be on the screen, but the device state should be preserved to the extent that further text output can occur and be visible after selftest

exits. Any error messages that are displayed by the selftest method will be sent to the console output device, so when testing an already-open display device, such error messages should be avoided during times when selftest

has the device in a state where it is unable to display text.

selftest

is not executed in an open/close pair. When selftest

executes, a new instance is created (and destroyed). It will have its own set of variables, values, and so forth. These quantities are not normally shared with an instance opened with the normal open

routine for the package.

Note –

selftest

should be written to do its own mapping and unmapping.

Package Data Definitions

The following examples show how to create static data items: variable bar

5 value grinch defer stub create ival x , y , z ,

7 buffer: foo ival foo 7 move \ One way to initialize a buffer

The data areas defined above are shared among all open instances of the package. If a value is changed, for instance, the new value will persist until it is changed again, independent of the creation and destruction of package instances.

Any open instance of a package can access and change the value of a static data item, which changes it for all other instances.

Packages

The following examples show how to create instance-specific data items, whose values are not shared among open instances: instance variable bar

5 instance value grinch instance defer stub

7 instance buffer: foo

Instance-specific data areas are re-initialized when a package instance is created (usually by opening the package), so each instance gets its own copy of the data area. For example, changes to bar in one instance will not affect the contents of it in another instance. (Note that create

operates across all the instances, and cannot be made instance-specific.)

The total amount of data space needed for a package’s instance-specific data items is remembered as part of the package definition when finish-device finishes the package definition. Also, the contents of all the variable s, value s, and defer s at the time finish-device

executes are stored as part of the package definition.

An instance of the package is created when that package is opened. Data space is allocated for that instance (the amount of which was remembered in the package definition). The portion of that data space created with variable

, value

, or defer

is initialized from the values stored in the package definition.

Data space created with buffer:

is set to zero.

You can add new methods and new properties to a package definition at any time, even after finish-device

has been executed for that package. To do so, select the package and create definitions or properties.

However, you cannot add new data items to a package definition after finish-device

has been executed for that package.

finish-device

sets the size of the data space for that package, and subsequently the size is fixed.

Instance Arguments and Parameters

An instance argument

(my-args)

is a string that is passed to a package when it is opened. The string may contain parameters of any sort, based on the requirements of the package, or may simply be a null-string if no parameters are needed. A null string can be generated with either

" "

0 0

74 Writing FCode 3.x Programs —November 1997

The instance argument passed can be accessed from inside the package with the my-args

FCode.

Note –

A package is not required to inspect the passed arguments.

If the argument string contains several parameters separated by delimiter characters, you can extract the subsections from the package with leftparse-string

. You can use any character as the delimiter; a comma is commonly used for this.

Note –

Avoid using blanks or the / character, since these will confuse the parsing of pathnames.

A new value for my-args

is passed when a package is opened. This can happen under a number of circumstances:

1. The my-args

string will generally be null when FCode on a Plug-in card is interpreted automatically by the OpenBoot system at power-on.

2. The my-args

string is set by a parameter to begin-package

, which is used to set up the device tree when Forth source code is downloaded and interpreted interactively.

3. The my-args

string can be set with set-args

before a particular slot is probed, if probing is being controlled from nvramrc

The above three instances happen only once, when the package FCode is interpreted for the first time. If you want to preserve the initial value for my-args

, the FCode program should copy it into a static buffer to preserve the information.

Whenever a package is re-opened, a new value for my-args

is supplied. The method for supplying this new value depends on the method used to open the package, as described below.

•

The instance argument ( my-args

) is supplied as a string parameter to the commands open-package

$open-package

Packages

•

User Interface commands, such as open-dev

, execute-device-method and test

, supply the entire pathname to the device being opened. This approach lets an instance argument be included in the pathname. For example, to open the SBus device

SUNW,bwtwo

with the argument string

5,3,0

, enter: ok " /sbus/SUNW,bwtwo:5,3,0" open-dev ok

Here is a more complicated (and fictitious) example: ok " /sbus/SUNW,fremly:test/grumpin@7,32:print/SUNW,fht:1034,5" ok open-dev ok

Here the string test

is passed to the

SUNW,fremly

package as it is opened, the string print

is passed to the grumpin

package as it is opened, and the string

1034,5

is passed to the

SUNW,fht

package as it is opened.

Package Addresses

A package’s address relative to its parent package is another piece of information available to a package. Again, there are two main ways to pass this address to the package:

•

Part of the pathname of the package

•

A string parameter given to the probe words

As an example of the first method, suppose the following package is being opened: ok " /sbus/esp/sd@3,0:b" open-dev

Then the address of the

/sd

package relative to the

/esp

package is

3,0

Writing FCode 3.x Programs —November 1997

The package can find its relative address with my-unit

, which returns the address as a pair of numbers. The first number (high) is the number before the comma in the example above, and the second number (low) is the number after the comma. Note that these are numbers, not strings.

As an example of the second method, suppose a test version of an FCode package is being interpreted: ok 0 0 " 3,0" " /sbus" begin-package

Here the my-args

parameters for the new FCode are null, the initial address is

3,0

and it will be placed under the

/sbus

node.

The initial address can be obtained through my-address

and my-space

Typically, you use my-space

and my-address

(plus an offset) to create the package’s

"reg"

property, and also to map in needed regions of the device.

Package Mappings

Mappings set up by a package persist across instances unless they are explicitly unmapped. It is usually best for each new instance to do its own mappings, being sure to unmap resources as they are no longer needed.

nvramrc

Machines that support packages will generally also support the nvramrc facility.

nvramrc

is a special area in the

NVRAM

that can contain user interface commands to be executed by OpenBoot as the machine powers on. These commands can be used to specify behavior during start up or to define changes for later execution.

Packages

For example: assume a card in SBus slot #2 (named

XYZ,me

) needs custom attributes set by the user.

nvramrc

contents would include: probe-all dev /sbus/XYZ,me

" type5" encode-string " xyzmode" property device-end install-console banner

After editing nvramrc

, turn on the NVRAM parameter use-nvramrc?

and reset the machine to activate the contents of nvramrc

. See nvedit in

Chapter 14, “FCode Dictionary” for more about editing nvramrc

contents.

Modifying Package Properties

To modify the properties of a package, first probe the package to get it into memory, then create or modify properties by executing property

or one of its short-hand forms. Normally, probing is done automatically after the nvramrc commands are executed.

See Chapter 7, “Properties“, for more information about properties.

Standard Support Packages

The

/packages

node of the device tree is unique. It has children, but instead of describing a physical bus,

/packages

serves as a parent node for support packages. The children of

/packages

are general-purpose software packages not attached to any particular hardware device. The “physical address space” defined by

/packages

is a trivial one: there are no addresses. Its children are distinguished by name alone.

The children of

/packages

are used by other packages to perform commonly used functions. They may be opened with the FCodes open-package

$open-package

, and closed with close-package

. IEEE Standard 1275-1994 defines three support packages that are children of

/packages

78 Writing FCode 3.x Programs —November 1997

Sun Disk-Label Support Package

Disk (block) devices are random-access, block-oriented storage devices with fixed-length blocks. Disks may be subdivided into several logical partitions, as defined by a disk label—a special disk block, usually the first one, containing information about the disk. The disk driver is responsible for appropriately interpreting a disk label. The driver may use the standard support package

/disk-label

if it does not implement a specialized label.

/disk-label

interprets a standard Sun disk label, reading any partitioning information contained in it. It includes a first-stage disk boot protocol for the standard label.

load

is the most important method defined by this package.

This package uses the read

and seek

methods of its parent (in practice, the package which opens this one to use the support routines).

/disk-label defines the following methods:

Packages

Name

open close load offset

Table 6-4

Sun Disk Label Package Methods

Stack

Diagram

( -- flag )

Description

Reads and verifies the disk label accessed by the read

and seek methods of its parent instance. Selects a disk partition based on the text string returned by my-args

. For the standard Sun disk label format, the argument is interpreted as follows:

Argument Partition

<none> a or A b or B

...

h or H 7

Returns -1 if the operation succeeds. As a special case, if the argument is the string “ nolabel

”, open

returns -1 (success) without attempting to read or verify the label.

( -- )

( adr -- size )

Frees all resources that were allocated by open

Reads a stand-alone program from the standard disk boot block location for the partition specified when the package was opened. Puts the program at memory address adr

, returning its length size. For the standard Sun disk format, the stand-alone program is 7.5K bytes beginning 512 bytes from the start of the partition.

( x.rel-- x.abs ) Returns the 64-bit absolute byte offset x.abs

corresponding to the 64bit partition-relative byte offset x.rel

. In other words, adds the byte location of the beginning of the selected partition to the number on the stack.

TFTP Booting Support Package

The

/obp-tftp

package implements the Internet Trivial File Transfer Protocol

(TFTP) for use in network booting. It is typically used by a network

device driver for its first stage network boot protocol. Again, load

is the most important method defined by this package.

Writing FCode 3.x Programs —November 1997

Name

open close load

This package uses the read

and write

methods of its parent, and defines the following methods:

Table 6-5

TFTP Package Methods

Stack

Diagram Description

(-- flag) Prepares the package for subsequent use, returning -1 if the operation succeeds and 0 otherwise.

Frees all resources that were allocated by open

( -- )

( adr -- size ) Reads the default stand-alone program from the default

TFTP

server, putting the program at memory address adr and returning its length size. For the standard Sun

TFTP

booting protocol,

RARP

(Reverse Address Resolution Protocol) is used to acquire the

address corresponding to the system’s

MAC

address (equivalent to its Ethernet address). From the

address, the default file name is constructed, of the form <Hex-IP-Address>.<architecture> (for example,

C0092E49.SUN4C

). Then obp-tftp

tries to

TFTP

read that file, first trying the server that responded to the

RARP

request, and if that fails, then broadcasting the

TFTP

read request.

Name

open close

Deblocker Support Package

The

/deblocker

package makes it easy to implement byte-oriented device methods, using the block-oriented or record-oriented methods defined by devices such as disks or tapes. It provides a layer of buffering between the high-level byte-oriented interface and the low-level block-oriented interface.

/deblocker

uses the max-transfer

, block-size

, read-blocks

and write-blocks

methods of its parent, and defines the following methods:

( -- )

Table 6-6

Deblocker Package Methods

Stack Diagram

( -- flag )

Description

Prepares the package for subsequent use, allocating the buffers used by the deblocking process based on the values returned by the parent instance’s max-transfer

and block-size

methods. Returns -1 if the operation succeeds, 0 otherwise.

Frees all resources that were allocated by open

Packages

Name

read write seek

Table 6-6

Deblocker Package Methods

Stack Diagram

( adr len -- actual ) Reads at most len bytes from the device into the memory buffer beginning at adr

. Returns actual

, the number of bytes actually read, or 0 if the read operation failed. Uses the parent’s read-blocks

method as necessary to satisfy the request, buffering any unused bytes for the next request.

( adr len -- actual )

Description

Writes at most len

bytes from the device into the memory buffer beginning at adr

. Returns actual

, the number of bytes actually read, or 0 if the write operation failed. Uses the parent’s write-blocks

method as necessary to satisfy the request, buffering any unused bytes for the next request.

( x.position -- flag )

Sets the device position at which the next read

or write

will take place.

The position is specified by the 64-bit number x.position

. Returns 0 if the operation succeeds or -1 if it fails.

82 Writing FCode 3.x Programs —November 1997

Properties

This chapter describes characteristics of hardware devices, software and user selections. Properties are associated with the device node in which they are created and are accessible both by OpenBoot routines and by client programs.

Properties can be inspected and, in some cases, modified.

Each property has a property name and a property value.

•

Property names are human-readable strings consisting of one to 31 printable, lower-case letters and symbols not including blanks, “/”, “\”, “:”,

“[“, “]” or “@”. Property names beginning with “+” are reserved for future use by IEEE Standard 1275-1994.

•

Property values specify the contents, or value, of a particular property. The value is an array of bytes that may be used to encode integer numbers, text strings, or other forms of information.

Properties are accessed by name. Given a property’s name, it is possible to determine whether that property has been defined and, if so, what its value is.

Property values are encoded as arrays of zero or more bytes for portability across machine architectures. The encoding and decoding procedures are defined by IEEE Standard 1275-1994. The encoding format is independent of hardware byte order and alignment characteristics. The encoded byte order is big-endian and the bytes are stored in successive memory locations without any padding.

The format of the property value array associated with a given property name is specific to that property name. There are five basic types of property value array formats:

•

Flag

Since property value arrays may be of zero length, properties may convey

“true” or “false” information by their presence or absence.

•

Byte

An array of 1 or more bytes is stored in a property value array as a series of sequential bytes in the property value array.

•

32-bit integer

A 32-bit integer is stored in a property value array in four successive bytes.

The most significant byte of the integer in the next available address in the property value array is followed by the high middle, low middle and least significant bytes of the integer (in other words, in big-endian format).

•

Text string

A text string of n printable characters is stored in a property value array in n+1 successive locations by storing the string in the first n locations followed by a byte of zero value (in other words, a null terminated string).

•

Composite

A composite value is made up of the concatenation of encoded bytes, encoded 32-bit integers and/or encoded strings. Each such primitive is stored immediately after the preceding primitive with no intervening space

(in other words, the items are packed). Here are examples of composite values: a. physical address range. Encoded as 4 integers: phys.lo phys.mid phys.hi size b. array. The concatenation of n items of some type.

The standard defines a number of standard properties with specified names and value formats. If a package uses one of these standard properties then the value format of the property must be as defined by the standard. Packages may define other properties whose names do not conflict with the list of standard properties. Such newly defined properties may have any value format.

Writing FCode 3.x Programs —November 1997

Properties may be created by FCode programs. The CPU’s OpenBoot is able to use property names that tell it such things as the device type (e.g. disk, tape, network, display, and so on) to determine how to use the device (if at all) during the boot process.

Solaris recognizes other property names that give information for configuring the operating system automatically. These properties include the driver name, the addresses and sizes of the device’s registers, and interrupt levels and interrupt vectors used by the device.

Other properties may be used by individual operating system device drivers.

The names of such properties and the interpretation of their values is subject to agreement between the writers of the FCode programs and the operating system driver, but may otherwise be arbitrarily chosen. For example, a display device might declare width, height, and depth properties to allow a single operating system driver to automatically configure itself for one of several similar but different devices.

A package’s properties identify the characteristics of the package and its associated physical device, if any. You can create a property either with the property

FCode, or with the name

, reg

, model

, and device-type

FCodes, described below.

For example, a frame buffer package might export its register addresses, interrupt levels, and frame buffer size. Every package has an associated property list, which is arbitrarily extensible. The user interface command

.properties

displays the names and values of the current node’s properties.

For example, if a property named foo

is created in a device node which already has a property named foo

, the new property supersedes the old one.

New properties can be added during the lifetime of a product. For backward compatibility, an FCode or device driver program that needs the value of a particular property should determine whether or not the property exists, and if not the program should supply its own default value.

Standard FCode Properties

IEEE Standard 1275-1994 defines the following standard properties. A package should never create any property using any of the following names, unless the defined meanings and structures are used.

Properties

Standard Property Names

This group of properties applies to all device nodes regardless of type. The name

property is required in all packages. The remaining properties are optional.

name reg device_type model interrupts address compatible status

Name of the package.

Package’s registers.

Characteristics that the device is expected to have.

Manufacturer’s model number.

Interrupts used by the device.

Virtual addresses of one or more memory-mapped regions of the device.

List of devices with which this device is compatible.

Operational status of the device.

Display Device Properties

Display devices include bit-mapped frame buffers, graphics displays and character-mapped displays. Display devices are typically used for console output. The following properties are specific to display devices: character-set depth height linebytes width big-endian-aperture little-endian-aperture

Character set (e.g. ISO8859-1).

Number of bits in each pixel of the display.

Number of pixels in the “y” direction of the display.

Number of pixels between consecutive scan lines of the display.

Number of pixels in the “x” direction of the display.

The big-endian aperture of the frame buffer.

The little-endian aperture of the frame buffer.

Writing FCode 3.x Programs —November 1997

Network Device Properties

Network devices are packet-oriented devices capable of sending and receiving

Ethernet packets. Network devices are typically used for booting.

mac-address address-bits

Last used network address.

Number of address bits needed to address this device on the physical layer.

max-frame-size

Maximum packet size that the device can transmit at one time.

Memory Device Properties

Memory devices are traditional random-access memory, suitable for temporary storage of data.

reg

Physical addresses installed in the system.

available

Regions of physical addresses that are currently unallocated by OpenBoot.

General Properties For Parent Nodes

#address-cells

Device node’s address format.

#size-cells

Number of cells that are used to encode the size field of a child’s reg property.

ranges

Relationship between the physical address spaces of the parent and child nodes.

Properties

Properties For PCI Parent Nodes

#address-cells

The value of this property for a PCI bus node is 3.

#size-cells device_type reg

The value of this property for a PCI bus node is 2, reflecting the 64-bit address space of PCI.

The value of this property for a PCI bus node is " pci

For nodes representing PCI-to-PCI bridges, the value denotes the configuration space address of the bridges's configuration registers. The format is the same as that for PCI child nodes.

For nodes representing bridges from some other bus to PCI, the format is as defined for the other bus.

bus-range slot-names

Specifies the range of bus numbers controlled by this PCI bus.

Describes the external labeling of add-in slots.

Properties for PCI Child Nodes

The following definitions are specified by the PCI Bus Binding to IEEE

Standard 1275-1994.

reg interrupts alternate-reg

This standard property is mandatory for PCI Child nodes.

The presence of this property indicates that the function represented by this node is connected to a PCI expansion connector's interrupt line.

Defines alternate access paths for addressable regions.

has-fcode

The presence of this property indicates that this node was created by the evaluation of an FCode program.

assigned-addresses

Defines the configuration space's base address and size.

power-consumption

Describes the device's maximum power consumption categorized by the various power rails and the device's power-management state.

Each of the following PCI child node properties is created during the probing process, after the device node has been created, and before evaluating the device's FCode (if any). The property values are those found in the standard

PCI configuration registers.

Writing FCode 3.x Programs —November 1997

Unless otherwise specified, each of the following properties has a property value created by encoding the value contained in the associated hardware register with encode-int

•

"vendor-id"

•

"device-id"

•

"revision-id"

•

"class-code"

•

"interrupts"

This property is present only if the interrupt pin register is non-zero.

•

"min-grant"

•

"max-latency"

•

"devsel-speed"

•

"fast-back-to-back"

This property is present only if the fast-back-to-back bit (Bit 7) of the function's status register is set.

Detailed Descriptions of Standard Properties

#address-cells

Applies only to bus nodes. It specifies the number of cells that are used to represent a physical address with a bus’ address space.

The value for SBus nodes is 2, for PCI bus nodes is 3.

#size-cells

Applies only to bus nodes. It specifies the number of cells used to represent the length of a physical address range (in other words, the size field of a child’s reg property).

The value for SBus nodes is 1, for PCI bus nodes is 2.

Properties

address

Declares currently-mapped device virtual addresses. It is generally used to declare large regions of existing mappings in order to enable the operating system device driver to re-use those mappings, thus conserving system resources. This property should be created after virtual addresses have been assigned by mapping operations. Should be deleted when the corresponding virtual addresses are unmapped.

The property value is an arbitrary number of virtual addresses. The correspondence between declared addresses and the set of mappable regions of a particular device is device-dependent.

-1 value my-buffers

-1 value my-dma-addr

: map-me ( -- )

my-address my-space 1.0000 " map-in" $call-parent ( virt1 )

to my-buffers

2000 " dma-alloc" $call-parent ( virt2 ) to my-dma-addr

my-buffers encode-int my-dma-addr encode-int encode+

" address" property

;

: unmap-me ( -- )

my-dma-addr 2000 " dma-free" $call-parent

my-buffers 1.0000 " map-out" $call-parent

" address" delete-property

;

address-bits

When declared in network devices, indicates the number of address bits needed to address this device on its network. Used as: d# 48 encode-int " address-bits" property

See also: property

and Chapter 11, “Network Devices”.

Writing FCode 3.x Programs —November 1997

alternate-reg

This property describes alternative access paths for the addressable regions described by the

"reg"

property. Typically, an alternative access path exists when a particular part of a device can be accessed either in memory space or in

I/O space, with a separate base address register for each of the two access paths. The primary access paths are described by the

"reg"

property and the secondary access paths, if any, are described by the alternate-reg

property.

If no alternative paths exist, the alternate-reg

property should not be defined. If the device has alternative access paths, each entry (in other words, each phys-addr size pair) of its value represents the secondary access path for the addressable region whose primary access path is in the corresponding entry of the

"reg"

property value. If the number of alternate-reg

entries exceeds the number of

"reg"

property entries, the additional entries denote addressable regions that are not represented by

"reg"

property entries, and are thus not intended to be used in normal operation; such regions might, for example, be used for diagnostic functions. If the number of alternate-reg entries is less than the number of

"reg"

entries, the regions described by the extra

"reg"

entries do not have alternative access paths. An alternate-reg entry whose phys.hi component is zero indicates that the corresponding region does not have an alternative access path; such an entry can be used as a placeholder to preserve the positions of later entries relative to the corresponding

"reg"

entries. The first

alternate-reg

entry, corresponding to the

"reg" entry describing the function's configuration space registers, has a phys.hi component of zero.

The property value is an arbitrary number of (phys-addr, size) pairs where:

•

phys-addr is (phys.lo phys.mid phys.hi), encoded with encode-phys

•

size is a pair of integers, each encoded with encode-int

. The first integer denotes the most-significant 32 bits of the 64-bit region size and the second integer denotes the least-significant 32 bits thereof.

assigned-addresses

This property describes the location and size of regions of physical address space that are specified in the device's configuration space base address registers.

The property value is zero to six (phys-addr, size) pairs where:

Properties

•

phys-addr is (phys.lo phys.mid phys.hi), encoded with encode-phys

•

size is a pair of integers, each encoded with encode-int

. The first integer denotes the most-significant 32 bits of the 64-bit region size and the second integer denotes the least-significant 32 bits thereof.

Each entry (in other words, (phys-addr, size) pair) in this property value corresponds to one (or two in the case of 64-bit-address memory space) of the function's configuration space base address registers. The entry indicates the physical address that has been assigned to that base address register, and the size in bytes of the assigned region. The size is a power of two (since the structure of PCI base address registers forces the decoding granularity to powers of two). Please see the glossary entry for this property for a complete description of the formatting details.

Note –

There is no implied correspondence between the order of entries in the

"reg"

property value and order of entries in the assigned-addresses property value. The correspondence between the

"reg"

entries and assigned-addresses

entries is determined by matching the fields denoting the base address register.

available

Defines the resources that are managed by this package (in other words,

/memory

/mmu

) that are currently available for use by a client program.

The property value is an arbitrary number of (phys-addr, length) pairs where:

phys-addr is a phys.lo phys.mid phys.hi list of integers encoded with encodeint

•

length (whose format depends on the package) is one or more integers, each encoded with encode-int

big-endian-aperture

This property is associated with display devices. Encoded identically to

"reg" for the corresponding bus, the property value contains the address of the bigendian aperture of the frame buffer (in other words, the address range through which the frame buffer can be addressed in big-endian mode).

Writing FCode 3.x Programs —November 1997

bus-range

This property specifies the range of bus numbers controlled by this PCI bus.

The property value is two integers, each encoded with encode-int

. The first integer represents the bus number of the PCI bus implemented by the bus controller represented by this node. The second integer represents the largest bus number of any PCI bus in the portion of the PCI domain that is subordinate to this node.

big-endian-aperture

Associated with display

devices. Encoded identically to reg

for the corresponding bus, the property value contains the address of the big endian

“aperture” of the frame buffer (i.e. the address range through which the frame buffer can be addressed in big-endian mode).

character-set

When declared in display or serial devices, indicates the recognized character set for this device. The property value is a text string.

A typical value is “

ISO8859-1

”. 8859-1 is the number of the ISO specification for that particular character set, which essentially covers the full range of western European languages. To get a list of possible values, consult the X registry for which there is an address in the X11R5 documentation.

Used as:

" ISO8859-1" encode-string " character-set" property

See also: property

, Chapter 9, “Display Devices” and Chapter 12, “Serial

Devices”.

class-code

This property contains the value of the class code register from the configuration space header. This register identifies the generic function of the device and (in some cases) a specific register-level programming interface.

Properties

compatible

This property specifies a list of devices with which this device is compatible.

The property is typically used by client programs to determine the correct driver to use with the device in those cases where the client program does not have a driver which matches the " name

" property.

The property value is the concatenation (with encode+

) of an arbitrary number of text strings (encoded with encode-string

) wherein each text string follows the formatting conventions as described for the " name

" property.

Note –

Reccommended practice document on the topic “Generic Names” is available on the Open Firmware Workink Group’s homepage. Recommended practice documents can be obtained as described in “Related Books” in the

Preface.

class-code

The property value is the register's value encoded with encode-int

See also: PCI Local Bus Specification.

Contains the value of the “Class Code” register from the Configuration Space header. That register identifies the generic function of the device and (in some cases) a specific register-level programming interface.

The property value is the register’s value encoded with encode-int

depth

Associated with display

devices. Encoded with encode-int

, the property value specifies the number of bits in each pixel of the display.

Writing FCode 3.x Programs —November 1997

device-id

This property contains the value of the device ID register from the configuration space header. That register identifies the particular device. The encoding of the register is determined by the device vendor.

The property value is the register's value encoded with encode-int

See also: PCI Local Bus Specification.

device-id

Contains the value of the “Device ID” register from the Configuration Space header. That register identifies the particular device. The encoding of the register is determined by the device vendor.

The property value is the register’s value encoded with encode-int

device_type

Declares the type of this plug-in device. The type need not be declared, unless this device is intended to be used for booting. If this property is declared, using one of the following key values, the FCode program must follow the required conventions for that particular type of device, by implementing a specified set of properties and procedures (methods). Used as:

" display" encode-string " device_type" property

Properties

Device Type

block byte display memory network pci serial

Defined values for this property are:

Table 7-1

Standard Device Types

Device Characteristics

Random-access, block-oriented device, such as a disk drive, usable as a boot file source. See

Chapter 8, “Block and Byte Devices” for the requirements of this type of device.

Random-access, byte-oriented device, such as a tape drive, usable as a boot file source. See

Chapter 8, “Block and Byte Devices” for the requirements of this type of device.

Frame buffer or other similar display device, usable for message display during booting. See

Chapter 9, “Display Devices” for the requirements of this type of device

Random-access memory device. See IEEE Standard 1275-1994 for the requirements of this type of device.

Packet-oriented network device, such as Ethernet, can be used as a boot file source. See Chapter 11,

“Network Devices” for the requirements of this type of device.

A PCI bus node to which PCI plug-in devices can be attached. See Chapter 10, “Memory-Mapped

Buses” for the requirements of this type of device.

Byte-oriented device, such as a serial port, usable for console input and/or console output. See

Chapter 12, “Serial Devices” for the requirements of this type of device.

devsel-speed

Contains the value of the “DEVSEL timing” field (Bits 9-10) of the “Status” register from the Configuration Space header. This field describes the timing of the DEVSEL# output of the device.

The property value is the register’s value encoded with encode-int

. A value of 0 indicates fast, 1 indicates medium and 2 indicates slow timing.

existing

Specifies all of the regions physical addresses actually installed in the system.

96 Writing FCode 3.x Programs —November 1997

fast-back-to-back

This property should be present only if the fast back-to-back capable field (Bit

7) is set in the status register from the configuration space header. That field indicates whether the device is capable of accepting fast back-to-back transactions when the transactions are not to the same agent.

See also: PCI Local Bus Specification.

has-fcode fast-back-to-back

Should be present only if the “Fast Back-to-Back Capable” field (Bit 7) is set in the status register from the Configuration Space header. That field indicates whether the device is capable of accepting fast back-to-back transactions when they are not to the same agent.

See also: PCI Local Bus Specification.

has-fcode

This property should be present only if this device node creation involved

FCode program evaluation, as opposed to being completely automatically created from information in configuration registers.

Should be present only if the creation of this device node involved the evaluation of an FCode program rather than automatic creation from information in configuration registers.

height

Associated with display

devices. Encoded with encode-int

, the property value specifies the number of displayable pixels in the “y” direction of the display.

Properties

interrupts

This optional property declares the interrupt level(s) for this plug-in device.

The contents are one or more integers. Note that the bus-level interrupt (not the CPU-level interrupt) is specified.

For SBus devices, SBus interrupt levels 1-7 are allowed. The correct choice for your interrupt level will depend on your latency requirements. Typical usage is: video - SBus level 5, Ethernet - SBus level 4, SCSI and DMA - SBus level 3.

SBus levels 6 and 7 should only be used with great care, otherwise significant system performance degradation may occur.

Because of previous usage of the intr

property instead of the interrupts property in earlier systems, we recommend that both intr

and interrupts be declared in FCode for SBus cards. However, cards which only declare intr should continue to work, as current systems automatically generate the interrupts

property for you as required.

To declare a single interrupt (level 5), used as:

5 encode-int “ interrupts” property

To declare two interrupts (levels 3 and 5), used as:

5 encode-int 3 encode-int encode+ “ interrupts” property

linebytes

Associated with display devices. Encoded with encode-int

, the property value specifies the number of pixels between consecutive scan lines of the display.

Properties

100

little-endian-aperture

This property is associated with display devices. Encoded identically to " reg

" for the corresponding bus, the property value contains the address of the littleendian aperture of the frame buffer (in other words, the address range through which the frame buffer can be addressed in little-endian mode).

local-mac-address

Used with devices whose device_type

is network

, this should be present only if the device has a built-in, 48-bit, IEEE 802.3-style Media Access Control

(MAC) address. The system may or may not use this address in order to access this device. Encoded with encode-bytes

mac-address

Must be created by the open

method of network devices to indicate the Media

Access Control (MAC) address that this device is currently using. This value may or may not be the same as any local-mac-address

property.

This property is typically used by client programs that determine which network address was used by the network interface from which the client program was loaded.

The property value is the six-byte MAC address encoded with encode-byte

Here’s how it is made up:

1. If a plug-in device has an assigned MAC address from the factory, this address is published as the value for local-mac-address

2. The system (based on various factors such as presence or absence of local-mac-address

and/or the value of the NVRAM parameter local-mac-address?

) determines the address for the plug-in device to use. The value returned by the mac-address

FCode is set to this address.

3. The plug-in device then reports the address it is using by publishing the mac-address

property.

Writing FCode 3.x Programs —November 1997

For example:

For a well-behaved plug-in “ network

” device (which has a factory-unique

MAC address but can use another system-supplied MAC address if desired by the system), the FCode would appear as: create mac-address 8 c, 0 c, 20 c, 0 c, 14 c, 5e c, mac-address encode-bytes " mac-address" property

(

plus code to "assign" the correct mac-address value into registers

)

max-frame-size

When declared in “ network

” devices, indicates the maximum packet size (in bytes) that the physical layer of the device can transmit. This property can be used by client programs to allocate buffers of the appropriate length.

Usage:

4000 encode-int " max-frame-size" property

See also: property

and Chapter 11, “Network Devices”.

max-latency

This property contains the value of the Max_Lat register from the configuration space header. That register specifies how frequently the device needs to gain access to the PCI bus. The value is given in units of 250 nanoseconds. A value of zero indicates that the device has no major requirements for the setting of the Latency Timers.

The property value is the register's value encoded with encode-int

See also: PCI Local Bus Specification.

Properties

101

102

min-grant

This property contains the value of the Min_Gnt register from the configuration space header. That register specifies how long a burst period the device needs assuming a clock frequency of 33 MHz. The value is given in units of 250 nanoseconds. A value of zero indicates that the device has no major requirements for the setting of the Latency Timers.

The property value is the register's value encoded with encode-int

See also: PCI Local Bus Specification.

model

Identifies the model name and number (including revision) for a device, for manufacturing and field-service purposes.

The ' model”

property is useful to identify the specific piece of hardware (the plug-in card), as opposed to the name

property (since several different but functionally-equivalent cards would have the same “ name”

property, thus calling the same device driver). Although the “ model”

property is good to have in general, it generally does not have any other specific purpose.

The property value format is arbitrary, but conventional usage is to begin the string with the manufacturer’s name (as with the “ name”

property) and to end it with the revision level.

Usage:

" SUNW,501-1415-1" encode-string " model" property

See also:

"name"

, model

, property.

name

Specifies the manufacturer’s name and device name. All device nodes must publish this property. The “ name”

property can be used to match a particular operating system device driver with the device.

Writing FCode 3.x Programs —November 1997

The property value is an arbitrary string. Any combination of one to 31 printable characters is allowed, except for “@”, “:” or “/”. The string may contain one comma, at most. Embedded spaces are not allowed.

IEEE Standard 1275-1994 specifies three different formats for the manufacturer’s name portion of the property value where two of those formats are strongly preferred.

For United States companies that have publicly listed stock, the most practical form of name is to use the company’s stock symbol (e.g. SUNW for Sun

Microsystems, Inc.). This option is also available to any company in the world provided that there is no duplication of the company’s stock symbol on either the New York Stock Exchange or the NASDAQ exchange. If a non-U.S.

company’s stock is traded as an American Depository Receipt (ADR), the ADR symbol satisfies this requirement. A prime advantage of this form of manufacturer’s name is that such stock symbols are very human-readable.

Alternatively, a company may obtain an organizationally unique identifier (OUI) from the IEEE Registration Authority Committee. This is a 24-bit number that is guaranteed to be unique world-wide. Companies that have obtained an OUI would use a sequence of hexadecimal digits of the form “0NNNNNN” for the manufacturer’s name portion of the property. This form of name has the disadvantage that the manufacturer is not easily recognizable.

Each manufacturer may devise its own format for the device name portion of the property value.

Here is an example usage:

" SUNW,bison-printer" encode-string " name" property

You may also use the name

command to create this property.

page-size

This property specifies the number of bytes in the smallest mappable region of virtual address space managed by the

/mmu

package.

Properties

103

power-consumption

This property describes the device's maximum power consumption (in microwatts) categorized by the various power rails and the device's powermanagement state (standby or fully-on).

The property value is a list of up to ten integers encoded with encode-int

in the following order:

•

Unspecified standby

•

Unspecified full-on

•

+5V standby

•

+5V full-on

•

+3.3V standby

•

+3.3V full-on

•

I/O power standby

•

I/O power full-on

•

Reserved standby

•

Reserved full-on

The unspecified entries indicate that it is unknown how the power is divided among the various rails. The unspecified entries must be zero if any of the other entries are non-zero. The unspecified entries are provided so that the

" power-consumption

" property can be created for devices without FCode, from the information on the PRSNT1# and PRSNT2# connector pins.

If the number of integers in the encoded property value is less than ten, the power consumption is zero for the cases corresponding to the missing entries.

For example, if there are four integers, they correspond to the two unspecified and the two "+5" quantities, and the others are zero.

104 Writing FCode 3.x Programs —November 1997

The following code would create a " power-consumption

" property for a device with +5V standby consumption of 100 mA and +5V full-on consumption of 2.5A:

0 encode-int 0 encode-int encode+ \ Set unspecified values to zero

500000 encode-int encode+ \ 100 mA@5V = 500,000 uW standby

12500000 encode-int encode+

" power-consumption" property

\ 2.5A@5V = 12,500,000 uW full-on

ranges

The ranges

property is a list of child-to-parent physical address correspondences required for most hierarchical devices.

ranges

is a property for bus devices, particularly those buses whose children can be accessed with CPU load and store operations (as opposed to buses like

SCSI, whose children are accessed with a command protocol).

The “ ranges”

property value describes the correspondence between the part of the physical address space of the bus node’s parent available for use by the bus node (the parent address space), and the physical address space defined by the bus node for its children (the child address space).

The “ ranges”

property value is a sequence of specifications.

child-phys parent-phys size

•

child-phys is a starting address in the child physical address space defined by the bus node

•

parent-phys is a starting address in the physical address space of the parent of the bus node

•

size is the length in bytes of the address range.

The specification means that there is a one-to-one correspondence between the child addresses and the parent addresses in that range. The parent addresses given are always relative to the parent’s address space.

Properties

105

106

Each starting address is represented using the physical address representation as two 32-bit numbers (one for space

and one for offset

). size is encoded as an unsigned integer.

The total size of each such specification is five 32-bit numbers (two for each of the two addresses, plus one for the size). Successive specifications are encoded sequentially. A space with length 2**(number of bits in a machine word) is represented with a size of 0.

The specifications should be sorted in ascending order of the child address.

The address ranges thus described need not be contiguous in either the child space or the parent space. Also, the entire child space must be described in terms of parent addresses, but not all of the parent address space available to the bus device need be used for child addresses (the bus device might reserve some addresses for its own purposes, for instance).

For example, suppose that a 4-slot 25-bit SBus is attached to a machine whose physical address space consists of a 32-bit memory space (space=0) and a 32-bit

I/O space (space=1). The SBus slots appear in I/O space at address

0xf800.0000, 0xfa00.0000, 0xfc00.0000, and 0xfe00.0000. In terms of the SBus’s parent address space, the SBus device has available for its purposes the offsets from 0xf800.0000 through 0xffff.ffff in space 1 of its parent.

The SBus device defines for its children the spaces 0, 1, 2, and 3, all starting at offset 0 and running for 0x200.0000 bytes. In this case the SBus device uses all the address space given to it by its parent for the SBus children, and reserves none of the addresses for itself. The “ ranges”

property for the SBus device would contain the encoded form of the following sequence of numbers:

Table 7-3

Child-Parent Address Relationships

Child Address

Space

Offset

Parent Address

Space

Offset

f800.0000

fa00.0000

fc00.0000

fe00.0000

Size

200.0000

Here the high components of the child address represent the SBus slot numbers, and the high component of the parent address represents I/O space.

Writing FCode 3.x Programs —November 1997

If ranges

exists but its value is of 0 length, the bus’s child address space is identical to its parent address space.

If the ranges

property for a particular bus device node is nonexistent, code using that device should use an appropriate default interpretation. Some examples include the following:

•

SBus node: Missing ranges

means that the version of OpenBoot was created before the ranges

property came into existence. Code should supply the correct ranges based on the machine type, from the finite set of machines that existed before ranges

came into existence.

•

Machine node: The machine node has no parent. Therefore the correspondence between its child and parent address spaces is meaningless, and there is no need for ranges

•

SCSI host adapter node: The child address space is not directly addressable, thus ranges

would be meaningless.

The distinction between reg

and ranges

is as follows:

•

reg

is supposed to represent the actual device registers in the parent address space. For a bus adapter, this would be such as configuration/mode/initialization registers.

•

ranges

represents the correspondence between a bus adapter’s child and parent address spaces.

Most packages do not need to be concerned with ranges

. These properties are mainly to communicate with stand-alone programs. One exception could be a bus extender or adaptor.

See also: Chapter 10, “Memory-Mapped Buses”.

For a PCI node in a PowerPC Reference Platform (PPCRP) compliant machine, the total size of each such specification is five 32-bit numbers (one for the parent address space, three for the child address space, and one for the size).

Successive specifications are encoded sequentially. A space with length

2**(number of bits in a machine word) is represented with a size of 0.

Sort the specifications in ascending order of child-phys, in accordance with recommendations. The address ranges thus described need not be contiguous in either the child space or the parent space. Also, the entire child space must be described in terms of parent addresses, but not all of the parent address space available to the bus device need be used for child addresses (the bus device might reserve some addresses for its own purposes, for instance).

Properties

107

108

In the PPCRP machine example, consider a 4-slot 32-bit PCI bus attached to a machine whose physical address space consists of a 32-bit “memory” space (Bit

31 = 0) and a 32-bit “I/O” space (Bit 31 = 1).

•

ISA I/O space appears in the parent’s “I/O” space at 0x8000.0000; the size is

0x1.0000.

•

A reserved block of addresses begins at 0x8001.0000; the size is 0x7f.0000.

•

PCI configuration space begins at 0x8080.0000; the size is 0x80.0000. The configuration registers of the individual PCI slots appear at addresses

0x8080.1000, 0x8080.2000, 0x8080.4000, and 0x8080.8000.

•

PCI I/O space begins at 0x8100.0000; the size is 3e80.0000.

•

Parity/interrupt vectors begin at 0xbf80.0000; their size is 0x80.0000.

•

PCI memory space begins at 0xc000.0000; the size is 3e00.0000.

The PCI device defines:

Configuration spaces for Devices 1 through 4 that each begin at 0x0000.0000; their size is 0x100 bytes.

ISA I/O space that begins at 0x0000.0000; the size is 0x1.0000.

PCI I/O space that begins at 0x0001.0000; the size is 0x3e80.0000.

A 32-bit, PCI memory space that begins at 0x0000.0000; the size is 0x3e00.0000.

The ranges

property for the PCI device would contain the encoded form of the following sequence of numbers:

Table 7-4

Child-Parent Address Relationships for a PCI Node in a PPCRP Machine

Child Address

Function

SCSI

Slot A

Slot B

Slot C

ISA I/O space

PCI I/O space

PCI Memory space phys.hi

0000.0800

0000.1000

0000.1800

0000.2000

0100.0000

0200.0000

phys.mid

0000.0000

phys.lo

0000.0000

0001.0000

0000.0000

Parent

Address

8080.1000

8080.2000

8080.4000

8080.8000

8000.0000

8100.0000

c000.0000

Size

0000.0800

0001.0000

3e80.0000

3e00.0000

Writing FCode 3.x Programs —November 1997

Here the phys.hi component of the child address represents the type of address space and the PCI device numbers; Bit 31 of the parent address represents “I/O space.” (Please see the PCI Bus Binding to IEEE Standard 1275-1994 for a detailed description of the encoding of the phys.hi field.)

The code to create this ranges property is:

\ SCSI Configuration Space

0000.0800 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.1000 encode-int encode+

800 encode-int encode+

\ Slot A Configuration Space

0000.1000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.2000 encode-int encode+

800 encode-int encode+

\ Slot B Configuration Space

0000.1800 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.4000 encode-int encode+

800 encode-int encode+

\ Slot C Configuration Space

0000.2000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8080.8000 encode-int encode+

800 encode-int encode+

\ ISA I/O space

0100.0000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+

8000.0000 encode-int encode+

1.0000 encode-int encode+

\ PCI I/O space

0100.0000 encode-int encode+ 0 encode-int encode+ 1.0000 encode-int encode+

8100.0000 encode-int encode+

3e80.0000 encode-int encode+

\ PCI Memory space

0200.0000 encode-int encode+ 0 encode-int encode+ 0 encode-int encode+ c000.0000 encode-int encode+

3e00.0000 encode-int encode+

" ranges" property

Properties

109

110

reg

If ranges

exists but its value is of 0 length, the bus’s child address space is identical to its parent address space.

If the ranges

property for a particular bus device node is nonexistent, code using that device should use an appropriate default interpretation. Here are some examples:

•

Root node: The root node has no parent. Therefore the correspondence between its child and parent address spaces is meaningless, and there is no need for ranges

•

SCSI host adapter node: The child address space is not directly addressable, thus ranges

would be meaningless.

•

For memory-mapped bus devices where a ranges

property would be meaningful, the absence of a ranges

property is conventionally interpreted to mean that the parent and child address spaces are identical.

reg

and ranges

are differentiated thus:

•

reg

represents the device registers in the parent address space. For a bus adapter, this would be such as configuration/mode/initialization registers.

•

ranges

represents the correspondence between a bus adapter’s child and parent address spaces.

Most packages do not need to consider ranges

. This property is mainly used for bus bridges. The firmware system does not itself use this property.

ranges is mainly used by operating systems that wish to auto-configure themselves.

See also: Chapter 10, “Memory-Mapped Buses”.

This property declares the location and size of onboard registers for its device.

The FCode program for every plug-in SBus and PCI device must declare this property.

For SBus, the contents are one or more (phys

size) pairs. Each pair specifies an addressable region of the device. An FCode PROM at location 0 of the device is generally not declared, except in the case where there are no other regions to declare.

Writing FCode 3.x Programs —November 1997

For an SBus device, to declare two register fields at 10.0000-10.00ff and 20.0000-

20.037f, use the following: my-address 10.0000 + my-space encode-phys \ Offset#1

100 encode-int encode+ \ Merge size#1 my-address 20.0000 + my-space encode-phys encode+ \ Merge offset#2

380 encode-int encode+ \ Merge size#2

” reg” property

In the first (phys,size) pair for a PCI device, the phys component is the configuration space address of the beginning of the function's set of configuration registers; the size component is zero. Each additional (phys,size) pair specifies the address and characteristics of an addressable region of memory space or I/O space associated with the function including the PCI

Expansion ROM.

For a PCI device, the order of the pairs should be:

•

An entry describing the configuration space for the device.

•

An entry for each active base address register (BAR), in configuration space order, describing the entire space mapped by that BAR.

•

An entry describing the Expansion ROM BAR, if the device has an

Expansion ROM.

•

An entry for each non-relocatable addressable resource.

In the event that a function has an addressable region that can be accessed relative to more than one base address register (for example, in memory space relative to one base register, and in I/O space relative to another), only the primary access path (typically, the one in memory space) is listed in the " reg

" property, and the secondary access path is listed in the alternate-reg property.

Properties

111

112

For PCI, phys is (phys.lo phys.mid phys.hi), encoded with encode-phys

, and size is a pair of integers, each encoded with encode-int

. The first integer denotes the most-significant 32 bits of the 64-bit region size, and the second integer denotes the least-significant 32 bits thereof.

For example, to declare a PCI device with:

•

A register field of size 0x100 in 32-bit memory space that is controlled by the first 32-bit base address register.

•

A register field of size 0x440 in I/O space that is controlled by the second

32-bit base address register. The register field of interest is offset from the base address register by 0x20.0000.

•

A 128Kbyte PCI Expansion ROM.

•

A non-relocatable field at 0-fff in I/O space.

use the following: hex my-address my-space encode-phys \ Config space regs

0 encode-int encode+ 0 encode-int encode+

0 0 my-space 0200.0010 or encode-phys encode+ \ Memory space

0 encode-int encode+ 100 encode-int encode+ \ BAR at 0x10

20.0000 0 my-space 0100.0014 or encode-phys \ I/O space encode+\ BAR at 0x14

0 encode-int encode+ 440 encode-int encode+

0 0 my-space 0200.0030 or encode-phys encode+ \ PCI Expansion ROM

0 encode-int encode+ 2.0000 encode-int encode+ \ memory space

0 0 my-space 8100.0000 or encode-phys encode+ \ Non-relocatable

0 encode-int encode+ 1000 encode-int encode+ \ memory space

" reg" property

In some non-PCI cases, the reg

command may also be used to create this property. However, reg

may only be used on buses for which #size-cells is one and only when a single “ reg”

property component is required. Consequently, reg

is never used with PCI devices which require at least three “ reg” property component—in other words

•

One component for the card's configuration space registers

•

At least one for the device's functional registers and

Writing FCode 3.x Programs —November 1997

revision-id

This property contains the value of the revision ID register from the configuration space header. That register specifies a device-specific revision identifier that is chosen by the vendor. Zero is an acceptable value.

The property value is the register's value encoded with encode-int

See also: PCI Local Bus Specification.

slot-names

•

One for the PCI Expansion ROM).

Note –

The contents of the “ reg”

property are used by OpenBoot firmware to determine how large a portion of the system's virtual address space to reserve for use by the card. It is important that the size arguments be as large as the actual available addressable resource. If the size argument for a region were to be declared smaller than that actually available, and if the driver or a user were to later add a legitimate offset that was larger than size to the base address of the region, the resulting virtual address might be within the virtual address space of another card.

See the PCI Bus Binding to IEEE Standard 1275-1994 for the encoding details.

status

This optional property indicates the operational status of the device.

Absence of this property means that the operational status of the device is unknown or okay.

If this property is present, the value is a string indicating the status of the device, as follows:

Table 7-5

status Property values

Meaning

The device is believed to be operational.

The device represented by this node is not operational, but it might become operational in the future

(e.g. an external switch is turned off, or something isn’t plugged in).

The device represented by this node is not operational because a fault has been detected, and it is unlikely that the device will become operational without repair. No additional failure details are available.

The device represented by this node is not operational because a fault has been detected, and it is unlikely that the device will become operational without repair. “xxx” is additional human-readable information about the particular fault condition that was detected.

Used as:

" disabled" encode-string " status" property

See also: property

translations

This property contains an array of (phys-addr, virt-addr, size) entries describing the address translations currently in use by OpenBoot. Those operating systems calling on OpenBoot services while taking over the memory management function must create all translations described by this property’s value.

114 Writing FCode 3.x Programs —November 1997

vendor-id

This property contains the value of the vendor ID register from the configuration space header. That register identifies the manufacturer of the device. Vendor identifiers are assigned by the PCI SIG to ensure uniqueness.

0xffff is an invalid value for vendor-id.

The property value is the register’s value encoded with encode-int

See also: PCI Local Bus Specification.

width

Manipulating Properties

Associated with display

devices. Encoded with encode-int

, the property value specifies the number of displayable pixels in the “x” direction of the display.

Property Creation and Modification

Use the FCode Function property

to create new properties or modify values of existing properties.

There are some special property-publishing FCodes, designed for use in common situations:

•

reg

is a quick way to create a “ reg”

property that describes the location of the package’s physical resources.

•

model

is a quick way to create the “ model”

property.

•

device-name

is a quick way to create the “ name”

property.

•

delete-property

completely removes a property.

Property Values

Various kinds of information can be stored in a property value byte array by using property encoding and decoding methods. The encoding format is machine-independent. Property value representation is independent of the byte organization and word alignment characteristics of a processor.

Properties

115

116

A property’s data type must be recognized by any software that uses it. In other words, property value data types are not self-identifying. Furthermore, the presence or absence of a property with a particular name can encode a true/false flag; such a property may have a zero-length property value.

Property Encoding

There are three FCodes for encoding a basic piece of data into a property value and one for concatenating the basic pieces of data for a property with multiple values.

encode-int encodestring encodes a number encodes a string encode-bytes encodes a sequence of bytes encode+ is used to concatenate two previously encoded, basic pieces of data encode-phys is an FCode that encodes a physical address (hiding all the relative addressing information)

Property Retrieval

There are three property value retrieving words, get-my-property

, get-inherited-property

, and get-package-property

•

Use get-my-property

if the property desired exists for the package being defined.

•

Use get-package-property

if the property exists in some other package.

In this case, you must first find the phandle of the other package, perhaps by using find-package

•

Use get-inherited-property

if the property exists somewhere in the chain of parent instances between the package being defined and the root node of the machine.

Note –

Using get-inherited-property

can be a bad idea because you don’t know who supplied the data.

Writing FCode 3.x Programs —November 1997

FCode programs often do not retrieve property values. Such programs usually know the values of their own properties implicitly, and often interact with their parents by calling well-known parent methods.

For example, suppose a particular SBus FCode package calls DVMA to transfer data between a device and memory.

It could use

my-parent ihandle>phandle get-package-property to find the value of a property named slave-only

slave-only

will be a property of the parent node of the package being defined, if it exists.

The value of the property is a bit mask of the SBus slots that do not support

DVMA. Then the package would look at my-unit

or my-space

to get its slot number. The two pieces of information will tell the package whether or not it can use DVMA.

Property Decoding

Once a package has found a property’s value, it must decode the value to forms it can recognize. If the value is the representation of an integer, use decode-int

to generate the number as a binary number on the stack. If the value is the representation of a string, use decode-string

. Both of these

FCodes act as parsers — they will also return the unused portion of the value for further decoding.

Other kinds of values can be decoded by left-parse-string

or packagespecific decoders. Note that the package must be able to decode the value of a property.

There is no decode-bytes

function, but it is easy to synthesize if you need it.

: decode-bytes ( addr1 len1 #bytes -- addr len2 addr1 #bytes )

tuck ( addr1 #bytes len2 )

>r 2dup + ( addr1 #bytes addr2 ) ( R: len2 )

r> 2swap

;

Properties

117

Property-Specific FCodes

Following is a summary of property-specific FCodes. See the individual dictionary entries in Chapter 14, “FCode Dictionary”, for more information.

Table 7-6

Property-specific FCodes

Stack Diagram Description Name

Property Creation

property

( prop-addr prop-len name-addr name-len -- ) device-type model name reg device-name

( addr len -- )

( phys.lo … phys.hi size -- )

( addr len -- ) delete-property

( name-addr name-len -- )

Property Encoding

encode-int encode-phys

( n -- prop-addr prop-len )

( phys.lo … phys.hi -- prop-addr prop-len )

Create a property named name-addr name-len with the value prop-addr prop-len.

Shorthand word to create the device_type property with the value addr len.

Shorthand word to create the model property with the value addr len.

Shorthand macro to create the name

property with the value addr len.

Shorthand word to create the reg

property.

Shorthand word to create the name property with the value addr len. Similar to name

, but uses only one FCode instead of creating a macro.

Delete the desired property.

encode-string encode+ encode-bytes

( addr len -- prop-addr prop-len )

( prop-addr1 prop-len1 prop-addr2 prop-len2

-- prop-addr prop-len1+2 )

( addr len -- prop-addr prop-len )

Converts an integer to a prop-encoded-array.

Converts a physical unit pair to a propencoded-array.

Converts a text string to a prop-encodedarray.

Concatenate two prop-encoded-array structures. They must have been created sequentially.

Converts a byte array to a prop-encodedarray. Similar to encode-string

, except no trailing null is appended.

Property Decoding

decode-int

( prop-addr prop-len --

prop-addr2 prop-len2 n )

Converts a prop-encoded-array string to an integer.

118 Writing FCode 3.x Programs —November 1997

Name

decode-string

Table 7-6

Property-specific FCodes (Continued)

Stack Diagram

( prop-addr prop-len --

prop-addr2 prop-len2 addr len )

Property Retrieval

get-my-property

( name-addr name-len --

true | prop-addr prop-len false )

Description

Converts a prop-encoded-array string to a normal string.

get-packageproperty get-inheritedproperty

( addr len phandle --

true | prop-addr prop-len false )

( addr len -- true | prop-addr prop-len false )

Returns the prop-encoded-array contents for the property addr len in the current instance, or true if not found.

Returns the prop-encoded-array contents for the property addr len in the package phandle, or true if not found.

Returns the prop-encoded-array contents for the property addr len, or true if not found.

The current package instance is searched first. If not found, the parent is searched next, then the parent’s parent, and so on.

Properties

119

120 Writing FCode 3.x Programs —November 1997

Block Devices

Block and Byte Devices

Block devices are nonvolatile mass storage devices whose information can be accessed in any order. Hard disks, floppy disks, and CD-ROMs are examples of block devices. OpenBoot typically uses block devices for booting.

This device type generally applies to disk devices, but as far as OpenBoot is concerned, it simply means that the device “looks like a disk” at the OpenBoot software interface level.

The block device’s FCode must declare the block

device type, and implement the methods open

and close

, as well as the methods described in “Required

Methods”.

Although packages of the block

device type present a byte-oriented interface to the rest of the system, the associated hardware devices are usually blockoriented i.e. the device reads and writes data in blocks (groups of, for example,

512 or 2048 bytes). The standard

/deblocker

support package assists in the presentation of a byte-oriented interface overlaying a block-oriented interface, implementing a buffering layer that hides the underlying block length.

Block devices are often subdivided into several logical partitions, as defined by a disk label - a special block, usually the first one on the device, which contains information about the device. The driver is responsible for appropriately interpreting a disk label. The driver may use the standard

/disk-label support package if the device does not implement a specialized label. The

/disk-label

support package interprets a system-dependent label format.

121

Since the disk booting protocol usually depends on the label format, the standard

/disk-label

support package also implements a load

method for the corresponding boot protocol.

Byte Devices

Byte devices are sequential-access mass storage devices, for example tape devices. OpenBoot typically uses byte devices for booting.

The byte device’s FCode program must declare the byte

device type, and implement the open

and close

methods in addition to those described in

“Required Methods”.

Although packages of the byte

device type present a byte-oriented interface to the rest of the system, the associated hardware devices are usually recordoriented; the device reads and writes data in records containing more than one byte. The records may be fixed or variable length. The standard

/deblocker support package assists in presenting a byte-oriented interface overlaying a record-oriented interface, implementing a buffering layer that hides the underlying record structure.

Required Methods

block-size

( -- block-len )

Returns the record size block-len (in bytes) of all data transfers to or from the device. The most common value for block-len is 512.

This method is only required if the

/deblocker

support package is used.

load

( addr -- size )

load

works differently for block and byte devices:

With block devices, it loads a stand-alone program from the device into memory at addr. size is the size in bytes of the program loaded. If the device can contain several such programs, the instance arguments returned by my-args can be used to select the program desired.

open

is executed before load

is invoked.

122 Writing FCode 3.x Programs —November 1997

With byte devices, load

reads a stand-alone program from the tape file specified by the value of the argument string given by my-args

. That value is the string representation of a decimal integer. If the argument string is null, tape file 0 is used.

load

places the program in memory at addr, returning the

size of the read-in program in bytes.

max-transfer

( -- max-len )

Returns the size in bytes of the largest single transfer that the device can perform.

max-transfer

is expected to be a multiple of block-size

This method is only required if the

/deblocker

support package is used.

read

( addr len -- actual )

Read at most len bytes from the device into memory at addr. actual is the number of bytes read. If the number of bytes read is 0 or negative, the read failed. Note that len need not be a multiple of the device’s normal block size.

read-blocks

( addr block# #blocks -- #read )

Read #blocks records of length block-size

bytes each from the device, starting at device block block#, into memory at address addr. #read is the number of blocks actually read.

This method is only required if the

/deblocker

support package is used.

seek

( poslow poshigh -- status ) for block; ( offset file# -- error? ) for byte

seek

works differently depending on whether it’s being used with a block or byte device.

For block devices, seek

sets the device position for the next read or write. The position is the byte offset from the beginning of the device specified by the 64bit number which is the concatenation of poshigh and poslow. status is -1 if the seek fails, and 0 or 1 if it succeeds.

For byte devices, it seeks to the byte offset in file file#. If offset and file# are both

0, rewind the tape. error? is -1 if seek fails, and 0 if seek succeeds.

Block and Byte Devices

123

write

( addr len -- actual )

Write len bytes from memory at addr to the device. actual is the number of bytes written. If actual is less than len, the write did not succeed. len need not be a multiple of the device’s normal block size.

write-blocks

( addr block# #blocks -- #written )

Write #blocks records of length block-size

bytes each to the device, starting at block block#, from memory at addr. #written is the number of blocks actually written.

If the device is not capable of random access (e.g. a sequential access tape device), block# is ignored.

This method is only required if the

/deblocker

support package is used.

124 Writing FCode 3.x Programs —November 1997

Required Properties

Table 8-1

Required Properties of Block and Byte Devices

Property Name

name reg device_type

Sample Value

" SUNW,my-scsi" list of registers (device-dependent) block or byte

Device Driver Examples

The structure of the device tree for the sample card supported by the sample device drivers in this chapter is as follows: sbus

… …

SUNW,my-scsi sd st

Figure 8-1

Sample Device Tree

Block and Byte Devices

125

126

Simple Block Device Driver

Code Example 8-1

Simple Block Device Driver

\ This is at a stage where each leaf node can be used only as a non-bootable device.

\ It only creates nodes and publishes necessary properties to identify the device.

fcode-version3 hex

" SUNW,my-scsi" encode-string " name" property

h# 20.0000 constant scsi-offset

h# 40 constant /scsi

my-address scsi-offset + my-space /scsi reg

new-device \ missing "reg" indicates a SCSI "wild-card" node

" sd" encode-string " name" property

finish-device

new-device \ missing "reg" indicates a SCSI "wild-card" node

" st" encode-string " name" property

finish-device end0

Extended Block Device Driver

Code Example 8-2

Sample Driver for my-scsi

Device

\ It is still a non-bootable device. The purpose is to show how an intermediate stage

\ of driver can be used to debug board during development. In addition to publishing

\ the properties, this sample driver shows methods to access, test and control

\ "SUNW,my-scsi" device.

\ The following main methods are provided for "SUNW,my-scsi" device.

\ open ( -- okay? )

\ close ( -- )

\ reset ( -- )

\ selftest ( -- error? ) fcode-version3

hex

headers

h# 20.0000 constant scsi-offset

h# 40 constant /scsi

d# 25.000.000 constant clock-frequency

Writing FCode 3.x Programs —November 1997

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

: identify-me ( -- )

" SUNW,my-scsi" encode-string " name" property

" scsi" device-type

my-address scsi-offset + my-space /scsi reg

;

identify-me

h# 10.0000 constant dma-offset

h# 10 constant /dma

-1 instance value dma-chip

\ methods to access/control dma registers

: dmaaddress ( -- addr ) dma-chip 4 + ;

: dmacount ( -- addr ) dma-chip 8 + ;

: dmaaddr@ ( -- n ) dmaaddress rl@ ;

: dmaaddr! ( n -- ) dmaaddress rl! ;

: dmacount@ ( -- n ) dmacount rl@ ;

: dmacount! ( n -- ) dmacount rl! ;

: dma-chip@ ( -- n ) dma-chip rl@ ;

: dma-chip! ( n -- ) dma-chip rl! ;

: dma-btest ( mask -- flag ) dma-chip@ and ;

: dma-bset ( mask -- ) dma-chip@ or dma-chip! ;

: dma-breset ( mask -- ) not dma-btest dma-chip! ;

external

\ methods to allocate, map, unmap, free dma buffers

: decode-unit ( addr len -- low high ) decode-2int ;

: dma-alloc ( size -- vaddr ) " dma-alloc" $call-parent ;

: dma-free ( vaddr size -- ) " dma-free" $call-parent ;

: dma-map-in ( vaddr size cache? -- devaddr ) " dma-map-in" $call-parent ;

: dma-map-out ( vaddr devaddr size -- ) " dma-map-out" $call-parent ;

\ Dma-sync could be a dummy routine if the parent device doesn't support.

: dma-sync ( virt-addr dev-addr size -- )

" dma-sync" my-parent ['] $call-method catch if

2drop 2drop 2drop

then

;

: map-in ( addr space size -- virt ) " map-in" $call-parent ;

Block and Byte Devices

127

128

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

: map-out ( virt size -- ) " map-out" $call-parent ;

headers

: dma-open ( -- )

my-address dma-offset + my-space /dma map-in to dma-chip

;

: dma-close ( -- ) dma-chip /dma map-out -1 to dma-chip ;

-1 instance value scsi-init-id

-1 instance value scsi-chip

h# 20 constant /mbuf

-1 instance value mbuf

-1 instance value mbuf-dma

d# 6 constant /sense

-1 instance value sense-command

-1 instance value sense-cmd-dma

d# 8 constant #sense-bytes

-1 instance value sense-buf

-1 instance value sense-buf-dma

-1 instance value mbuf0

d# 12 constant /cmdbuf

-1 instance value cmdbuf

-1 instance value cmdbuf-dma

-1 instance value scsi-statbuf

\ mapping and allocation routines for scsi

: map-scsi-chip ( -- )

my-address scsi-offset + my-space /scsi map-in to scsi-chip

;

: unmap-scsi-chip ( -- ) scsi-chip /scsi map-out -1 to scsi-chip ;

\ After any changes to sense-command by CPU or any changes to sense-cmd-dma by

\ device, synchronize changes by issuing " sense-command sense-cmd-dma /sense

\ dma-sync " Similarly after any changes to sense-buf, sense-buf-dma, mbuf,

\ mbuf-dma, cmdbuf or cmdbuf-dma, synchronize changes by appropriately issuing

\ dma-sync map scsi chip and allocate buffers for "sense" command and status

: map-scsi ( -- )

map-scsi-chip

/sense dma-alloc to sense-command

sense-command /sense false dma-map-in to sense-cmd-dma

#sense-bytes dma-alloc to sense-buf

sense-buf #sense-bytes false dma-map-in to sense-buf-dma

Writing FCode 3.x Programs —November 1997

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

2 alloc-mem to scsi-statbuf

;

\ free buffers for "sense" command and status and unmap scsi chip

: unmap-scsi ( -- )

scsi-statbuf 2 free-mem

sense-buf sense-buf-dma #sense-bytes dma-sync \ redundant

sense-buf sense-buf-dma #sense-bytes dma-map-out

sense-buf #sense-bytes dma-free

sense-command sense-cmd-dma /sense dma-sync \ redundant

sense-command sense-cmd-dma /sense dma-map-out

sense-command /sense dma-free

-1 to sense-command

-1 to sense-cmd-dma

-1 to sense-buf

-1 to scsi-statbuf

-1 to sense-buf-dma

unmap-scsi-chip

;

\ constants related to scsi commands

h# 0 constant nop

h# 1 constant flush-fifo

h# 2 constant reset-chip

h# 3 constant reset-scsi

h# 80 constant dma-nop

\ words to get scsi register addresses.

\ Each chip register is one byte, aligned on a 4-byte boundary.

: scsi+ ( offset -- addr ) scsi-chip + ;

: transfer-count-lo ( -- addr ) h# 0 scsi+ ;

: transfer-count-hi ( -- addr ) h# 4 scsi+ ;

: fifo ( -- addr ) h# 8 scsi+ ;

: command ( -- addr ) h# c scsi+ ;

: configuration ( -- addr ) h# 20 scsi+ ;

: scsi-test-reg ( -- addr ) h# 28 scsi+ ;

\ Read only registers:

: scsi-status ( -- addr ) h# 10 scsi+ ;

: interrupt-status ( -- addr ) h# 14 scsi+ ;

: sequence-step ( -- addr ) h# 18 scsi+ ;

Block and Byte Devices

129

130

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

: fifo-flags ( -- addr ) h# 1c scsi+ ;

\ Write only registers:

: select/reconnect-bus-id ( -- addr ) h# 10 scsi+ ;

: select/reconnect-timeout ( -- addr ) h# 14 scsi+ ;

: sync-period ( -- addr ) h# 18 scsi+ ;

: sync-offset ( -- addr ) h# 1c scsi+ ;

: clock-conversion-factor ( -- addr ) h# 24 scsi+ ;

\ words to read from/store to scsi registers.

: cnt@ ( -- w ) transfer-count-lo rb@ transfer-count-hi rb@ bwjoin ;

: fifo@ ( -- c ) fifo rb@ ;

: cmd@ ( -- c ) command rb@ ;

: stat@ ( -- c ) scsi-status rb@ ;

: istat@ ( -- c ) interrupt-status rb@ ;

: fifo-cnt ( -- c ) fifo-flags rb@ h# 1f and ;

: data@ ( -- c ) begin fifo-cnt until fifo@ ;

: seq@ ( -- c ) sequence-step rb@ h# 7 and ;

: fifo! ( c -- ) fifo rb! ;

: cmd! ( c -- ) command rb! ;

: cnt! ( w -- ) wbsplit transfer-count-hi rb! transfer-count-lo rb! ;

: targ! ( c -- ) select/reconnect-bus-id rb! ;

: data! ( c -- ) begin fifo-cnt d# 16 <> until fifo! ;

\ scsi chip noop and initialization

: scsi-nop ( -- ) nop cmd! ;

: init-scsi ( -- ) reset-chip cmd! scsi-nop ;

: wait-istat-clear ( -- error? )

d# 1000

begin

1 ms 1- ( count )

dup 0= ( count expired? )

istat@ ( count expired? istat )

0= or ( count clear? )

until ( count )

0= if

istat@ 0<> if

cr ." Can't clear ESP interrupts: "

." Check SCSI Term. Power Fuse." cr

true exit

Writing FCode 3.x Programs —November 1997

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

then

false

;

: clk-conv-factor ( -- n ) clock-frequency d# 5.000.000 / 7 and ;

\ initialize scsi chip, tune time amount, set async operation mode, and set scsi

\ bus id

: reset-my-scsi ( -- error? )

init-scsi

h# 93 select/reconnect-timeout rb!

0 sync-offset rb!

clk-conv-factor clock-conversion-factor rb!

h# 4 scsi-init-id 7 and or configuration rb!

wait-istat-clear

;

: reset-bus ( -- error? )

reset-scsi cmd! wait-istat-clear

;

: init-n-test ( -- ok? ) reset-my-scsi 0= ;

: get-buffers ( -- )

h# 8000 dma-alloc to mbuf0

/cmdbuf dma-alloc to cmdbuf

cmdbuf /cmdbuf false dma-map-in to cmdbuf-dma

;

: give-buffers ( -- )

mbuf0 h# 8000 dma-free -1 to mbuf0

cmdbuf cmdbuf-dma /cmdbuf dma-sync \ redundant

cmdbuf cmdbuf-dma /cmdbuf dma-map-out

cmdbuf /cmdbuf dma-free

-1 to cmdbuf -1 to cmdbuf-dma

;

: scsi-selftest ( -- fail? ) reset-my-scsi ;

\ dma-alloc and dma-map-in mbuf-dma

Block and Byte Devices

131

132

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

: mbuf-alloc ( -- )

/mbuf dma-alloc to mbuf

mbuf /mbuf false dma-map-in to mbuf-dma

;

\ dma-map-out and dma-free mbuf-dma

: mbuf-free ( -- )

mbuf mbuf-dma /mbuf dma-sync \ redundant

mbuf mbuf-dma /mbuf dma-map-out

mbuf /mbuf dma-free

-1 to mbuf

-1 to mbuf-dma

;

external

\ If any routine was using buffers allocated by dma-alloc, and was using dma mapped

\ by dma-map-in, it would have to dma-sync those buffers after making any changes to

\ them.

: open ( -- success? )

dma-open

" scsi-initiator-id" get-inherited-property 0= if

decode-int to scsi-init-id

2drop

map-scsi

init-n-test ( ok? )

dup if ( true )

get-buffers ( true )

else

unmap-scsi dma-close ( false )

then ( success? )

else

." Missing initiator id" cr false

dma-close

then ( success? )

;

: close ( -- )

give-buffers unmap-scsi dma-close

;

: reset ( -- )

dma-open map-scsi

h# 80 dma-breset

Writing FCode 3.x Programs —November 1997

Code Example 8-2

Sample Driver for my-scsi

Device (Continued)

reset-my-scsi drop reset-bus drop

unmap-scsi dma-close

;

\ if scsi-selftest was actually using buffers allocated by mbuf-alloc, it would

\ have to do dma-sync after any changes to mbuf or mbuf-dma.

: selftest ( -- fail? )

map-scsi

mbuf-alloc

scsi-selftest

mbuf-free

unmap-scsi

;

new-device \ missing "reg" indicates a SCSI "wild-card" node

" sd" encode-string " name" property

finish-device

new-device \ missing "reg" indicates a SCSI "wild-card" node

" st" encode-string " name" property

finish-device end0

Block and Byte Devices

133

134

Complete Block and Byte Device Driver

Code Example 8-3

Sample Driver for Bootable Devices

\ This driver supports "block" and "byte" type bootable devices, by using standard

\ "deblocker"and "disk-label" packages.

fcode-version3

hex

headers

: copyright ( -- )

;

h# 20.0000 constant scsi-offset

h# 40 constant /scsi

d# 25.000.000 constant clock-frequency

: identify-me ( -- )

" SUNW,my-scsi" encode-string " name" property

" scsi" device-type

my-address scsi-offset + my-space /scsi reg

;

identify-me

h# 10.0000 constant dma-offset

h# 10 constant /dma

-1 instance value dma-chip

external

: decode-unit ( addr len -- low high ) decode-2int ;

: dma-alloc ( size -- vaddr ) " dma-alloc" $call-parent ;

: dma-free ( vaddr size -- ) " dma-free" $call-parent ;

: dma-map-in ( vaddr size cache? -- devaddr ) " dma-map-in" $call-parent ;

: dma-map-out ( vaddr devaddr size -- ) " dma-map-out" $call-parent ;

\ Dma-sync could be dummy routine if parent device doesn't support.

: dma-sync ( virt-addr dev-addr size -- )

" dma-sync" my-parent ['] $call-method catch if

2drop 2drop 2drop

then

;

: map-in ( addr space size -- virt ) " map-in" $call-parent ;

: map-out ( virt size -- ) " map-out" $call-parent ;

Writing FCode 3.x Programs —November 1997

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

headers

\ variables/values for sending commands, mapping etc.

-1 instance value scsi-init-id

-1 instance value scsi-chip

-1 instance value mbuf

-1 instance value mbuf-dma

h# 20 constant /mbuf

...

\ mapping and allocation routines for scsi

: map-scsi-chip ( -- )

my-address scsi-offset + my-space /scsi map-in to scsi-chip

;

: unmap-scsi-chip ( -- ) scsi-chip /scsi map-out -1 to scsi-chip ;

: map-scsi ( -- )

map-scsi-chip

\ allocate buffers etc. for "sense" command and status

...

;

: unmap-scsi ( -- )

\ free buffers etc. for "sense" command and status

...

unmap-scsi-chip

;

\ words related to scsi commands and register access.

...

: reset-my-scsi ( -- error? ) ... ;

: reset-bus ( -- error? ) ... ;

: init-n-test ( -- ok? ) ... ;

: get-buffers ( -- ) ... ;

: give-buffers ( -- ) ... ;

: scsi-selftest ( -- fail? ) ... ;

Block and Byte Devices

135

136

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

d# 512 constant ublock

0 instance value /block

0 instance value /tapeblock

instance variable fixed-len?

...

external

: set-timeout ( n -- ) ... ;

: send-diagnostic ( -- error? )

\ run diagnostics and return any error.

...

;

: device-present? ( lun target -- present? ) ... ;

: mode-sense ( -- true | block-size false ) ... ;

: read-capacity ( -- true | block-size false ) ... ;

\ Spin up a SCSI disk, coping with a possible wedged SCSI bus

: timed-spin ( target lun -- ) ... ;

: disk-r/w-blocks ( addr block# #blocks direction? -- #xfered )

... ( #xfered )

;

\ Execute "mode-sense" command. If failed, execute read-capacity command.

\ If this also failed, return d# 512 as the block size.

: disk-block-size ( -- n )

mode-sense if read-capacity if d# 512 then then

dup to /block

;

: tape-block-size ( -- n ) ... ;

: fixed-or-variable ( -- max-block fixed? ) ... ;

: tape-r/w-some ( addr block# #blks read? -- actual# error? ) ... ;

headers

: dma-open ( -- ) my-address dma-offset + my-space /dma map-in to dma-chip ;

: dma-close ( -- ) dma-chip /dma map-out -1 to dma-chip ;

Writing FCode 3.x Programs —November 1997

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

\ After any changes to mbuf by cpu or any changes to mbuf-dma by device, synchronize

\ changes by issuing " mbuf mbuf-dma /mbuf dma-sync "

: mbuf-alloc ( -- )

/mbuf dma-alloc to mbuf

mbuf /mbuf false dma-map-in to mbuf-dma

;

\ dma-map-out and dma-free mbuf-dma

: mbuf-free ( -- )

mbuf mbuf-dma /mbuf dma-sync \ redundant

mbuf mbuf-dma /mbuf dma-map-out

mbuf /mbuf dma-free

-1 to mbuf

-1 to mbuf-dma

;

external

\ external methods for scsi bus ( "SUNW,my-scsi" node)

: open ( -- okay? )

dma-open

" scsi-initiator-id" get-inherited-property 0= if

decode-int to scsi-init-id

2drop

map-scsi

init-n-test ( ok? )

dup if ( true )

get-buffers ( true )

else

unmap-scsi dma-close ( false )

then ( success? )

else

." Missing initiator id" cr false

dma-close

then ( success? )

;

: close ( -- ) give-buffers unmap-scsi dma-close ;

: reset ( -- )

dma-open map-scsi

...

reset-my-scsi drop reset-bus drop

Block and Byte Devices

137

138

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

unmap-scsi dma-close

;

: selftest ( -- fail? )

map-scsi

mbuf-alloc

scsi-selftest

mbuf-free

unmap-scsi

;

headers

\ start of child block device

new-device \ missing "reg" indicates SCSI "wild-card" node

" sd" encode-string " name" property

" block" device-type

0 instance value offset-low

0 instance value offset-high

0 instance value label-package

\ The "disk-label" package interprets any partition information contained in

\ the disk label. The "load" method of the "block" device uses the load method

\ provided by "disk-label"

: init-label-package ( -- okay? )

0 to offset-high 0 to offset-low

my-args " disk-label" $open-package to label-package

label-package if

0 0 " offset" label-package $call-method

to offset-high to offset-low

true

else

." Can't open disk label package" cr false

then

;

0 instance value deblocker

: init-deblocker ( -- okay? )

" " " deblocker" $open-package to deblocker

deblocker if

Writing FCode 3.x Programs —November 1997

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

true

else

." Can't open deblocker package" cr false

then

;

: device-present? ( lun target -- present? )

" device-present?" $call-parent

;

\ The following methods are needed for "block" device:

\ open, close, selftest, reset, read, write, load, seek, block-size,

\ max-transfer,read-blocks, write-blocks.

\ Carefully notice the relationship between the methods for the "block" device

\ and the methods pre-defined for "disk-label" and "deblocker"

external

\ external methods for "block" device ( "sd" node)

: spin-up ( -- ) my-unit " timed-spin" $call-parent ;

: open ( -- ok? )

my-unit device-present? 0= if false exit then

spin-up \ Start the disk if necessary

init-deblocker 0= if false exit then

init-label-package 0= if

deblocker close-package false exit

then

true

;

: close ( -- )

label-package close-package 0 to label-package

deblocker close-package 0 to deblocker

;

: selftest ( -- fail? )

my-unit device-present? if

" send-diagnostic" $call-parent ( fail? )

else

true ( error )

then

;

Block and Byte Devices

139

140

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

: reset ( -- ) ... ;

\ The "deblocker" package assists in the implementation of byte-oriented read and

\ write methods for disks and tapes. The deblocker provides a layer of buffering

\ to implement a high level byte-oriented interface "on top of" a low-level

\ block-oriented interface.

\ The "seek", "read" and "write" methods of this block device use corresponding

\ methods provided by "deblocker"

\ In order to be able to use the "deblocker" package this device has to define the

\ following four methods, which the deblocker uses as its low-level interface

\ to the device:

\ 1) block-size, 2) max-transfer, 3) read-blocks and 4) write-blocks

: block-size ( -- n ) " disk-block-size" $call-parent ;

: max-transfer ( -- n ) block-size h# 40 * ;

: read-blocks ( addr block# #blocks -- #read )

true " disk-r/w-blocks" $call-parent

;

: write-blocks ( addr block# #blocks -- #written )

false " disk-r/w-blocks" $call-parent

;

: dma-alloc ( #bytes -- vadr ) " dma-alloc" $call-parent ;

: dma-free ( vadr #bytes -- ) " dma-free" $call-parent ;

: seek ( offset.low offset.high -- okay? )

offset-low offset-high x+ " seek" deblocker $call-method

;

: read ( addr len -- actual-len ) " read" deblocker $call-method ;

: write ( addr len -- actual-len ) " write" deblocker $call-method ;

: load ( addr -- size ) " load" label-package $call-method ;

finish-device \ finishing "block" device "sd"

headers

\ start of child byte device

new-device \ missing "reg" indicates "wild-card" node

" st" encode-string " name" property

Writing FCode 3.x Programs —November 1997

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

" byte" device-type

false instance value write-eof-mark?

instance variable file-mark?

true instance value scsi-tape-first-install

: scsi-tape-rewind ( -- [[xstatbuf] f-hw] error? ) ... ;

: write-eof ( -- [[xstatbuf] f-hw] error? ) ... ;

0 instance value deblocker

: init-deblocker ( -- okay? )

" " " deblocker" $open-package to deblocker

deblocker if

true

else

." Can't open deblocker package" cr false

then

;

: flush-deblocker ( -- )

deblocker close-package init-deblocker drop

;

: fixed-or-variable ( -- max-block fixed? )

" fixed-or-variable" $call-parent

;

: device-present? ( lun target -- present? )

" device-present?" $call-parent

;

\ The following methods are needed for "byte" devices:

\ open, close, selftest, reset, read, write, load, seek, block-size,

\ max-transfer, read-blocks, write-blocks. Carefully notice the relationship

\ between the methods for "byte" devices and the methods pre-defined for the

\ standard deblocker package.

external

\ external methods for "byte" device ( "st" node)

Block and Byte Devices

141

142

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

\ The "deblocker" package assists in the implementation of byte-oriented read

\ and write methods for disks and tapes. The deblocker provides a layer of

\ buffering to implement a high level byte-oriented interface "on top of" a

\ low-level block-oriented interface.

\ The "read" and "write" methods of this "byte" device use the corresponding

\ methods provided by the "deblocker"

\ In order to be able to use the "deblocker" package this device has to define the

\ following four methods which the deblocker uses as its low-level interface to

\ the device:

\ 1) block-size, 2) max-transfer, 3) read-blocks and 4) write-blocks

: block-size ( -- n ) " tape-block-size" $call-parent ;

: max-transfer ( -- n )

fixed-or-variable ( max-block fixed? )

\ Use the largest multiple of /tapeblock that to <= h# fe00

h# fe00 over / *

then

;

: read-blocks ( addr block# #blocks -- #read )

file-mark? @ 0= if

true " tape-r/w-some" $call-parent file-mark? ! ( #read )

else

3drop 0

then

;

: write-blocks ( addr block# #blocks -- #written )

false " tape-r/w-some" $call-parent file-mark? !

;

: dma-alloc ( #bytes -- vaddr ) " dma-alloc" $call-parent ;

: dma-free ( vaddr #bytes -- ) " dma-free" $call-parent ;

: open ( -- okay? ) \ open for tape

my-unit device-present? 0= if false exit then

scsi-tape-first-install if

scsi-tape-rewind if

Writing FCode 3.x Programs —November 1997

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

." Can't rewind tape" cr

0= if drop then

false exit

then

false to scsi-tape-first-install

then

\ Set fixed-len? and /tapeblock

fixed-or-variable 2drop

init-deblocker 0= if false exit then

true

;

: close ( -- )

deblocker close-package 0 to deblocker

write-eof-mark? if

write-eof if

." Can't write EOF Marker."

0= if drop then

then

;

: reset ( -- ) ... ;

: selftest ( -- fail? )

my-unit device-present? if

" send-diagnostic" $call-parent ( fail? )

else

true ( error )

then

;

: read ( addr len -- actual-len ) " read" deblocker $call-method ;

: write ( addr len -- actual-len )

true to write-eof-mark?

" write" deblocker $call-method

;

: load ( addr -- size )

\ use my-args to get tape file-no

... ( addr file# )

\ position at requested file

...

Block and Byte Devices

143

Code Example 8-3

Sample Driver for Bootable Devices (Continued)

dup begin ( start-addr next-addr )

dup max-transfer read ( start-addr next-addr #read )

dup 0> ( start-addr next-addr #read got-some? )

while ( start-addr next-addr #read )

+ ( start-addr next-addr' )

repeat ( start-addr end-addr 0 )

drop swap - ( size )

;

: seek ( byte# file# -- error? )

\ position at requested file

... ( byte# )

flush-deblocker ( byte# )

begin dup 0> while ( #remaining )

" mbuf0" $call-parent

over ublock min read ( #remaining #read )

dup 0= if ( #remaining 0 )

2drop true

exit ( error )

then ( #remaining #read )

- ( #remaining' )

repeat ( 0 )

drop false ( no-error )

;

finish-device \ finishing "byte" device "st" end0

\ finishing "SUNW,my-scsi"

144 Writing FCode 3.x Programs —November 1997

Display Devices

This chapter discusses writing FCode programs for display devices. The display device type applies to frame buffers and other devices appearing as memory to the processor, with associated hardware to convert the memory image to a visual display. Display devices can be used as console output devices.

Required Methods

The display device’s FCode must declare the display

device type, and must implement the methods open

and close

System defer

words are loaded by appropriate routines.

is-install

, isremove

and is-selftest

are used to create the open

, close

and selftest routines.

set-font

initializes the values of frame-buffer-adr

, charheight

and char-width

, all of which are built into the system ROM and can be used by any display device driver.

For display devices, created methods interact with OpenBoot commands in a way that is different from that of other device types. Other device types provide methods that are found by dictionary searches looking for specific names.

Some FCodes are specifically designed for display devices. See Table A-36 through Table A-42 in Appendix , “FCode Reference".

145

Required Properties

Table 9-1

Required Display Device Properties

Property Name

name reg device_type

Typical Value

SUNW,cgsix list of registers {device dependent}

" display" {required for display devices}

Device Driver Examples

Simple Display Device Driver

This is a sample FCode program for a display device that does not need to be usable as a console display device during system power-up.

Code Example 9-1

Basic Display Device Driver Example

\ cg6 (Lego) frame buffer driver fcode-version3 hex

" SUNW,cgsix" name

" SUNW,501-xxxx" model h# 20.0000 constant dac-offset h# 10 constant /dac h# 30.0000 constant fhc-offset h# 10 constant /fhc h# 30.1800 constant thc-offset h# 20 constant /thc h# 70.0000 constant fbc-offset h# 10 constant /fbc h# 70.1000 constant tec-offset h# 10 constant /tec h# 80.0000 constant fb-offset h# 10.0000 constant /frame

: >reg-spec ( offset size -- encoded-reg )

>r 0 my-address d+ my-space encode-phys 0 encode-int encode+ r> encode-int encode+

;

0 0 >reg-spec \ Configuration space registers dac-offset /dac >reg-spec encode+ fhc-offset /fhc >reg-spec encode+ thc-offset /thc >reg-spec encode+

146 Writing FCode 3.x Programs —November 1997

Code Example 9-1

Basic Display Device Driver Example (Continued) fbc-offset /fbc >reg-spec encode+ tec-offset /tec >reg-spec encode+ fb-offset /frame >reg-spec encode+

" reg" property end0

Extended Display Device Driver

This sample FCode program has additional functionality to initialize and test the device, but still is not usable as a console display device during system power-up.

Code Example 9-2

Extended Display Device Driver Example

\ cg6 (Lego) frame buffer driver fcode-version3 hex

" SUNW,cgsix" name

: >reg-spec ( offset size -- encoded-reg )

>r 0 my-address d+ my-space encode-phys 0 encode-int encode+ r> encode-int encode+

;

0 0 >reg-spec \ Configuration space registers dac-offset /dac >reg-spec encode+ fhc-offset /fhc >reg-spec encode+ thc-offset /thc >reg-spec encode+ fbc-offset /fbc >reg-spec encode+ tec-offset /tec >reg-spec encode+ fb-offset /frame >reg-spec encode+

" reg" property

Display Devices

147

148

Code Example 9-2

Extended Display Device Driver Example (Continued)

-1 value dac-addr

-1 value fhc-addr

-1 value thc-addr

-1 value fbc-addr

-1 value tec-addr

-1 value fb-addr

: do-map-in ( offset size -- )

>r ( offset ) ( R: size ) \ Move size to return stack

0 ( offset 0 ) ( R: size ) \ Convert offset to double number

my-address ( offset 0 phys.lo phys.mid ) ( R: size )

d+ ( phys.lo’ phys.mid ) ( R: size )

my-space r> ( phys.lo’ phys.mid phys.hi size ) ( R: )

" map-in" $call-parent

;

: do-map-out ( vaddr size -- ) " map-out" $call-parent ;

: dac-map ( -- ) dac-offset /dac do-map-in to dac-addr ;

: dac-unmap ( -- ) dac-addr /dac do-map-out -1 to dac-addr ;

: fhc-map ( -- ) fhc-offset /fhc do-map-in to fhc-addr ;

: fhc-unmap ( -- ) fhc-addr /fhc do-map-out -1 to fhc-addr ;

: thc-map ( -- ) thc-offset /thc do-map-in to thc-addr ;

: thc-unmap ( -- ) thc-addr /thc do-map-out -1 to thc-addr ;

: fbc-map ( -- ) fbc-offset /fbc do-map-in to fbc-addr ;

: fbc-unmap ( -- ) fbc-addr /fbc do-map-out -1 to fbc-addr ;

: tec-map ( -- ) tec-offset /tec do-map-in to tec-addr ;

: tec-unmap ( -- ) tec-addr /tec do-map-out -1 to tec-addr ;

: fb-map ( -- ) fb-offset /frame do-map-in to fb-addr ;

: fb-unmap ( -- ) fb-addr /frame do-map-out -1 to fb-addr ;

: map-regs ( -- ) dac-map fhc-map thc-map fbc-map tec-map ;

: unmap-regs ( -- ) tec-unmap fbc-unmap thc-unmap fhc-unmap dac-unmap ;

\ Brooktree DAC interface section

\ The Brooktree DAC has an internal address register which helps to select the

\ internal register which is to be accessed. First, the address is written to

Writing FCode 3.x Programs —November 1997

Code Example 9-2

Extended Display Device Driver Example (Continued)

\ register 0, then the data is written to one of the other registers. Ibis has 3

\ separate DAC chips which appear as the three least-significant bytes of a

\ longword. All three chips may be simultaneously updated with a single longword

\ write.

: dac! ( data reg# -- ) >r dup 2dup bljoin r> dac-addr + l! ;

: dac-ctl! ( data int.addr reg# -- ) swap 0 dac! dac! ;

\ color! sets an overlay color register.

\ In order to be able to use either the Brooktree 457 or 458 dacs, we set the address

\ once, then store the color 3 times. The chip internally cycles each time the color

\ register is written, selecting in turn the red color, the green color, and the blue

\ color. The chip is used in "RGB mode".

: color! ( r g b c# -- )

0 dac! ( r g b )

swap rot ( b g r )

4 dac! ( b g )

4 dac! ( b )

4 dac! ( )

;

: lego-init-dac ( -- )

40 06 8 dac-ctl! \ Control reg: enable off, overlay off, RGB on

0 05 8 dac-ctl! \ Blinking off

ff 04 8 dac-ctl! \ Read mask set to all ones

ff ff ff 0 color! \ White in overlay background color register

0 0 0 ff color! \ Black in overlay foreground color register

64 41 b4 1 color! \ SUN-blue for logo

;

\ End of Brooktree DAC code

\ Lego Selftest section

: fbc! ( value offset -- ) fbc-addr + l! ;

: fbc@ ( offset -- value ) fbc-addr + l@ ;

: tec! ( value offset -- ) tec-addr + l! ;

: lego-selftest ( -- failed? ) false ;

\ Hardware configuration register section

Display Devices

149

150

Code Example 9-2

Extended Display Device Driver Example (Continued)

: fhc! ( value offset -- ) fhc-addr + l! ;

: thc! ( value offset -- ) thc-addr + l! ;

: set-res-params ( hcvd hcvs hchd hchsdvb hchs fhc-conf -- )

0 fhc! 0 thc! 4 thc! 8 thc! c thc! 10 thc!

;

\ Resolution params: hcvd hcvs hchd hchsdvb hchs fhc-conf

: r1024x768 ( -- params ) 2c032c 32c0005 110051 490000 510007 3bb ;

: r1152x900 ( -- params ) 2403a8 10005 15005d 570000 10009 bbb ;

: r1024x1024 ( -- params ) 200426 10005 180054 520000 10009 3bb ;

: r1152x870 ( -- params ) 2c0392 20005 120054 540000 10009 bbb ;

: r1600x1280 ( -- params ) 340534 534009 130045 3d0000 450007 1bbb ;

0 value lego-rez-width

0 value lego-rez-height

0 value sense-code

: set-resolution ( sense-code -- )

case

0 of d# 1152 d# 900 endof

12 of d# 1024 d# 1024 endof

13 of d# 1600 d# 1280 endof

drop d# 1152 d# 900 0

endcase

to lego-rez-height to lego-rez-width

;

8f value thc-misc

: lego-video-on ( -- ) thc-misc 400 or 18 thc! ;

: lego-video-off ( -- ) thc-misc 18 thc! ;

: lego-init-hc ( -- )

sense-code case

0 of r1152x900 endof

12 of r1024x1024 endof

13 of r1600x1280 endof

drop r1152x900 0

endcase ( resolution-params )

set-res-params

Writing FCode 3.x Programs —November 1997

Code Example 9-2

Extended Display Device Driver Example (Continued)

016b 14 thc! \ THC_HCREFRESH

148f 18 thc! \ THC_HCMISC

\ 48f 18 thc! \ THC_HCMISC

lego-video-off \ Turn video on at install time

;

\ End of hardware configuration register section end0

Complete Display Device Drive

This sample FCode program is for a device that would be usable as a system console device.

Code Example 9-3

Complete Display Device Driver Example

\ cg6 (Lego) frame buffer driver fcode-version3 hex

" SUNW,cgsix" name

" SUNW,501-xxxx" model

" display" device-type h# 20.0000 constant dac-offset h# 10 constant /dac h# 30.0000 constant fhc-offset h# 10 constant /fhc h# 30.1800 constant thc-offset h# 20 constant /thc h# 70.0000 constant fbc-offset h# 10 constant /fbc h# 70.1000 constant tec-offset h# 10 constant /tec h# 80.0000 constant fb-offset h# 10.0000 constant /frame

: >reg-spec ( offset size -- encoded-reg )

>r 0 my-address d+ my-space encode-phys 0 encode-int encode+ r> encode-int encode+

;

Display Devices

151

152

Code Example 9-3

Complete Display Device Driver Example (Continued) fb-offset /frame >reg-spec encode+

" reg" property

-1 value dac-addr

-1 value fhc-addr

-1 value thc-addr

-1 value fbc-addr

-1 value tec-addr

-1 value fb-addr

: do-map-in ( offset size -- )

>r ( offset ) ( R: size ) \ Move size to return stack

0 ( offset 0 ) ( R: size ) \ Convert offset to double number

my-address ( offset 0 phys.lo phys.mid ) ( R: size )

d+ ( phys.lo’ phys.mid ) ( R: size )

my-space r> ( phys.lo’ phys.mid phys.hi size ) ( R: )

" map-in" $call-parent

;

: do-map-out ( vaddr size -- ) " map-out" $call-parent ;

: dac-map ( -- ) dac-offset /dac do-map-in to dac-addr ;

: dac-unmap ( -- ) dac-addr /dac do-map-out -1 to dac-addr ;

: fhc-map ( -- ) fhc-offset /fhc do-map-in to fhc-addr ;

: fhc-unmap ( -- ) fhc-addr /fhc do-map-out -1 to fhc-addr ;

: thc-map ( -- ) thc-offset /thc do-map-in to thc-addr ;

: thc-unmap ( -- ) thc-addr /thc do-map-out -1 to thc-addr ;

: fbc-map ( -- ) fbc-offset /fbc do-map-in to fbc-addr ;

: fbc-unmap ( -- ) fbc-addr /fbc do-map-out -1 to fbc-addr ;

: tec-map ( -- ) tec-offset /tec do-map-in to tec-addr ;

: tec-unmap ( -- ) tec-addr /tec do-map-out -1 to tec-addr ;

: fb-map ( -- ) fb-offset /frame do-map-in to fb-addr ;

: fb-unmap ( -- ) fb-addr /frame do-map-out -1 to fb-addr ;

: map-regs ( -- ) dac-map fhc-map thc-map fbc-map tec-map ;

: unmap-regs ( -- ) tec-unmap fbc-unmap thc-unmap fhc-unmap dac-unmap ;

\ Brooktree DAC interface section

Writing FCode 3.x Programs —November 1997

Code Example 9-3

Complete Display Device Driver Example (Continued)

\ The Brooktree DAC has an internal address register which helps to

\ select the internal register which is to be accessed.

\ First, the address is written to register 0, then the data is written

\ to one of the other registers.

\ Ibis has 3 separate DAC chips which appear as the three least-significant

\ bytes of a longword. All three chips may be simultaneously updated

\ with a single longword write.

: dac! ( data reg# -- ) >r dup 2dup bljoin r> dac-addr + l! ;

: dac-ctl! ( data int.addr reg# -- ) swap 0 dac! dac! ;

\ color! sets an overlay color register.

\ In order to be able to use either the Brooktree 457 or 458 dacs, we

\ set the address once, then store the color 3 times. The chip internally

\ cycles each time the color register is written, selecting in turn the

\ red color, the green color, and the blue color.

\ The chip is used in "RGB mode".

: color! ( r g b c# -- )

0 dac! ( r g b )

swap rot ( b g r )

4 dac! ( b g )

4 dac! ( b )

4 dac! ( )

;

: lego-init-dac ( -- )

40 06 8 dac-ctl! \ Control reg: enable off, overlay off, RGB on

0 05 8 dac-ctl! \ Blinking off

ff 04 8 dac-ctl! \ Read mask set to all ones

ff ff ff 0 color! \ White in overlay background color register

0 0 0 ff color! \ Black in overlay foreground color register

64 41 b4 1 color! \ SUN-blue for logo

;

\ End of Brooktree DAC code

\ Lego Selftest section

: fbc! ( value offset -- ) fbc-addr + l! ;

: fbc@ ( offset -- value ) fbc-addr + l@ ;

: tec! ( value offset -- ) tec-addr + l! ;

Display Devices

153

154

Code Example 9-3

Complete Display Device Driver Example (Continued)

: lego-selftest ( -- failed? ) false ;

\ Hardware configuration register section

: fhc! ( value offset -- ) fhc-addr + l! ;

: thc! ( value offset -- ) thc-addr + l! ;

: set-res-params ( hcvd hcvs hchd hchsdvb hchs fhc-conf -- )

0 fhc! 0 thc! 4 thc! 8 thc! c thc! 10 thc!

;

\ Resolution params: hcvd hcvs hchd hchsdvb hchs fhc-conf

: r1024x768 ( -- params ) 2c032c 32c0005 110051 490000 510007 3bb ;

: r1152x900 ( -- params ) 2403a8 10005 15005d 570000 10009 bbb ;

: r1024x1024 ( -- params ) 200426 10005 180054 520000 10009 3bb ;

: r1152x870 ( -- params ) 2c0392 20005 120054 540000 10009 bbb ;

: r1600x1280 ( -- params ) 340534 534009 130045 3d0000 450007 1bbb ;

0 value lego-rez-width

0 value lego-rez-height

0 value sense-code

: set-resolution ( sense-code -- )

case

0 of d# 1152 d# 900 endof

12 of d# 1024 d# 1024 endof

13 of d# 1600 d# 1280 endof

drop d# 1152 d# 900 0

endcase

to lego-rez-height to lego-rez-width

;

8f value thc-misc

: lego-video-on ( -- ) thc-misc 400 or 18 thc! ;

: lego-video-off ( -- ) thc-misc 18 thc! ;

: lego-blink ( -- ) lego-video-off 20 ms lego-video-on ;

: lego-init-hc ( -- )

sense-code case

0 of r1152x900 endof

12 of r1024x1024 endof

13 of r1600x1280 endof

Writing FCode 3.x Programs —November 1997

Code Example 9-3

Complete Display Device Driver Example (Continued)

drop r1152x900 0

endcase ( resolution-params )

set-res-params

016b 14 thc! \ THC_HCREFRESH

148f 18 thc! \ THC_HCMISC

lego-video-off \ Turn video on at install time

;

\ End of hardware configuration register section

\ Lego graphics section

: lego-install ( -- )

map-regs fb-map fb-addr to frame-buffer-adr

default-font ( param ... ) set-font

frame-buffer-adr encode-int " address" property

lego-rez-width lego-rez-height over char-width / over char-height /

fb8-install

['] lego-blink to blink-screen

lego-video-on

;

: lego-remove ( -- )

lego-video-off

unmap-regs

fb-unmap -1 to frame-buffer-adr

;

\ End of Lego graphics section

: lego-probe ( -- )

map-regs

sense-code set-resolution

lego-init-dac

lego-init-hc

unmap-regs

Display Devices

155

Code Example 9-3

Complete Display Device Driver Example (Continued)

lego-rez-width encode-int " width" property

lego-rez-height encode-int " height" property

d# 8 encode-int " depth" property

lego-rez-width encode-int " linebytes" property

['] lego-install is-install

['] lego-remove is-remove

['] lego-selftest is-selftest

; lego-probe end0

156 Writing FCode 3.x Programs —November 1997

Memory-Mapped Buses

This chapter discusses addressing and required properties for memorymapped buses.

A memory-mapped bus logically extends the processor’s memory address space to include the devices on that bus. This enables the children of the bus device to be mapped into the CPU address space and accessed like memory using processor load and store cycles to address those children directly.

SBus and VMEbus are examples of memory-mapped buses.

Not all bus devices fall into this category. For example, SCSI is not a memory-mapped bus; SCSI targets are not accessed with load or store instructions.

Required Methods

A memory-mapped bus package code must implement the open

, close

, reset

, and selftest

methods, as well as the following:

decode-unit

( addr len -- phys.lo … phys.hi )

Convert addr len, a text string representation, to phys.lo

… phys.hi

, a numerical representation of a physical address in the address space defined by this package. The format of phys.lo

… phys.hi

varies from bus to bus.

157

158

dma-alloc

( size -- virt )

Allocate a virtual address range of length size bytes that is suitable for direct memory access by a bus master device. The memory is allocated according to the most stringent alignment requirements for the bus. virt is a 32-bit address that the OpenBoot-based system can use to access the memory.

Note that dma-map-in

must also be called to generate a suitable DMA address.

A child of a memory-mapped device calls dma-alloc

using

" dma-alloc" $call-parent

For example:

-1 value my-vaddr

: my-dma-alloc ( size -- )

" dma-alloc" $call-parent to my-vaddr

;

dma-free

( virt size -- )

Free size bytes of memory previously allocated by dma-alloc

at the virtual address virt.

A child of a memory-mapped device calls dma-free

by using

" dma-free" $call-parent

For example:

2000 value my-size

: my-dma-free ( -- )

my-vaddr my-size " dma-free" $call-parent

-1 to my-vaddr

;

Writing FCode 3.x Programs —November 1997

dma-map-in

( virt size cacheable? -- devaddr )

Convert the virtual address range virt size, previously allocated by dmaalloc

, into an address devaddr suitable for DMA on the bus.

dma-map-in can also be used to map application-supplied data buffers for DMA use if the bus allows. If cacheable?

is true, the calling child desires to use any available fast caches for the DMA buffer. If access to the buffer is required before the buffer is mapped out, the child must call dma-sync

or dma-map-out

to ensure cache coherency with memory.

A child of a memory-mapped device calls dma-map-in

using

" dma-map-in" $call-parent

For example:

: my-vaddr-dma-map ( -- )

my-vaddr my-size false " dma-map-in" $call-parent ( devaddr )

to my-vaddr-dma

;

dma-map-out

( virt devaddr size -- )

Remove the DMA mapping previously created with dma-map-in

. Flush all caches associated with the mapping.

A child of a memory-mapped device calls dma-map-out

by using

" dma-map-out" $call-parent

For example:

: my-vaddr-dma-free ( -- )

my-vaddr my-vaddr-dma my-size " dma-map-out" $call-parent

-1 to my-vaddr-dma

;

Memory-Mapped Buses

159

160

dma-sync

( virt devaddr size -- )

Synchronize (flush) any memory caches associated with the DMA mapping previously established by dma-map-in

. You must interleave calls to this method (or dma-map-out

) between DMA and CPU accesses to the memory region, or you may not obtain the most recent data written into the cache.

For example, a child of a hierarchical device calls dma-sync

by using

$callparent

. This method is valid for FCode version 2.1 or later. Some early version 2 systems do not define this method in the

/sbus

node. Those systems automatically synchronize DMA and CPU access. The following example will give correct results in all cases.

: my-dma-sync ( virt devadr size -- )

" dma-sync" $call-parent

;

probe-self

( arg-addr arg-len reg-addr reg-len fcode-addr fcode-len -- )

Probe for a child of this node. fcode-addr fcode-len is a unit-address text string that identifies the location of the FCode program for the child. reg-addr reg-len is a probe-address text string that identifies the address of the child itself. argaddr arg-len is an instance-arguments text string for any device arguments for the child (which can be retrieved in the child’s FCode program with the myargs

FCode).

probe-self

checks whether there is indeed FCode at the indicated location, perhaps by mapping the device and using cpeek

to ensure that the device is present and that the first byte is a valid FCode start byte.

If the FCode exists, probe-self

creates a new child device node and interprets the FCode. If the interpretation of the FCode fails in some way, the new device node may be empty, containing no properties or methods.

For example, to probe FCode for SBus slot #1:

" /sbus" open-dev

0 0 " 1,0" 2dup probe-self device-end

Writing FCode 3.x Programs —November 1997

map-in

( phys.lo … phys.hi size -- virt )

Create a mapping associating the range of physical addresses beginning at phys.lo … phys.hi

extending for size bytes in the package’s physical address space with a processor virtual address virt

The number of cells in the list phys.lo … phys.hi

is determined by the value of the

"#address-cells"

property of the node containing map-in

For example, a child of a memory-mapped device calls map-in

with

" mapin" $call-parent

. (The following example assumes that the value of the parent’s

"#address-cells"

property is 3):

: map-reg ( -- )

my-address xx-offset 0 d+ my-space ( phys.lo phys.mid phys.hi )

xx-size " map-in" $call-parent ( virt )

to xx-vaddr ( )

;

map-out

( virt size -- )

Destroy the mapping set by map-in

at virtual address virt of length size bytes.

For example, a child of a memory-mapped device calls map-out

with

" mapout" $call-parent

: unmap-reg ( -- )

xx-vaddr xx-size ( virt size )

" map-out" $call-parent ( )

-1 to xx-vaddr

;

SBus Addressing

The SBus uses geographical addressing with numbered slots.

An SBus physical address is represented numerically by the SBus slot number as the high number and the offset from the base of that slot as the low number.

The text string representation is slot#, offset where both slot# and offset are the

ASCII representations of hexadecimal numbers.

Memory-Mapped Buses

161

SBus Required Properties

Table 10-1 SBus Required Properties

Property Name Sample Value

name burst-sizes

" SUNW,fas" device_type ranges slot-address-bits

" sbus"

Device Driver Examples

The following examples of a hierarchical FCode driver are based on Sun's SBus expansion hardware, XBox. XBox increases the number of SBus slots available in a system by providing a bus-bridge between the platform's onboard SBus and an SBus in the XBox hardware. XBox includes an SBus card called the

XAdaptor card which plugs into the host platform's SBus and includes an expansion chassis called the XBox Expansion Box. Therefore XBox is an example of a hierarchical device which implements an SBus interface to child plug-in devices.

The example is divided into three parts: the basic device driver, the extended device driver, and the complete device driver. In the case of a hierarchical device, in practice, one would only want to develop and ship a driver with the complete functionality. Otherwise, plug-in cards which rely on a full set of parent services generally would not be able to function. The three stage presentation of the driver simply shows how a driver might grow through the development cycle.

162 Writing FCode 3.x Programs —November 1997

Basic Hierarchical Device Driver

The basic driver simply declares most of the important properties of the device, particularly the addresses of the various registers. A driver in this state might be used to support the development of the OS driver which would attach to the device name and configure itself based on the device properties published by the FCode driver.

Code Example 10-1 Basic Hierarchical Device Driver hex fcode-version3

" SUNW,xbox" name

" 501-1840" model

\ XBox Registers

\ XAdaptor card registers h# 0 constant write0-offset h# 4 constant /write0 h# 2.0000 constant xac-err-offset h# c constant /xac-err h# 10.0000 constant xac-ctl0-offset h# 4 constant /xac-ctl0 h# 11.0000 constant xac-ctl1-offset h# 4 constant /xac-ctl1 h# 12.0000 constant xac-elua-offset h# 4 constant /xac-elua h# 13.0000 constant xac-ella-offset h# 4 constant /xac-ella h# 14.0000 constant xac-ele-offset h# 4 constant /xac-ele

\ XBox Exapnsion box registers h# 42.0000 constant xbc-err-offset h# c constant /xbc-err h# 50.0000 constant xbc-ctl0-offset h# 4 constant /xbc-ctl0 h# 51.0000 constant xbc-ctl1-offset h# 4 constant /xbc-ctl1 h# 52.0000 constant xbc-elua-offset h# 4 constant /xbc-elua h# 53.0000 constant xbc-ella-offset h# 4 constant /xbc-ella h# 54.0000 constant xbc-ele-offset h# 4 constant /xbc-ele

: >reg-spec ( offset size -- xdrreg )

>r my-address + my-space encode-phys r> encode-int encode+

Memory-Mapped Buses

163

164

Code Example 10-1 Basic Hierarchical Device Driver (Continued) xac-ele-offset /xac-ele >reg-spec encode+ xbc-err-offset /xbc-err >reg-spec encode+ xbc-ctl0-offset /xbc-ctl0 >reg-spec encode+ xbc-ctl1-offset /xbc-ctl1 >reg-spec encode+ xbc-elua-offset /xbc-elua >reg-spec encode+ xbc-ella-offset /xbc-ella >reg-spec encode+ xbc-ele-offset /xbc-ele >reg-spec encode+

" reg" property

\ Xbox can interrupt on any SBus level

1 encode-int 2 encode-int encode+ 3 encode-int encode+ 4 encode-int encode+

5 encode-int encode+ 6 encode-int encode+ 7 encode-int encode+

" interrupts" property

1 sbus-intr>cpu encode-int 0 encode-int encode+

2 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

3 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

4 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

5 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

6 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

7 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

" intr" property

\ XBox bus clock speed d# 25.000.000 encode-int " clock-frequency" property

\ Burst sizes 64,32,16,8,4,2,1 bursts.

h# 7f encode-int " burst-sizes" property

\ XBox has no slave-only slots

0 encode-int " slave-only" property

\ Get the number of address bits for this SBus slot from the parent SBus

\ node without inheritance . OpenBoot 2.5 doesn't publish slot-address-bits.

\ However 2.5 is only on 4m machines, which are all 28 bits per slot.

: $= ( addr1 len1 addr2 len2 -- equal? ) \ string compare

rot over - if

drop 2drop false \ different lengths

else comp 0=

then

;

Writing FCode 3.x Programs —November 1997

Code Example 10-1 Basic Hierarchical Device Driver (Continued)

: 4mhack ( -- n )

" compatible" get-inherited-property if

d# 25 \ no "compatible" prop; assume 4c

else decodestring " sun4m" $= if

d# 28

else

d# 25 \ not sun4m

then

nip nip

then

;

: #bits ( -- n )

" slot-address-bits" my-parent ihandle>phandle

get-package-property if

4mhack

else

decode-int nip nip

then

;

#bits constant host-slot-size host-slot-size encode-int " slot-address-bits" property end0

Extended Hierarchical Device Driver

The extended driver adds methods allowing access to various device registers in addition to the functions of the basic driver. It provides methods to:

•

Map in the registers

•

Fetch from and store to the registers

•

Program one of the registers which control the allocation of address space across the various SBus slots.

Memory-Mapped Buses

165

166

Such an extended driver provides methods that a developer can use to read and write registers and verify correct hardware responses. Note that the complete driver does not use all of the device registers; read/write access methods were included for all of them to allow easy testing during development.

Code Example 10-2 Extended Hierarchical Device Driver hex fcode-version3

" SUNW,xbox" name

" 501-1840" model

\ XBox Registers h# 0 constant write0-offset h# 4 constant /write0 h# 2.0000 constant xac-err-offset h# c constant /xac-err h# 10.0000 constant xac-ctl0-offset h# 4 constant /xac-ctl0 h# 11.0000 constant xac-ctl1-offset h# 4 constant /xac-ctl1 h# 12.0000 constant xac-elua-offset h# 4 constant /xac-elua h# 13.0000 constant xac-ella-offset h# 4 constant /xac-ella h# 14.0000 constant xac-ele-offset h# 4 constant /xac-ele h# 42.0000 constant xbc-err-offset h# c constant /xbc-err h# 50.0000 constant xbc-ctl0-offset h# 4 constant /xbc-ctl0 h# 51.0000 constant xbc-ctl1-offset h# 4 constant /xbc-ctl1 h# 52.0000 constant xbc-elua-offset h# 4 constant /xbc-elua h# 53.0000 constant xbc-ella-offset h# 4 constant /xbc-ella h# 54.0000 constant xbc-ele-offset h# 4 constant /xbc-ele

: >reg-spec ( offset size -- xdrreg )

>r my-address + my-space encode-phys r> encode-int encode+

Writing FCode 3.x Programs —November 1997

Code Example 10-2 Extended Hierarchical Device Driver (Continued) xbc-ctl0-offset /xbc-ctl0 >reg-spec encode+ xbc-ctl1-offset /xbc-ctl1 >reg-spec encode+ xbc-elua-offset /xbc-elua >reg-spec encode+ xbc-ella-offset /xbc-ella >reg-spec encode+ xbc-ele-offset /xbc-ele >reg-spec encode+

" reg" property

\ Xbox can interrupt on any SBus level

1 encode-int 2 encode-int encode+ 3 encode-int encode+ 4 encode-int encode+

5 encode-int encode+ 6 encode-int encode+ 7 encode-int encode+

" interrupts" property

1 sbus-intr>cpu encode-int 0 encode-int encode+

2 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

3 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

4 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

5 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

6 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

7 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

" intr" property

\ XBox bus clock speed d# 25.000.000 encode-int " clock-frequency" property

\ Burst sizes 64,32,16,8,4,2,1 bursts.

h# 7f encode-int " burst-sizes" property

\ XBox has no slave-only slots

0 encode-int " slave-only" property

\ Get the number of address bits for this SBus slot from the parent SBus

\ node without inheritance . OpenBoot 2.5 doesn't publish slot-address-bits.

\ However 2.5 is only on 4m machines, which are all 28 bits per slot.

: $= ( addr1 len1 addr2 len2 -- equal? ) \ string compare

rot over - if

drop 2drop false \ different lengths

else comp 0=

then

;

: 4mhack ( -- n )

" compatible" get-inherited-property if

Memory-Mapped Buses

167

168

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

d# 25 \ no "compatible" prop; assume 4c

else decodestring " sun4m" $= if

d# 28

else

d# 25 \ not sun4m

then

nip nip

then

;

: #bits ( -- n )

" slot-address-bits" my-parent ihandle>phandle

get-package-property if

4mhack

else

decode-int nip nip

then

;

#bits constant host-slot-size host-slot-size encode-int " slot-address-bits" property

\ Utility display string

: .me ( -- ) ." SBus " my-space .d ." XBox " ;

\ The XBox device has two modes opaque and transparent.

\ Upon reset the device is set to opaque mode. In this mode all

\ accesses to address space of the device are directed to the XBox H/W

\ (ie. XAdaptor Card or the XBox Expansion Box) itself.

\ In the transparent mode all accesses are mapped to the SBus cards

\ which are plugged into the XBox. In transparent mode the XBox H/W is

\ accessible only via the "write-0" register. To allow another bus

\ bridge to be plugged into the XBox all writes to the write-0 register

\ must contain a "key" which is programmed into the XBox H/W at boot

\ time. If the key field of a write to write-0 matches that programmed

\ at boot time the H/W intercepts the write. Otherwise the H/W passes

\ the write along.

\ The XBox has two sets of registers. Those of the XAdaptor card and

\ and those of the XBox Expansion Box.

\ Opaque mode host adapter registers

Writing FCode 3.x Programs —November 1997

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

-1 value xac-err-regs

-1 value xac-ctl0 -1 value xac-ctl1

-1 value xac-elua -1 value xac-ella

-1 value xac-ele

\ Opaque mode expansion box registers

-1 value xbc-err-regs

-1 value xbc-ctl0 -1 value xbc-ctl1

-1 value xbc-elua -1 value xbc-ella

-1 value xbc-ele

\ Transparent mode register

-1 value write0-reg

: xbox-map-in ( offset space size -- virt ) " map-in" $call-parent ;

: xbox-map-out ( virt size -- ) " map-out" $call-parent ;

: map-regs ( -- )

write0-offset my-address + my-space /write0 xbox-map-in to write0-reg

xac-err-offset my-address + my-space /xac-err xbox-map-in to xac-err-regs

xac-ctl0-offset my-address + my-space /xac-ctl0 xbox-map-in to xac-ctl0

xac-ctl1-offset my-address + my-space /xac-ctl1 xbox-map-in to xac-ctl1

xac-elua-offset my-address + my-space /xac-elua xbox-map-in to xac-elua

xac-ella-offset my-address + my-space /xac-ella xbox-map-in to xac-ella

xac-ele-offset my-address + my-space /xac-ele xbox-map-in to xac-ele

xbc-err-offset my-address + my-space /xbc-err xbox-map-in to xbc-err-regs

xbc-ctl0-offset my-address + my-space /xbc-ctl0 xbox-map-in to xbc-ctl0

xbc-ctl1-offset my-address + my-space /xbc-ctl1 xbox-map-in to xbc-ctl1

xbc-elua-offset my-address + my-space /xbc-elua xbox-map-in to xbc-elua

xbc-ella-offset my-address + my-space /xbc-ella xbox-map-in to xbc-ella

xbc-ele-offset my-address + my-space /xbc-ele xbox-map-in to xbc-ele

;

: unmap-regs ( -- )

write0-reg /write0 xbox-map-out -1 to write0-reg

xac-err-regs /xac-err xbox-map-out -1 to xac-err-regs

xac-ctl0 /xac-ctl0 xbox-map-out -1 to xac-ctl0

xac-ctl1 /xac-ctl1 xbox-map-out -1 to xac-ctl1

xac-elua /xac-elua xbox-map-out -1 to xac-elua

xac-ella /xac-ella xbox-map-out -1 to xac-ella

xac-ele /xac-ele xbox-map-out -1 to xac-ele

xbc-err-regs /xbc-err xbox-map-out -1 to xbc-err-regs

xbc-ctl0 /xbc-ctl0 xbox-map-out -1 to xbc-ctl0

xbc-ctl1 /xbc-ctl1 xbox-map-out -1 to xbc-ctl1

xbc-elua /xbc-elua xbox-map-out -1 to xbc-elua

xbc-ella /xbc-ella xbox-map-out -1 to xbc-ella

xbc-ele /xbc-ele xbox-map-out -1 to xbc-ele

Memory-Mapped Buses

169

170

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

;

\ Opaque mode register access words

: xac-errd@ ( -- l ) xac-err-regs rl@ ;

: xac-erra@ ( -- l ) xac-err-regs 4 + rl@ ;

: xac-errs@ ( -- l ) xac-err-regs 8 + rl@ ;

: xac-ctl0@ ( -- w ) xac-ctl0 rl@ ;

: xac-ctl0! ( w -- ) xac-ctl0 rl! ;

: xac-ctl1@ ( -- w ) xac-ctl1 rl@ ;

: xac-ctl1! ( w -- ) xac-ctl1 rl! ;

: xac-elua@ ( -- l ) xac-elua rl@ ;

: xac-elua! ( l -- ) xac-elua rl! ;

: xac-ella@ ( -- w ) xac-ella rl@ ;

: xac-ella! ( w -- ) xac-ella rl! ;

: xbc-errd@ ( -- l ) xbc-err-regs rl@ ;

: xbc-erra@ ( -- l ) xbc-err-regs 4 + rl@ ;

: xbc-errs@ ( -- l ) xbc-err-regs 8 + rl@ ;

: xbc-ctl0@ ( -- w ) xbc-ctl0 rl@ ;

: xbc-ctl0! ( w -- ) xbc-ctl0 rl! ;

: xbc-ctl1@ ( -- w ) xbc-ctl1 rl@ ;

: xbc-ctl1! ( w -- ) xbc-ctl1 rl! ;

: xbc-elua@ ( -- l ) xbc-elua rl@ ;

: xbc-elua! ( l -- ) xbc-elua rl! ;

: xbc-ella@ ( -- w ) xbc-ella rl@ ;

: xbc-ella! ( w -- ) xbc-ella rl! ;

\ Transparent Mode register access words external

: unique-key ( -- n ) " unique-key" $call-parent ; headers unique-key constant my-key my-key encode-int " write0-key" property

: xbox! ( w offset -- ) my-key h# 18 << or or write0-reg rl! ;

: write-xac-ctl0 ( w -- ) xac-ctl0-offset xbox! ;

: write-xac-ctl1 ( w -- ) xac-ctl1-offset xbox! ;

: write-xbc-ctl0 ( w -- ) xbc-ctl0-offset xbox! ;

: write-xbc-ctl1 ( w -- ) xbc-ctl1-offset xbox! ;

Writing FCode 3.x Programs —November 1997

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

\ Some functionally oriented words

: set-key ( -- ) my-key 8 << xac-ctl0! ;

: transparent ( -- ) 1 xac-ctl1! ;

: opaque ( -- ) 0 write-xac-ctl1 ;

: enable-slaves ( -- ) h# 38 write-xbc-ctl1 ;

: xbox-errors ( -- xbc-err xac-err )

opaque xbc-errd@ xac-errd@ transparent

;

: ?.errors ( xbc-err xac-err -- )

dup h# 8000.0000 and if

cr .me ." xac-error " .h cr

else drop

then

dup h# 8000.0000 and if

cr .me ." xbc-error " .h cr

else drop

then

;

\ The address space of the XBox in transparent mode may be dynamically

\ allocated across its plug-in slots. This is called the

\ upper-address-decode-map (uadm). Below is a table which relates the

\ slot configuration code which is programmed in hardware to the

\ allocation of address space for each slot. The number in each cell is

\ the number of address bits needed for the slot.

decimal create slot-sizes-array

\ slot0 slot1 slot2 slot3 slot-config

23 c, 23 c, 23 c, 23 c, \ 00

23 c, 23 c, 23 c, 23 c, \ 01

23 c, 23 c, 23 c, 23 c, \ 02

23 c, 23 c, 23 c, 23 c, \ 03

25 c, 0 c, 0 c, 0 c, \ 04

0 c, 25 c, 0 c, 0 c, \ 05

0 c, 0 c, 25 c, 0 c, \ 06

0 c, 0 c, 0 c, 25 c, \ 07

24 c, 24 c, 0 c, 0 c, \ 08

24 c, 0 c, 24 c, 0 c, \ 09

0 c, 24 c, 24 c, 0 c, \ 0a

Memory-Mapped Buses

171

172

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

0 c, 0 c, 0 c, 0 c, \ 0b

24 c, 23 c, 23 c, 0 c, \ 0c

23 c, 24 c, 23 c, 0 c, \ 0d \ Overridden in code

23 c, 23 c, 24 c, 0 c, \ 0e \ Overridden in code

25 c, 0 c, 0 c, 0 c, \ 0f

26 c, 26 c, 26 c, 26 c, \ 10

26 c, 26 c, 26 c, 26 c, \ 11

26 c, 26 c, 26 c, 26 c, \ 12

26 c, 26 c, 26 c, 26 c, \ 13

28 c, 0 c, 0 c, 0 c, \ 14

0 c, 28 c, 0 c, 0 c, \ 15

0 c, 0 c, 28 c, 0 c, \ 16

0 c, 0 c, 0 c, 28 c, \ 17

28 c, 28 c, 28 c, 28 c, \ 18

28 c, 28 c, 28 c, 28 c, \ 19

28 c, 28 c, 28 c, 28 c, \ 1a

28 c, 28 c, 28 c, 28 c, \ 1b

0 c, 0 c, 0 c, 0 c, \ 1c

0 c, 0 c, 0 c, 0 c, \ 1d

0 c, 0 c, 0 c, 0 c, \ 1e

0 c, 0 c, 0 c, 0 c, \ 1f hex

20 constant /slot-sizes-array

-1 value slot-config

: >slot-size ( slot# -- size )

slot-sizes-array slot-config la+ swap ca+ c@ 1 swap <<

1 not and \ Could have slot size of 0.

;

\ This array is to be filled with offsets for each slot.

\ Eg. 0, 100.0000, 180.0000, 200.0000

create host-offsets 0 , 0 , 0 , 0 ,

: >host-offset ( child-slot# -- adr ) host-offsets swap na+ @ ; create config-d-offsets h# 100.0000 , 0 , h# 180.0000 , 0 , create config-e-offsets h# 100.0000 , h# 180.0000 , 0 , 0 ,

: set-host-offsets ( -- )

slot-config case

h# d of config-d-offsets host-offsets 4 /n* move exit endof

Writing FCode 3.x Programs —November 1997

Code Example 10-2 Extended Hierarchical Device Driver (Continued)

h# e of config-e-offsets host-offsets 4 /n* move exit endof

endcase

0 ( initial-offset )

4 0 do ( offset )

dup host-offsets i na+ ! ( offset )

i >slot-size + ( offset' )

loop ( final-offset )

drop

;

: set-configuration ( config-code -- )

is slot-config

set-host-offsets

slot-config 3 << my-key 8 << or

dup write-xac-ctl0 \ set XAC

write-xbc-ctl0 \ set XBC

slot-config encode-int " uadm" property \ publish slot configuration

; end0

Complete Hierarchical Device Driver

The complete driver includes all the required device node methods. It also includes code to initialize the hardware at system reset. In particular, it configures the allocation of address space across slots. It does this by either performing an autoconfiguration or by accepting a manual override via a property in its parent. During the configuration process, the driver interprets the FCode of any SBus card plugged into the XBox. This results in devices being added to the device tree.

Code Example 10-3 Complete Hierarchical Device Driver hex fcode-version3

" SUNW,xbox" name

" 501-1840" model

" sbus" device-type

Memory-Mapped Buses

173

174

Code Example 10-3 Complete Hierarchical Device Driver (Continued)

: >reg-spec ( offset size -- xdrreg )

>r my-address + my-space encode-phys r> encode-int encode+

; write0-offset /write0 >reg-spec xac-err-offset /xac-err >reg-spec encode+ xac-ctl0-offset /xac-ctl0 >reg-spec encode+ xac-ctl1-offset /xac-ctl1 >reg-spec encode+ xac-elua-offset /xac-elua >reg-spec encode+ xac-ella-offset /xac-ella >reg-spec encode+ xac-ele-offset /xac-ele >reg-spec encode+ xbc-err-offset /xbc-err >reg-spec encode+ xbc-ctl0-offset /xbc-ctl0 >reg-spec encode+ xbc-ctl1-offset /xbc-ctl1 >reg-spec encode+ xbc-elua-offset /xbc-elua >reg-spec encode+ xbc-ella-offset /xbc-ella >reg-spec encode+ xbc-ele-offset /xbc-ele >reg-spec encode+

" reg" property

\ Xbox can interrupt on any SBus level

1 encode-int 2 encode-int encode+ 3 encode-int encode+ 4 encode-int encode+

5 encode-int encode+ 6 encode-int encode+ 7 encode-int encode+

" interrupts" property

1 sbus-intr>cpu encode-int 0 encode-int encode+

Writing FCode 3.x Programs —November 1997

Code Example 10-3 Complete Hierarchical Device Driver (Continued)

2 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

3 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

4 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

5 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

6 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

7 sbus-intr>cpu encode-int encode+ 0 encode-int encode+

" intr" property

\ XBox bus clock speed d# 25.000.000 encode-int " clock-frequency" property

\ Burst sizes 64,32,16,8,4,2,1 bursts.

h# 7f encode-int " burst-sizes" property

\ XBox has no slave-only slots

0 encode-int " slave-only" property

\ Get the number of address bits for this SBus slot from the parent SBus

\ node without inheritance . OpenBoot 2.5 doesn't publish slot-address-bits.

\ However 2.5 is only on 4m machines, which are all 28 bits per slot.

: $= ( addr1 len1 addr2 len2 -- equal? ) \ string compare

rot over - if

drop 2drop false \ different lengths

else comp 0=

then

;

: 4mhack ( -- n )

" compatible" get-inherited-property if

d# 25 \ no "compatible" prop; assume 4c

else decode-string " sun4m" $= if

d# 28

else

d# 25 \ not sun4m

then

nip nip

then

;

: #bits ( -- n )

" slot-address-bits" my-parent ihandle>phandle

get-package-property if

4mhack

else

Memory-Mapped Buses

175

176

Code Example 10-3 Complete Hierarchical Device Driver (Continued)

decode-int nip nip

then

;

#bits constant host-slot-size host-slot-size encode-int " slot-address-bits" property

\ Utility display string

: .me ( -- ) ." SBus " my-space .d ." XBox " ;

\ The XBox device has two modes opaque and transparent.

\ Upon reset the device is set to opaque mode. In this mode all

\ accesses to address space of the device are directed to the XBox H/W

\ (ie. XAdaptor Card or the XBox Expansion Box) itself.

\ In the transparent mode all accesses are mapped to the SBus cards

\ which are plugged into the XBox. In transparent mode the XBox H/W is

\ accessible only via the "write-0" register. To allow another bus

\ bridge to be plugged into the XBox all writes to the write-0 register

\ must contain a "key" which is programmed into the XBox H/W at boot

\ time. If the key field of a write to write-0 matches that programmed

\ at boot time the H/W intercepts the write. Otherwise the H/W passes

\ the write along.

\ The XBox has two sets of registers. Those of the XAdaptor card and

\ and those of the XBox Expansion Box.

\ Opaque mode host adapter registers

-1 value xac-err-regs

-1 value xac-ctl0 -1 value xac-ctl1

-1 value xac-elua -1 value xac-ella

-1 value xac-ele

\ Opaque mode expansion box registers

-1 value xbc-err-regs

-1 value xbc-ctl0 -1 value xbc-ctl1

-1 value xbc-elua -1 value xbc-ella

-1 value xbc-ele

\ Transparent mode register

-1 value write0-reg

: xbox-map-in ( offset space size -- virt") " map-in" $call-parent ;