I'm sponsoring this fasttrack for Cathy Zhou and the Clearview I-Team.
The timer is set for Friday, March 16th. These proposed changes are
mostly cosmetic and only impact Consolidation Private interfaces.
Patch binding is requested.
--8<--
1 Introduction
==============
This case proposes to restructure the libdladm library and its friends
(liblaadm, libwladm and libmacadm). Specifically, it proposes to merge
them into one single library -- libdladm -- but keep the component
boundaries unchanged.
The mentioned libraries provide a set of data-link administration
APIs for link management applications, primarily dladm(1M). Today,
these libraries are split based on functionality:
- libdladm: General data-link administration APIs.
- liblaadm: Aggregation link administration APIs.
- libwladm: WLAN administration APIs.
- libmacadm: MAC management APIs. Currently it only
contains macadm_walk() which walks all MACs
on the system.
As the data-link administration APIs have evolved, these libraries
have become increasingly tied to each other and the dependencies
between them have become unnecessarily complicated. Therefore, we
propose to merge them into libdladm, but keep the component
boundaries unchanged.
Note that all of the APIs involved are Consolidation Private today,
and will remain Consolidation Private.
2 Proposed changes
==================
We propose to:
1) Remove libmacadm, liblaadm and libwladm and move their
functionality into libdladm.
2) Keep the component boundaries. The new libdladm will be split
into four components:
(1) Common routines (libdladm.h)
Common routines shared by all other data-link administration
components, which do not directly configure links. For
example, dladm_status2str(). This will also include the
current libmacadm API macadm_walk().
(2) General link administration APIs (libdllink.h)
Link administration APIs which applies not limited to one
specific type of link. For example, the link property
management API.
(3) Aggregation link administration APIs (libdlaggr.h)
(4) WLAN link administration APIs (libdlwlan.h)
Besides the above four components, we foresee more components as
libdladm evolves. For example, the VLAN administration component
and the IPtun administration component.
3) Change all APIs to be prefixed with "dladm_". For components that
manage a specific type of link, APIs will be prefixed with
"dladm_<comp>_". For example, dladm_aggr_create() and
dladm_wlan_scan().
4) Unify the error code namespace.
Today, each library has its own error code namespace. This
complicates error processing of data-link management applications.
As part of this proposal, the error code namespace will be
unified into one error code namespace: dladm_status_t. Types
wladm_status_t, laadm_diag_t and functions laadm_diag(),
wladm_status2str() will be removed.
5) Unify other general structure types and macros. For example,
wladm_prop_type_t will be merged into the existing
dladm_prop_type_t type.
6) Make minor API name and function signature changes to ensure
all libdladm APIs are consistent and simple. Specifically:
- dladm_<comp>_<xxx>2str()
In order to be consistent, all functions used to convert
specific values to strings will all be named as
dladm_<comp>_<xxx>2str(), and will takes "char *" as the
second argument. Further, today dladm.c has its private
implemention of several xxx2str() like functions, these
functions will be implemented as libdladm APIs.
+---------------------------+----------------------------+
| Old API | New API |
+---------------------------+----------------------------|
| laadm_str_to_policy() | dladm_aggr_policy2str() |
| laadm_mac_addr_to_str() | dladm_aggr_macaddr2str() |
| laadm_lacp_timer_to_str() | ladm_aggr_lacptimer2str() |
+---------------------------+----------------------------|
| dladm.c private functions | dladm_aggr_portstate2str() |
| | dladm_linkstate2str() |
| | dladm_linkduplex2str() |
+---------------------------+----------------------------+
- changes for simplification
Some structure and function names are simplified:
+---------------------------+----------------------------+
| Old API | New API |
+---------------------------+----------------------------|
| wladm_link_attr_t | dladm_wlan_linkattr_t |
| wladm_wep_key_t | dladm_wlan_wepkey_t |
| laadm_walk_sys() | dladm_aggr_walk() |
+---------------------------+----------------------------+
- changes for consistency
WLADM_LINK_STATUS_* will be changed to DLADM_WLAN_LINKSTATUS_*
to be consistent with its type name (dladm_wlan_linkstatus_t):
typedef enum {
DLADM_WLAN_LINKSTATUS_DISCONNECTED = 1,
DLADM_WLAN_LINKSTATUS_CONNECTED
} dladm_wlan_linkstatus_t;
Further, macro WLADM_STRSIZE and LAADM_POLICY_STR_LEN will be
subsumed by the existing DLADM_STRSIZE macro.
Also, the WLADM_OPT_* macros will be changed to
DLADM_WLAN_CONNECT_* to be consistent with the
DLADM_AGGR_MODIFY_* macros:
+----------------------+-------------------------------+
| Old API | New API |
+----------------------+-------------------------------|
| WLADM_OPT_CREATEIBSS | DLADM_WLAN_CONNECT_CREATEIBSS |
| WLADM_OPT_NOSCAN | DLADM_WLAN_CONNECT_NOSCAN |
+----------------------+-------------------------------+
3 Interface Table
=================
Note that all listed interfaces are Consolidation Private.
+----------------------------------------------------------------------+
| Interfaces Exported |
|--------------+------------------------------------+------------------|
| Header file | Interface | Comments |
|--------------+------------------------------------+------------------|
| <libdladm.h> | dladm_status2str() | |
| | dladm_set_rootdir() | |
| |------------------------------------+------------------|
| | DLADM_STRSIZE | |
| |------------------------------------+------------------|
| | DLADM_OPT_TEMP | |
| | DLADM_OPT_CREATE | |
| | DLADM_OPT_PERSIST | |
| |------------------------------------+------------------|
| | typedef enum { | |
| | DLADM_STATUS_OK = 0, | |
| | DLADM_STATUS_BADARG, | |
| | DLADM_STATUS_FAILED, | |
| | DLADM_STATUS_TOOSMALL, | |
| | DLADM_STATUS_NOTSUP, | |
| | DLADM_STATUS_NOTFOUND, | |
| | DLADM_STATUS_BADVAL, | |
| | DLADM_STATUS_NOMEM, | |
| | DLADM_STATUS_EXIST, | |
| | DLADM_STATUS_LINKINVAL, | |
| | DLADM_STATUS_PROPRDONLY, | |
| | DLADM_STATUS_BADVALCNT, | |
| | DLADM_STATUS_DBNOTFOUND, | |
| | DLADM_STATUS_DENIED, | |
| | DLADM_STATUS_IOERR, | |
| | DLADM_STATUS_TEMPONLY, | |
| | DLADM_STATUS_TIMEDOUT, | |
| | DLADM_STATUS_ISCONN, | |
| | DLADM_STATUS_NOTCONN, | |
| | DLADM_STATUS_REPOSITORYINVAL, | |
| | DLADM_STATUS_MACADDRINVAL, | |
| | DLADM_STATUS_KEYINVAL | |
| | } dladm_status_t; | |
| +------------------------------------+------------------+
| | typedef enum { | |
| | DLADM_PROP_VAL_CURRENT = 1, | |
| | DLADM_PROP_VAL_DEFAULT, | |
| | DLADM_PROP_VAL_MODIFIABLE, | |
| | DLADM_PROP_VAL_PERSISTENT | |
| | } dladm_prop_type_t; | |
|--------------+------------------------------------+------------------|
| <libdllink.h>| dladm_walk() | |
| | dladm_mac_walk() | was macadm_walk()|
| | dladm_info() | |
| | dladm_hold_link() | |
| | dladm_rele_link() | |
| | dladm_linkstate2str() | |
| | dladm_linkduplex2str() | |
| | dladm_init_linkprop() | |
| | dladm_get_prop() | |
| | dladm_set_prop() | |
| | dladm_walk_prop() | |
| | dladm_init_secobj() | |
| | dladm_get_secobj() | |
| | dladm_set_secobj() | |
| | dladm_unset_secobj() | |
| | dladm_walk_secobj() | |
| | dladm_secobjclass2str() | |
| | dladm_str2secobjclass() | |
| |------------------------------------+------------------|
| | DLADM_SECOBJ_VAL_MAX | |
| | DLADM_PROP_VAL_MAX | |
| | DLADM_SECOBJ_CLASS_WEP | |
| |------------------------------------+------------------|
| | dladm_secobj_class_t | |
|--------------+------------------------------------+------------------|
| <libdlaggr.h>| dladm_aggr_walk() | was laadm_*() |
| | dladm_aggr_up() | |
| | dladm_aggr_down() | |
| | dladm_aggr_add() | |
| | dladm_aggr_create() | |
| | dladm_aggr_delete() | |
| | dladm_aggr_modify() | |
| | dladm_aggr_remove() | |
| | dladm_aggr_lacpmode2str() | |
| | dladm_aggr_lacptimer2str() | |
| | dladm_aggr_macaddr2str() | |
| | dladm_aggr_policy2str() | |
| | dladm_aggr_portstate2str() | |
| | dladm_aggr_str2lacpmode() | |
| | dladm_aggr_str2lacptimer() | |
| | dladm_aggr_str2macaddr() | |
| | dladm_aggr_str2policy() | |
| |------------------------------------+------------------|
| | DLADM_AGGR_MODIFY_POLICY | was LAADM_* |
| | DLADM_AGGR_MODIFY_MAC | |
| | DLADM_AGGR_MODIFY_LACP_MODE | |
| | DLADM_AGGR_MODIFY_LACP_TIMER | |
|--------------+------------------------------------+------------------|
| <libdlwlan.h>| dladm_wlan_walk() | was wladm_*() |
| | dladm_wlan_scan() | |
| | dladm_wlan_connect() | |
| | dladm_wlan_disconnect() | |
| | dladm_wlan_is_valid() | |
| | dladm_wlan_get_linkattr() | |
| | dladm_wlan_set_prop() | |
| | dladm_wlan_get_prop() | |
| | dladm_wlan_walk_prop() | |
| | dladm_wlan_essid2str() | |
| | dladm_wlan_bssid2str() | |
| | dladm_wlan_secmode2str() | |
| | dladm_wlan_strength2str() | |
| | dladm_wlan_mode2str() | |
| | dladm_wlan_speed2str() | |
| | dladm_wlan_auth2str() | |
| | dladm_wlan_bsstype2str() | |
| | dladm_wlan_linkstatus2str() | |
| | dladm_wlan_str2essid() | |
| | dladm_wlan_str2bssid() | |
| | dladm_wlan_str2secmode() | |
| | dladm_wlan_str2strength() | |
| | dladm_wlan_str2mode() | |
| | dladm_wlan_str2speed() | |
| | dladm_wlan_str2auth() | |
| | dladm_wlan_str2bsstype() | |
| | dladm_wlan_str2linkstatus() | |
| |------------------------------------+------------------|
| | dladm_wlan_bssid_t | was wladm_*_t |
| | dladm_wlan_secmode_t | |
| | dladm_wlan_strength_t | |
| | dladm_wlan_mode_t | |
| | dladm_wlan_auth_t | |
| | dladm_wlan_bsstype_t | |
| | dladm_wlan_linkstatus_t | |
| | dladm_wlan_speed_t | |
| | dladm_wlan_channel_t | |
| | dladm_wlan_attr_t | |
| | dladm_wlan_linkattr_t | |
| | dladm_wlan_wepkey_t | |
| |------------------------------------+------------------|
| | DLADM_WLAN_CONNECT_TIMEOUT_DEFAULT | was WLADM_* |
| | DLADM_WLAN_CONNECT_CREATEIBSS | |
| | DLADM_WLAN_CONNECT_NOSCAN | |
+--------------+------------------------------------+------------------+
4 PSARC/2006/623 material updates
=================================
As the result of removing the libwladm library and changing its API
names, documents of PSARC/2006/623 need to be updated accordingly.
For the updated materials, see libdladm.txt, libdlwlan.txt and
PSARC_2006_623.diff in the "materials" directory.
--
meem
