Digital Network Appliance Platform Binding

1 2 3 4 5 6 7 8 9 10 11 Digital Network Appliance Platform Binding to: 12 13 14 15 16 17 18 IEEE 1275-1994 19 20 21 Standard for Boot 22 23 24 (Initialization, Configuration) 25 26 27 Firmware 28 29 30 31 32 33 34 Revision: 0.2 DRAFT 35 36 37 Date: January 26, 1998 38 39 40 41 42 43 44 45 46 47 PRELIMINARY 48 49 50 51 52 53 54 Digital Network Appliance Platform Binding

1 Purpose of the Digital Network Appliance Platform 2 3 Binding 4 5 6 This document specifies the application of IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) 7 Firmware, Core Practices and Requirements to Digital Network Appliance Platform compliant computer 8 systems, including practices for client program interface and data formats. An implementation of Open Firmware 9 for a Digital Network Appliance compliant system shall implement the core requirements as defined in [1], the 10 ARM processor-specific extensions described in [2] and the Digital Network Appliance specific extensions 11 described in this binding. 12 13 14 Task Group Members 15 16 17 The Digital Network Appliance Platform Binding Team Members were the following: 18 Mitch Bradley, FirmWorks 19 20 David Chaiken, Digital Equipment Corporation 21 Greg Hill (editor), FirmWorks 22 23 Jay Kistler, Digital Equipment Corporation 24 25 26 Trademarks 27 28 29 The following terms, denoted by a registration symbol (®) or trademark symbol(™) 30 on the first occurrence in this publication, are registered trademarks or trademarks of 31 the companies as shown in the list below: 32 Trademark Company 33 34 Ethernet™ Xerox 35 36 Microsoft® Microsoft Corporation 37 MS-DOS® Microsoft Corporation 38 39 40 41 Revision History 42 43 Revision 0.2 DRAFT July 3, 1997 Initial, unapproved release. 44 Revision 0.2 DRAFT January 26, 1998 Changed name to “Digital Network Appliance Platform Bind- 45 ing”. 46 47 48 49 50 51 52 53 54

i of 7 Preliminary January 26, 1998 Revision 0.2 DRAFT Digital Network Appliance Platform Binding

1 Table of Contents 2 3 4 5 6 1. Overview...... 1 7 2. References and Terms...... 1 8 2.1 References...... 1 9 2.2 Terms ...... 1 10 3. Packages ...... 2 11 3.1 "disk-label" Support Package ...... 2 12 3.2 Program-image Formats...... 2 13 14 3.2.1 Load Address ...... 2 15 3.2.2 Load Image Formats ...... 2 16 3.2.3 a.out Format...... 3 17 3.2.4 Raw Binary Format ...... 4 18 3.3 "obp-tftp" Support Package ...... 4 19 3.3.1 Use of BOOTP...... 4 20 21 3.3.2 DHCP Support ...... 4 22 4. Properties ...... 5 23 4.1 Root Node Properties ...... 5 24 4.2 "/chosen" Node Properties ...... 5 25 4.3 "/isa" Node Properties ...... 6 26 4.4 "/isa/rtc" Node Properties ...... 6 27 28 4.5 "/openprom" Node Properties ...... 6 29 5. Extensions for Digital Network Appliance Platform Systems ...... 6 30 5.1 Display Devices ...... 6 31 5.2 Device Support ...... 7 32 5.3 Conventions for Devices on ISA ...... 7 33 5.4 "/aliases" Node Properties ...... 7 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

January 26, 1998 Revision 0.2 DRAFT Preliminary ii of 7 Digital Network Appliance Platform Binding

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

iii of 7 Preliminary January 26, 1998 Revision 0.2 DRAFT Digital Network Appliance Platform Binding

1 1. Overview 2 3 This document specifies the application of IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) 4 Firmware, Core Practices and Requirements to Digital Network Appliance compliant computer systems, 5 including practices for client program interface and data formats. An implementation of Open Firmware for a 6 Digital Network Appliance compliant system shall implement the core requirements as defined in [1], the ARM 7 processor-specific extensions described in [2] and the Digital Network Appliance specific extensions described in 8 this binding. 9 The document defines the binding to ARM platforms that use 32-bit addressing. Since the minimum cell size of 10 Open Firmware is 32 bits, only one cell is necessary to represent addresses of processor bus devices; hence the 11 value of "#address-cells" for / shall be 1. 12 13 14 2. References and Terms 15 16 2.1. References 17 18 This standard shall be used in conjunction with the following publications. When the following standards are 19 superseded by an approved revision, the revision shall apply. 20 [1] IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) Firmware, Core Practices and 21 Requirements. 22 23 [2] ARM processor binding to: IEEE Std 1275-1994, Standard for Boot (Initialization, Configuration) 24 Firmware. 25 [3] MS-DOS® Programmer's Reference, published by Microsoft®. This document describes the MS-DOS 26 partition, directory and FAT formats used by the "disk-label" support package. 27 [4] a.out file format as defined in the file include/sys/exec_aout.h of the NetBSD distribution. 28 http://www.netbsd.org. 29 30 [5] Croft, B., and J. Gilmore, Bootstrap Protocol (BOOTP), RFC 951, Stanford University and Sun 31 Microsystems, September 1985, http://ds.internic.net/rfc/rfc951.txt 32 [6] Deutsch, P., DEFLATE Compressed Data Format Specification, Version 1.3, RFC 1951, Aladdin 33 Enterprises, May 1996, htttp://ds.internic.net/rfc/rfc1951.txt 34 [7] Deutsch, P., GZIP File Format Specification, Version 4.3, RFC 1952, Aladdin Enterprises, May 1996, 35 http://ds.internic.net/rfc/rfc1952.txt 36 37 [8] Droms, R., Dynamic Host Configuration Protocol, RFC 1531, Bucknell University, October 1993, 38 http://ds.internic.net/rfc/rfc1531.txt 39 [9] Wimer, W., Clarifications and Extensions for the Bootstrap Protocol, RFC 1532, Carnegie Mellon 40 University, October 1993, http://ds.internic.net/rfc/rfc1532.txt 41 [10] ISO-9660, Information processing -- Volume and file structure of CD-ROM for information interchange, 42 published by International Organization for Standardization. 43 44 [11] Device Support Extensions to IEEE 1275-1994 Standard for Boot (Initialization, Configuration) Firmware. 45 [12] Open Firmware Recommended Practice: 16-color Text Extension. 46 [13] Open Firmware Recommended Practice: Graphics Extension. 47 48 [14] Open Firmware Recommended Practice: TFTP Extension, Version 0.8 (Unapproved Draft). 49 50 2.2. Terms 51 52 This standard uses technical terms as they are defined in the documents cited in "References", plus the following 53 terms: 54

January 26, 1998 Revision 0.2 DRAFT Preliminary 1 of 7 Digital Network Appliance Platform Binding

1 a.out: A binary object file format defined in [4] that is used to represent client programs in Open Firmware for 2 ARM. 3 core, core specification: refers to IEEE Std 1275-1994 Standard for Boot (Initialization, Configuration) 4 Firmware, Core Practices and Requirements 5 6 FDISK: Refers to the boot-record and partition table format used by MS-DOS, as defined in [3]. 7 8 Open Firmware: The firmware architecture defined by the core specification or, when used as an adjective, a 9 software component compliant with the core specification. 10 11 3. Packages 12 13 This section describes the Digital Network Appliance-specific requirements of Open Firmware packages. 14 15 3.1. "disk-label" Support Package 16 17 The Digital Network Appliance is primarily intended to support diskless systems that store most of their data on 18 network servers. Consequently, many implementations of this architecture lack disk-like mass storage devices 19 (e.g. disks, diskettes, CD-ROMs). Therefore, this binding does not mandate the presence of a "disk-label" 20 support package, nor does it specify the exact behavior of a "disk-label" support package, should it exist. 21 For variants that do support disk devices, the behavior of the "disk-label" support package should be 22 specified in additional documentation pertaining to the platform in its application domain. 23 24 3.2. Program-image Formats. 25 26 3.2.1. Load Address 27 28 The default load address is 0xF0000000, the value of load-base. Client programs are assumed to be designed 29 to be loaded at 0xF0000000. 30 Prior to the first execution of load, the firmware shall allocate and map at least 6 MB of physical memory at 31 this address, unless the hardware configuration of the system makes this impossible. In that case, the firmware 32 shall map as much memory as practical. 33 34 3.2.2. Load Image Formats 35 36 The load User Interface command in conjunction with init-program shall prepare the loaded image for 37 later execution according to the following algorithm: 38 If the three bytes beginning at the default load address are the gzip 39 compression signature (i.e. Byte 0 = 0x1F, Byte 1 = 0x8B, Byte 2 = 0x08) as 40 described in [7], skip the header according to [7] and inflate the image 41 according to the algorithm described in [6], placing the inflated image at 42 the default load address, and proceed with the following steps. 43 44 If the 4 bytes beginning at the default load address are the a.out signature 45 as described in Section 3.2.3, prepare the image for execution as described 46 in Section 3.2.3 and skip the remaining steps. 47 Otherwise, if the 2 bytes beginning at the default load address are the Forth 48 source code signature characters "\ " (i.e. 0x5C, 0x20), arrange for the next 49 execution of go to interpret the load image as Forth source code, and skip 50 the remaining steps. 51 52 Otherwise, if the byte at the default load address is the start1 FCode token 53 (i.e. 0xF1), arrange for the next execution of go to evaluate the load image 54 as FCode (e.g. as with "load-base 1 byte-load"), and skip the remaining steps.

2 of 7 Preliminary January 26, 1998 Revision 0.2 DRAFT Digital Network Appliance Platform Binding

1 Note: At this point, the firmware may recognize and prepare other image formats not specified 2 here. 3 4 Otherwise (i.e. if the load image format has not been recognized explicitly), 5 prepare the image for execution as described in Section 3.2.4. 6 7 3.2.3. a.out Format 8 The offsets given below are from the default load address. 9 10 Offset Name Endianess Contents 11 12 0 a_midmag Big Signature: 0x008F010B 13 a_text 14 4 Little The length in bytes of the header plus the text segment in 15 both the file and the execution image. 16 8 a_data Little The length in bytes of the data segment in both the file 17 and the execution image 18 19 12 a_bss Little The length in bytes of the bss segment in the execution 20 image. The bss segment is not stored in the file, because 21 its initial contents are always zero. 22 23 16 a_sym Little The length in bytes of the symbols portion of the file. 24 (The symbol table in the execution image consists of two 25 portions, one for the symbols and a second for the 26 strings.1) 27 28 20 a_entry Little The virtual address at which program execution is to 29 begin. 30 24 a_trsize Little The size of the text relocation table. Used only for object 31 files. Contains 0 for executable files. 32 33 28 a_drsize Little The size of the data relocation table. Used only for object 34 files. Contains 0 for executable files. 35 36 The loaded image consists of the above header immediately followed in order by the text segment, the data 37 segment, the symbols portion of the symbol table and the strings portion of the symbol table. After recognizing 38 this header, load shall: 39 40 • Synchronize the instruction and data caches from load-base to load-base + a_text + a_data + 0x20, 41 • Move the symbol portion and string portion of the symbol table from load-base + a_text + a_data + 42 0x20 to load-base + a_text + a_data + a_bss + 0x20. 43 a_bss load-base a_text a_data 44 •Zero bytes of memory beginning at + + + 0x20, • Release and unmap the physical memory from load-base + a_text + a_data + a_bss + a_sym + 45 1 46 string_size + 0x20 (i.e. from the end of the prepared client program memory image) to the end of the load 47 area. (The goal of this step is to have the "available" properties in the /memory and /mmu nodes 48 accurately reflect the memory actually consumed by the client program prepared image.) 49 • the pc in the saved-program-state to a_entry. 50 51 52 1 53 string_size is the 32-bit, little-endian value at load-base + a_text + a_data + a_sym which 54 describes the length in bytes of the string portion of the symbol table.

January 26, 1998 Revision 0.2 DRAFT Preliminary 3 of 7 Digital Network Appliance Platform Binding

1 • Set the remaining elements of the saved-program-state to their initial values as defined in Section 6.2.1 of [2]. 2 Note: The above header is that used by NetBSD [4]. 3 4 3.2.4. Raw Binary Format 5 6 In order to prepare a raw binary image for execution, load shall: 7 • Synchronize the instruction and data caches from load-base to load-base + the size of the loaded image, 8 9 • Release and unmap the physical memory from load-base + the size of the loaded image (i.e. from the end of 10 the loaded image) to the end of the load area. (The goal of this step is to have the "available" properties in 11 the /memory and /mmu nodes accurately reflect the memory actually consumed by the client program prepared 12 image.) 13 • Set the pc in the saved-program-state to load-base. 14 • Set the remaining elements of the saved-program-state to their initial values as defined in Section 6.2.1 of [2]. 15 16 17 3.3. "obp-tftp" Support Package 18 The "obp-tftp" Support Package shall comply with the requirements set forth in Sections 5.1 and 5.2 of 19 [14] with the following extensions. 20 21 3.3.1. Use of BOOTP 22 23 BOOTP (in its DHCP variation as described below) shall be the default discovery protocol (i.e. if the first 24 argument to the "obp-tftp" open method is not an IP address BOOTP shall be used). 25 26 3.3.2. DHCP Support 27 In the "obp-tftp" load method, if the BOOTP protocol is to be used to discover the server’s IP address, 28 the DHCP variant of the BOOTP protocol shall be used, beginning at the DHCP INIT state as specified in [8]. 29 In addition to the DHCP options required by [8], the DHCPDISCOVER and DHCPREQUEST packets shall 30 contain a “client identifier” option whose value is derived from the "system-id" property of the device 31 root node, and if the device tree root node contains an "architecture" property (whose value is a text 32 string encoded as with encode-string), the DHCPDISCOVER and DHCPREQUEST packets shall contain a 33 “vendor class identifier” option whose value is the string decoded from the prop-encoded-array of that 34 "architecture" property’s value. 35 Note: For this binding, the "system-id" property must be derived from system-mac-address, 36 so the “client identifier” option’s value is derived from the hardware address. 37 38 If the server responds to the DHCP DISCOVER with a BOOTREPLY that is not a DHCPOFFER (i.e. the options 39 field is empty and does not contain DHCP options), Open Firmware shall proceed using the BOOTP protocol. 40 Otherwise (i.e. if the server responds with a DHCPOFFER BOOTREPLY), Open Firmware shall proceed using 41 the DHCP protocol, until the DCHP client (i.e. the firmware) enters the DHCP BOUND state, at which point 42 the firmware has acquired an IP address for its subsequent use. 43 Upon successful completion of the discovery protocol, via either the full DHCP process or the truncated 44 “BOOTP server responds with non-DHCPOFFER” version, the verbatim contents of the final BOOTP or 45 DHCPACK packet from the server shall be reported by encoding those contents as with encode-bytes and 46 using the resulting prop-encoded-array to create both a "bootreply-packet" property and a 47 "bootp-response" property in the /chosen node. Client programs should use the 48 "bootreply-packet" property; the "bootp-response" property is a concession to existing client 49 programs. 50 51 The firmware may, but need not, implement an additional mechanism for remembering a previously-assigned IP 52 address and attempting to re-use that address by skipping the DHCPDISCOVER phase and proceeding directly 53 to the DHCPREQUEST phase, as permitted in [8]. The details of such a mechanism are not specified by this 54 binding.

4 of 7 Preliminary January 26, 1998 Revision 0.2 DRAFT Digital Network Appliance Platform Binding

1 4. Properties 2 3 This section describes the standard properties of Digital Network Appliance Platform Open Firmware 4 implementation. 5 6 4.1. Root Node Properties 7 / 8 The following properties of the root node (“ ”) shall be created by an Open Firmware implementation. 9 Note: The root node typically corresponds to the VL bus in a Digital Network Appliance system 10 "#address-cells" 11 Standard property, encoded as with encode-int, that specifies the number of cells required to represent 12 physical addresses on the processor bus. The value of "#address-cells" for the processor bus shall be 13 1. 14 15 "clock-frequency" 16 Standard property, encoded as with encode-int, that represents the primary system bus speed (in hertz). 17 "dma-ranges" 18 19 Standard property, whose value is an array of entries of the form: child-address child-size. 20 Each entry describes a contiguous DMA address range, giving the base addresses of the range in the child 21 address space and the length of the range, which is expressed in the child's size format. (The “child” 22 address space is the address space defined by the root node.) 23 Each child-address is a physical address, encoded as with encode-phys, within the child address space. 24 The number of cells therein can be determined from the "#address-cells" property of the root node. 25 26 Each child-size is a sequence of integers, each encoded as with encode-int. The number of integers is determined from the "#size-cells" property of the root node, or by the default value of 1 if the root 27 node contains no "#size-cells" property. 28 29 Note: The general form of a "dma-ranges" entry is child-address parent-address child-size. Within 30 this node, the parent-address portion is zero cells long. 31 "system-id" 32 Standard property, encoded as with encode-string, that contains the identification of the computer 33 system. This string shall be unique across all systems and all manufacturers. The system-id shall be of the 34 form "0nnnnnnmmmmmm" where nnnnnn is a sequence of 6 uppercase hexadecimal digits representing a 24-bit Organizationally Unique Identifier (OUI) assigned by the IEEE Registration Authority Committee, 35 and mmmmmm is a sequence of 6 uppercase hexadecimal digits representing a 24-bit binary number 36 assigned by the manufacturer to assure uniqueness. 37 38 The 6-byte MAC address returned by system-mac-address meets the above requirements. For this 39 binding, that MAC address, encoded in the form specified above, shall be used as the system-id. 40 41 4.2. "/chosen" Node Properties 42 The following properties of the "/chosen" node shall be created by an Open Firmware implementation. 43 44 "clock" 45 Standard property, encoded as with encode-int, that represents the ihandle of an instance of the real-time 46 clock node. The purpose of this property is to enable a client program to use the set-time method of the 47 "/isa/rtc" node easily. 48 "nvram" 49 50 Standard property, encoded as with encode-int, that represents the ihandle of an instance of the 51 NVRAM node. 52 Note: The nvram node identified in the /chosen node shall support a size method as specified in 53 Section 7.2 of [11]. The size method will return a value that is the total DNA platform NVRAM 54 size.

January 26, 1998 Revision 0.2 DRAFT Preliminary 5 of 7 Digital Network Appliance Platform Binding

1 4.3. "/isa" Node Properties 2 "/isa" 3 The following properties of the node shall be created by an Open Firmware implementation. 4 "dma-ranges" 5 Standard property, whose value is an array of entries of the form: child-address parent-address child-size 6 7 Each entry describes a contiguous DMA address range, giving the base addresses of the range in both the 8 child and parent address spaces and the length of the range, which is expressed in the child's size format. (The “child” address space is the address space defined by the /isa node. The “parent” address space is 9 the address space defined by the root node, the /isa node’s parent.) 10 11 Each child-address is a physical address, encoded as with encode-phys, within the child address space. The number of cells used is 2 reflecting the default value of the "#address-cells" property since the 12 /isa "#address-cells" 13 node contains no property. 14 Each parent-address is a physical address, encoded as with encode-phys, within the parent address 15 space. The number of cells therein is determined from the "#address-cells" property of the root node, 16 the /isa node’s parent. 17 Each child-size is a single integer encoded as with encode-int. This reflects the default value of the 18 "#size-cells" property since the /isa node contains no "#size-cells" property. 19 20 4.4. "/isa/rtc" Node Properties 21 22 The following properties of the "/isa/rtc" node shall be created by an Open Firmware implementation. 23 "status" 24 25 Standard property, encoded as with encode-string, that specifies the state of the latched and unlatched battery bits of the real-time clock. If either of those bits indicates a battery problem, the "status" property 26 value shall be set to the string “bad battery”. In all other cases, the property value shall be set to the string 27 "okay". 28 Note: The “latched battery bits” are those bits found at 0xE of the RTC chip. The “unlatched 29 battery bits” are those found at 0xD of the RTC chip. 30 31 Note: Other values may be defined for this property in the future. 32 33 4.5. "/openprom" Node Properties 34 35 The following properties of the "/isa/rtc" node shall be created by an Open Firmware implementation. 36 "built-on" 37 Standard property, encoded as with encode-int, that specifies the year, month and day on which the 38 ROM image was built. The unencoded integer consists of 8 decimal digits ordered from left to right as four 39 digits for the year, two digits for the month, and two digits for the day (e.g. 19970610 for firmware built on 40 June 10, 1997). 41 42 5. Extensions for Digital Network Appliance Platform Systems 43 44 This section describes the properties, methods, and device subtrees that are applicable to devices required by the 45 Digital Network Appliance Platform architecture. It is strongly recommended that other platforms follow these 46 definitions for the corresponding devices. 47 48 5.1. Display Devices 49 50 Display device packages (i.e. device_type = "display") for Digital Network Appliance Platform systems 51 should include in their implementation all the properties and methods called for in [12] and [13]. 52 Display device package shall also include the following method: 53 54

6 of 7 Preliminary January 26, 1998 Revision 0.2 DRAFT Digital Network Appliance Platform Binding

1 text-mode3 ( -- ) 2 Changes the display device’s operating mode to “EGA/VGA text mode 3”. 3 4 5.2. Device Support 5 6 Open Firmware implementations for Digital Network Appliance Platform systems must implement those device 7 types from [11] that are appropriate to the hardware present. 8 9 5.3. Conventions for Devices on ISA 10 11 This section defines the naming and device type conventions for typical devices on ISA buses. The following 12 lists are the values of the "name" and "device_type" properties of the devices on an ISA bus: 13 name device_type 14 8042 15 kbd "keyboard" 16 mouse "mouse" 17 floppy "block" 18 com "serial" 19 timer "timer" 20 lpt "parallel" 21 ide "block" nvram "nvram" 22 rtc "rtc" 23 24 Note: The "kbd" and "mouse" names are indented to show that they are the child nodes of the 25 8042 node. 26 Some systems use an I/O controller, often called a super I/O chip, which provides control functions of multiple 27 I/O devices. When a system uses a super I/O chip, a device node representing the super I/O chip itself need not 28 exist. Instead, the device nodes of the devices attached to the super I/O chip may be direct children of the bus 29 node representing the bus to which the super I/O chip is attached. 30 31 It is strongly recommended that the "compatible" property be implemented for ISA bus devices to help 32 operating systems find appropriate device drivers for these devices. 33 34 5.4. "/aliases" Node Properties 35 36 An implementation of Open Firmware for the Digital Network Appliance Platform shall provide the following 37 aliases under the "/aliases" node if an underlying hardware device is present: 38 audio 39 cdrom 40 com1 The serial port at I/O address 0x3F8 41 com2 The serial port at I/O address 0x2F8 42 disk floppy 43 keyboard 44 net 45 rom 46 screen 47 scsi 48 tape 49 50 51 52 53 54

January 26, 1998 Revision 0.2 DRAFT Preliminary 7 of 7