Subject: Brussels persistence [PSARC/2008/222 FastTrack timeout 04/02/2008]
To:      PSARC-ext@Sun.Com
Cc:      brussels-dev@opensolaris.org
Bcc:     one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay


Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 Brussels persistence
    1.2. Name of Document Author/Supplier:
	 Author:  Artem Kachitchkine
    1.3  Date of This Document:
	26 March, 2008
4. Technical Description
4.1. Summary

PSARC/2007/429 introduced network driver properties that persist across
system reboot, but not across link plumb/unplumb. This case seeks to
fix that deficiency.

Property persistence across reboots is currently achieved by having
svc:/network/physical invoke "dladm init-linkprop" on startup, which
causes all available links to plumb and properties pushed into
respective drivers. Persistence across plumb/unplumb can be
achieved manually:

	ifconfig <link> plumb
	dladm init-linkprop <link>

We propose that this happens automatically each time a link is plumbed.


4.2. Details

The kernel MAC layer pushes properties into drivers via mc_setprop
callback. From the driver standpoint, link plumbing and unplumbing
correspond, effectively, to mc_start and mc_stop callbacks. We propose
that for each persistent property mc_setprop is invoked prior to
mc_start, but after attach(9E) and mac_register() are completed.
That way the driver can save property values in the soft state and
configure the hardware in mc_start accordingly.

Implementation utilizes the dlmgmtd daemon (PSARC/2006/499). A door
upcall is invoked from the MAC layer, causing dlmgmtd to initiate the
equivalent of "dladm init-linkprop <link>" using libdladm. The door call
returns upon operation completion.

    Note: The project team considered direct parsing of the persistent
    store (currently /etc/dladm/dataconf.conf) from the kernel,
    similar to the driver.conf mechanism. But this seems future unproof,
    as the repository might eventually move to SMF, and there is no SMF
    access in the kernel.

Although the above should be sufficient, in practice, the way today's
drivers are coded, some of them might require properties before attach(9E)
completes. To make Brussels transition easier for driver maintainers, we
propose to add "pull" style property retrieval, in addition to the "push"
style mc_setprop callback:


int mac_prop_init(dev_info_t *dip, int instance, mac_prop_handle_t *mph)

Returns a handle to be used later with mac_prop_get(). The 'instance'
argument has the same meaning as m_instance passed to mac_register():
most GLDv3 should use 0.

void mac_prop_fini(mac_prop_handle_t mph)
    
Releases the handle.


int mac_prop_get(mac_prop_handle_t mph, const char *name, void *value,
    uint_t size, uint_t *rsizep)

If the requested property exists in the persistent store, up to 'size'
bytes are copied into 'value'. If buffer is too small, real size is
returned in 'rsizep' and the function returns EAGAIN. If property
does not exist in the persistent store, ENOENT is returned.

These functions do not require links to be in any particular state, so
can be called from attach(9E) or any other kernel context. They could
also be potentially useful for virtual links in the future.


4.3 Even more details

The following interfaces are less interesting in terms of architecture
but are worth a mention here.

Door upcall interface:

command:      DLMGMT_CMD_LINKPROP_INIT
argument:     dlmgmt_door_linkprop_init_t
flag:         DLMGMT_LINKPROP_MAC_ONLY
return value: dlmgmt_linkprop_init_retval_t


Additional flags for dld_ioc_prop_t:

DLD_PROP_FLAG_MAC_ONLY

This flags indicates to the MAC layer that the property passed from
userland via DLDIOCSETPROP is intended for MAC only and should not be
pushed into drivers via mc_setprop. Used in mac_prop_init()
implementation.

DLD_PROP_FLAG_MAC_NAME

This flag indicates that dld should use the provided MAC name
instead of link ID. Before a device is fully attached, using
vanity name services for mapping can be problematic.

Additional entry in dld_ioc_prop_t:

char    pr_macname[LIFNAMSIZ];

Used instead of the pr_linkid when DLD_PROP_FLAG_MAC_NAME is set.


4.4. Interfaces

Interface                     | Stability 
------------------------------+-----------------------
mac_prop_handle_t             | Consolidation Private
mac_prop_init                 | Consolidation Private
mac_prop_fini                 | Consolidation Private
mac_prop_get                  | Consolidation Private
DLMGMT_CMD_LINKPROP_INIT      | Consolidation Private
dlmgmt_door_linkprop_init_t   | Consolidation Private
dlmgmt_linkprop_init_retval_t | Consolidation Private
DLMGMT_LINKPROP_MAC_ONLY      | Consolidation Private
DLD_PROP_FLAG_MAC_ONLY        | Consolidation Private
DLD_PROP_FLAG_MAC_NAME        | Consolidation Private
------------------------------+-----------------------

Release binding: minor


4.5. References

PSARC/2007/429 Brussels - enhanced network driver configuration via dladm
PSARC/2006/499 Clearview Nemo unification and vanity naming

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