This case seeks micro/patch binding.

1. Introduction
   1.1. Project/Component Working Name:

	Solaris Instance UUID

   1.2. Name of Document Author/Supplier:

	Gavin Maltby

   1.3. Date of This Document:

	05/19/2010

   1.5. Email Aliases:
    	1.5.1. Responsible Manager: gavin.gibson@oracle.com
    	1.5.2. Responsible Engineer: gavin.maltby@oracle.com

4. Technical Description:
    4.1. Details:

    4.1.1 Summary

	We associate a unique identifier with each running
	Solaris instance.  An "instance" in this sense is a boot
	of Solaris, so the intention is to identify each distinct boot
	of a Solaris installation from the next (*).  The instance identifier
	will serve to identify a running Solaris instance and correlate
	it with any crash dump images thereof (both "live savecore" images
	and panics).

	The identifier takes the form of a 36-character UUID string
	which is generated during boot (at the time that we appoint
	any dump device, but still generated even if there is no
	dump device) and embedded in the running kernel image.
	This is a once-only operation - further attempts to set the
	image UUID will fail with EALREADY.

	Most interfaces are Private - see 4.5.  We arc them, nevertheless,
	to document them for various crashdump analysis tools.  The
	only public interface is the syslog messages line in 4.1.4 below.

	This feature does not overlap with that of FWARC/2009/680 - the
	UUID there identifies distinct ldoms, not Solaris images.

	(*) In some virtualization products it is possible that a booted
	    instance is snapshotted and that snapshot restored to a
	    running state repeatedly.  In this case the instance UUID
	    will not change at each snapshot resume - it will be that
	    of the original boot before snapshot.  In this case a single
	    image UUID can be associated with multiple panics.

   4.1.2 Setting Image UUID

	An undocumented (private) option -i to dumpadm is used to
	set the current instance UUID during boot.  This is executed
	during the start method script for service instance
	system/filesystem/usr:default which is the earliest point in
	boot that a dump device can be appointed (for zfs root filesystems).

	If something should cause this method script to run again then
	the repeated attempted to set a UUID will fail harmlessly.  Similarly
	a command line use of dumpadm -i will fail if filesystem/usr has
	already come online.

   4.1.3 Retrieving Image UUID

	The current image UUID may be retrieved from userland
	through a (private) ioctl DIOCGETUUID on /dev/dump; you need suitable
	permissions to open /dev/dump even for reading.  In a crashdump
	image it is retrievable both from the dump header and from the
	kernel variable dump_osimage_uuid.

	Within the kernel, the UUID of the image may be retrieved with
	dump_get_uuid().

	We do not deliver a command line utility to query the current
	image UUID.

   4.1.4 Image UUID in syslog

	When it is first generated, the instance UUID is noted in the
	messages file (but not to the console):

May 31 22:57:55 parity genunix: [ID 227219 kern.info] This Solaris instance has UUID 18081944-4691-639f-e2cf-8f2054a0ded4

   4.1.5 Image UUID in mdb

	The image UUID is displayed by ::status in mdb in both live and
	post-mortem kernel debug sessions.

	# mdb -k
	> ::status
	debugging live kernel (64-bit) on parity
	operating system: 5.11 swfma-bld (i86pc)
	image uuid: 18081944-4691-639f-e2cf-8f2054a0ded4

	If we panic that instance and run mdb on the resulting crashdump:

	# mdb -k 0
	> ::status
	debugging crash dump vmcore.0 (64-bit) from parity
	operating system: 5.11 snv_138 (i86pc)
	image uuid: 18081944-4691-639f-e2cf-8f2054a0ded4
	panic message: forced crash dump initiated at user request
	dump content: kernel pages only

   4.1.6 DUMP_VERSION and PANICBUFVERS Changes

	The DUMP_VERSION used in a struct dumphdr (written at the head
	and tail of a crashdump) is bumped from 9 to 10;  version 10
	includes a character array dump_uuid.

	The PANICBUFVERS, which describes the format of panic data
	captured in panicbuf and written out to a crash dump, is bumped
	from 1 to 2.

    4.5. Interfaces:

	Interface		Stability
	-----------------------	------------
	dump_get_uuid		Consolidation Private
	dump_set_uuid		Project Private
	dumpadm -i		Project Private
	DIOCSETUUID		Project Private
	DIOCGETUUID		Project Private
	dump_osimage_uuid	Project Private
	panicdata pd_uuid	Consolidation Private
	UUID syslog message	Committed

    4.6. Doc Impact:

   6.5. ARC review type:

		FastTrack

   6.6. ARC Exposure:

		open