#pragma ident	"@(#)large-disk.txt	1.4	08/02/01 SMI"

OBP Deblocker Package Changes for Large Disks

1. Introduction.

This document describes the interface additions required
in "block" device type packages that use the standard "deblocker"
package in order to support large disks.

1.1. References

[1] IEEE 1275-1994: Standard for Boot (Initialization,
    Configuration) Firmware: Core Requirements and
    Practices.

[2] Open Firmware Working Group Recommended Practice:
    Standard Methods: size and #blocks.
    http://playground.sun.com/1275/practice/#size-blocks

2. Existing Interfaces.

The "deblocker" package is defined in the Open Firmware
core specification [1] and specifies that any package
that uses the "deblocker" package must define the following
methods that have 32-bit limitations. Note that other
methods that don't have 32-bit block number limitations
are not included in this document.

	read-blocks ( addr block# #blocks -- #read )
	write-blocks ( addr block# #blocks -- #written )

The OFWG recommended practice "Standard Methods: size and #blocks"
[2], defines the following method for packages that implement
device type "block" or "byte".

	#blocks ( -- #blocks )

In the first two cases, the block# argument is a 32-bit
signed integer, which limits read-blocks and write-blocks
to the first 1TB of the device if the package treats the
block number as a signed 32-bit integer, or to the first
2TB of the device if the package treats the block# field
as an unsigned 32-bit integer.

In the last case, the #blocks method returns the number
of blocks on the device as an unsigned 32-bit integer.

3. Proposal.

This proposal modifies the definition of the "deblocker"
package to add support for 64-bit block numbers,
and creates a new method to return the number of blocks
as a 64-bit number to support large disks.

3.1. "deblocker" Package Additions

Any package that uses the "deblocker" support package
and supports large disks must implement the following
methods in addition to the methods required in section
3.8.3 of [1].

3.1.1. Methods

  read-blocks64		( addr d.block# #blocks -- #read )	M

	Read #blocks, starting at d.block#, from device
	into memory.

	Read #blocks records of length block-size bytes
	from the device (starting at block d.block#) into
	memory (starting at addr.) Return #read, the number
	of blocks actually read.

	If the device is not capable of random access (e.g.,
	a sequential access tape device) d.block# is ignored.

  write-blocks64	 (addr d.block# #blocks -- #written )	M

	Write #blocks from memory into device, starting at d.block#.

	Write #blocks records of length block-size bytes from memory
	(starting at addr) to the device (starting at block number
	d.block#.) Return #written, the number of blocks actually written.

	If the device is not capable of random access (e.g., a sequential
	access tape device), d.block# is ignored.

Implementation note:

  read-blocks64 and write-blocks64 differ from
  read-blocks and write-blocks only in the d.block# argument.
  d.block# is a double number.  A double number in FCode consists
  of 2 stack items, as in ( low high ).

  For packages that implement variable sized command sets, as with
  scsi n-byte commands, the device driver must not assume that it can use
  larger versions of the underlying command set if the block numbers
  fit in smaller versions of the command/response packets.

  The "deblocker" package is permitted to use either these new methods with
  the "hi" value of d.block# set to zero or the legacy read-blocks or
  write-blocks methods when reading from or writing to block numbers < 2^32.

3.2.2. Properties

Any package (e.g., device driver) compliant with the extensions defined
in this document shall implement the following property.

The "deblocker" package compliant with this specification shall
implement the following property in the "deblocker" package.

  "lba64"							S

	Standard property name to indicate that the package
	supports 64-bit block numbers.

	prop-encoded-array:
	 Property contains no data. prop-encoded-array is NULL.

	Created as with:

		0 0 " lba64" property

  Implementation Notes:

  The client program can check if the system supports booting
  booting from large disks if the "lba64" property exists in
  both the "disk" node under the target HBA node and also in
  the "/packages/deblocker" node. The property must exist in
  both nodes or the system and/or target HBA does not support
  booting from large disks.

4. "block" Device Type Extension

Packages of device type "block" shall implement the following
method:

  #blocks64		 ( -- d.blocks )			M

	Return the size of the device in blocks.

	Return, as a double number "d.blocks", the number of blocks of storage
	associated with the device or instance, where a "block" is a unit
	of storage consisting of the number of bytes returned by the package's
	"block-size" method.  If the size cannot be determined, or if the
	number of blocks exceeds the range of a double number, return the
	double number -1.


5. Implementation Notes

In order to support large disks, HBA device drivers must implement
the following additional methods in the "disk" device node:

	read-blocks64
	write-blocks64
	#blocks64

The following property must be implemented in the "disk" node
if the HBA driver is compliant with this specification:

	"lba64" ( boolean property .. no value )

The "lba64" property will also be present in the
/packages/deblocker package if the deblocker implementation
supports large disks. Client programs may use the existence
of these properties to determine if a specific target device
and the core firmware both include large disk support.

All existing methods required of "block" device type drivers
and all methods currently required by drivers using the "deblocker"
package must also be implemented in the "disk" device node.

The "deblocker" package may use either form of the methods
that read or write blocks when the block number is < 2^32.