On Thu, 2008-12-11 at 08:41 -0800, Dirk Brandewie wrote:
> Hi Everyone,
>
> The attached files represent a proposed dbus based API to access the
> Linux WiMax stack. This proposal is the result of a number of
> discussions over the last few months at OLS and the plumbers
> conference.
>
> Overview:
> There are two object types used to access the WiMax stack the adapter
> and network object.
>
> The adapter (adapter-api.txt) object is created when the hardware
> device is discovered in the system. This object is used to control the
> state of the adapter and the process of scanning for available
> networks.
>
> The network (network-api.txt) object is created when a network is
> discovered via the adapter.Scan() method. This object is used to
> control the state and report information about available network
> connections.
>
> There is one helper agent (agent-api.txt) that is meant to call out to
> gather user credentials i.e.(username, password). The current file is
> just a placeholder.
General comments...
? Maybe use "org.wimax1.XXXX" as the interface for all of these, so that
later on perhaps a "org.wimax2" interface could be defined when things
change or need to be reworked. People are still somewhat divided on
using versioned D-Bus interfaces, but it's not a horrible idea, and
saves you from doing the Microsoft "DoSomethingEx()" API that looks &
feels bad.
ADAPTER
---------------------------
? What scenarios would reset be used in, or what exactly gets "reset"
when Reset() is called? In Linux, hardware doesn't generally get reset
by the user, but by the driver when the hardware is in an unrecoverable
state, and the driver handles re-applying the state, or notifying
userspace that the state is reset. We shouldn't be hacking around
broken firmwares with a "Reset WiMAX Adapter" button in the UI like the
Intel Windows WiMAX app has, we should be making the hardware/firmware
actually work. If it really *does* need a reset, the driver should be
able to detect that and handle it accordingly without user interaction.
? What "adapter specific" config options does Scan() use? Can't most of
the key/value pairs be standardized? If it does take a dict (a{sv} in
D-Bus type nomenclature) then the doc should probably be updated to
reflect that it takes those options, or else some reference to how to
send/set those values should be made.
? What provides the Credentials agent service? Can you describe more
fully how this is supposed to work? From the docs I can't see how it
could, unless there are methods to add/remove credentials from the
org.wimax D-Bus service, which I don't see. Was the flow supposed to
be:
org.wimax.Adapter.RegisterCredentialAgent("/something/I/make/up")
org.wimax.Agent.SetProperty({ "Username": "dcbw", "Password", "foobar")
org.wimax.Network.Connect()
?
? NetworkFound -> NetworkAppeared: a consistency thing; since the
"disappeared" signal is NetworkDisappeared... Just a suggestion.
? What sort of thing goes in the Name property?
? Powered -> RadioOn or RfOn or something? From the description, it's
really an rfkill state, and since other stuff (SoftwareRfKillState,
HardwareRfKillState) talks about rfkill, this probably should too.
"Powered" could mean whether the card itself has power, not necessarily
whether the radio is on/off. Best to be clear.
? LockedNSPInfo
? SetProperty signal should emit a new
"org.wimax.Error.PropertyReadOnly" error if the property is read-only
NETWORK
-------------
? The D-Bus interface listed is "org.wimax.Device", which seems quite
wrong; you probably meant "org.wimax.Network" ?
? What's "RoamingMode", what are it's values, and how is it used?
? txPwr (-> TxPower) / bsId (-> BSID) / provisioned (-> Provisioned) =
Use consistent capitalization
? Reconnect - there's got to be a better place for this, like
RoamingMode. Having these a *changable* properties on the Network
objects means that (unless something saves these values and restores
them whenever the network is scanned) ConMan or NetworkManager or
whatever have to re-set the correct value on the network each and every
time it's newly found. That kinda sucks. For Reconnect (and maybe
RoamingMode), couldn't these be global values on the adapter object
instead? What is a per-network reconnect property required instead of a
per-adapter reconnect property? The per-adapter property could be a
number of values including "never reconnect", "reconnect to home network
only", or "reconnect to any network". Same sort of thing for
RoamingMode maybe.
OPEN ISSUES
---------------
? Could you describe the comments about profiles here? I tend to think
that "profiles" as generally understood are better left to the userspace
processes that control *all* the connections of the device. I feel like
any sort of "profile" stuff in the D-Bus service itself would (a) get
out of date and become inflexible quickly, (b) have to be saved
somewhere by the service, and (c) add a bunch more API that's not really
needed since higher-level connection managers are going to duplicate
most of this anyway, requiring them to translate their own settings into
the wimax service "profiles" and back again, ie more code.
? State transitions: usually done on the interfaces & objects themselves
so that the signal routing code on the client side is less complex.
Since a process that is interested in signals for some object is
*already* by definition handling that object somehow, and since it's
quite a lot cleaner client-side to process signals for objects on the
object itself, I don't think they should all be crammed into a single
interface.
Dan
