I am submitting this fast-track on behalf of myself, with
timeout set to 08/28/2007. Patch/update binding requesed.
Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1 Project/Component Working Name:
Deletion of a KSTAT_FLAG_PERSISTENT kstat
1.2 Name of Document Author/Supplier:
Author: Chris Horne
1.3 Date of This Document:
Tue Jul 3 22:09:03 MDT 2007
4. Technical Description
4.1 Problem
For a KSTAT_FLAG_PERSISTENT kstat is created by
kstat_create(9F), a kstat_delete(9F) call does not completely
destroy the kstat. This behavior means that kstat consumers
can't fully controll which kstats a utility like iostat(1M)
will still find and display.
4.2 Proposal
This fasttrack defines a new kstat_destroy_persistent(9F)
interface that can be used to completely destroy a kstat
created with the KSTAT_FLAG_PERSISTENT.
Some use cases for this interface are
o When the association of a disk partition to a region of
storage undergoes a fundamental change, a driver needs a way
to completely delete kstats associated with the old
partition. Some examples of such a situation are a change in
the base block associated of a partition, or conversion of a
disk from SUN label to/from an EFI label.
<http://monaco.sfbay.sun.com/detail.jsp?cr=6476952>
<http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=6476952>
o We have requests to support 'reset' of kstat data. In
general the kstat implementation does not knows enough to
perform the reset operation itself: not all initial values
are guaranteed to be zero - esp for strings. A simple
approach to reset would be for a target driver to completely
delete its kstats, and then use common code recreate them.
Current kstat_delete() behavior for KSTAT_FLAG_PERSISTENT
kstats prevents this.
<http://monaco.sfbay.sun.com/detail.jsp?cr=4761239>
<http://bugs.opensolaris.org/bugdatabase/view_bug.do?bug_id=4761239>
4.4 Interface Table
------------------------------------------------------------------------
Interface Level Comments
------------------------------------------------------------------------
kstat_delete_persistent() Committed delete a
KSTAT_FLAG_PERSISTENT
kstat
4.5 References
[0] The kstat stability "best practice"
http://sac.sfbay.sun.com/cgi-bin/bp.cgi?NAME=kstat.bp
[1] PSARC 1992/085 /dev/statistics
http://sac.sfbay/PSARC/1992/085
http://www.opensolaris.org/os/community/arc/caselog/1992/085
[2] PSARC 1996/273 64-bit neutral kstat
http://sac.sfbay/PSARC/1996/273
http://www.opensolaris.org/os/community/arc/caselog/1996/273
[3] PSARC 1997/285 64-bit kstat revisited
http://sac.sfbay/PSARC/1997/285
http://www.opensolaris.org/os/community/arc/caselog/1997/285
[4] PSARC 1999/495 kstat(1M)
http://sac.sfbay/PSARC/1999/495
http://www.opensolaris.org/os/community/arc/caselog/1999/495
[5] PSARC 2000/053 ECC and Memory Configuration kstats
http://sac.sfbay/PSARC/2000/053
[6] PSARC 2000/468 Optionally disable per-partition kstats
http://sac.sfbay/PSARC/2000/468/
http://www.opensolaris.org/os/community/arc/caselog/2000/468
[7] PSARC/2001/239 KSTAT_DATA_STRING
http://sac.sfbay/PSARC/2001/239/
http://www.opensolaris.org/os/community/arc/caselog/2001/239
4.6 Man page changes
See below.
6. Resources and Schedule
6.4 Steering Committee requested information
6.4.1 Consolidation C-team Name:
ON
6.5 ARC review type:
FastTrack
A.1 Proposed kstat_delete(9F) man page changes:
Kernel Functions for Drivers kstat_delete(9F)
NAME
| kstat_delete, kstat_delete_persistent -
remove a kstat from the system
SYNOPSIS
#include <sys/types.h>
#include <sys/kstat.h>
void kstat_delete(kstat_t *ksp);
| void kstat_delete_persistent(kstat_t *ksp);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
PARAMETERS
ksp Pointer to a currently installed kstat(9S) struc-
ture.
DESCRIPTION
| A kstat is either persistent or non-persistent depending on
| whether kstat_create(9F) used the KSTAT_FLAG_PERSISTENT.
|
| For non-persistent kstats, kstat_delete() removes ksp from the
| kstat chain and frees all associated system resources.
|
| For persistent kstats, kstat_delete(9F) simply marks the kstat
| as dormant; a subsequent kstat_create() reactivates the
| kstat. To fully delete a persistent kstat, use
| kstat_delete_persistent.
RETURN VALUES
None.
CONTEXT
| kstat_delete() and kstat_delete_persistent() can be called from any
| context.
SEE ALSO kstat_create(9F), kstat_install(9F), kstat_named_init(9F),
kstat(9S)
Writing Device Drivers
| NOTES When calling kstat_delete() or kstat_delete_persistent(),
the driver must not be holding
that kstat's ks_lock. Otherwise, it may deadlock with a
kstat reader.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
