On Mon, 2009-01-05 at 09:21 -0800, Dan Williams wrote:
> 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.
Agreed. If I never see a "DoSomethingEx()" API again it will be too
soon.
> 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.
Agreed. I will remove Reset()
>
> ? 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.
The adapter specific config options are the information handed to the
firmware to limit the search/scan space for the scan. Wide scans
(scanning all bands and channels) can take tens of minutes and gets
worse with each frequency range the adapter can operate in.
I don't know what other WiMax vendors firmware/driver interface looks
like to constrain the space scanned by the call to Scan(). I am pretty
sure that the UI component does not want to maintain the information
even if we standardized it since it will be network provider dependent.
This information will also change based on the any roaming agreements
between vendors.
The thought was that it would be better to leave this to the
Adapter/Device configuration mechanism used for a given platform/device
(MID, netbook, CPE, notebook) which will likely differ based on device
integrator and the geography where the device is sold/used.
>
> ? 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()
The credential agent interface is meant to collect credential
information from the user so the flow above would be reasonable or the
agent could throw up a dialog box for the user to fill in the
information. I am not a UI guy I don't know what the right model is.
I am unaware of any network provider using username/password to
authenticate to the network. It's not clear to me that this interface
will needed over time. The interface is in at the moment since the
capability exists in the WiMax Common API in windows and I wanted to
make sure we were feature compatible with the windows API.
> ? NetworkFound -> NetworkAppeared: a consistency thing; since the
> "disappeared" signal is NetworkDisappeared... Just a suggestion.
How about NetworkAvailable NetworkUnavailable?
>
> ? What sort of thing goes in the Name property?
Something a little more user friendly than wmx1, wmx2 ...
Not being a UI guy I am not sure if this is desirable or not, maybe the
CM would want to give the adapter a more firendly name.
>
> ? 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.
>
Agreed. I will rework this
> ? LockedNSPInfo
>
> ? SetProperty signal should emit a new
> "org.wimax.Error.PropertyReadOnly" error if the property is read-only
>
Agreed I will add to document.
>
> NETWORK
> -------------
> ? The D-Bus interface listed is "org.wimax.Device", which seems quite
> wrong; you probably meant "org.wimax.Network" ?
Yep will fix
>
> ? What's "RoamingMode", what are it's values, and how is it used?
RoamingMode is to tell the firmware how/if to roam. We will have to
work on the valid values.
I think a starting point for allowable values could be:
Auto = Do what it takes to maintain the connection
Home = Only roam within the home network. Do not try roaming partners
None = Don't roam
The reason for this is to give the user control of roaming behavior
since there may be costs involved with roaming based on their network
plan.
>
> ? txPwr (-> TxPower) / bsId (-> BSID) / provisioned (-> Provisioned) =
> Use consistent capitalization
>
I will fix this
> ? 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.
>
I think these belong in the network object since they are properties of
the discovered network. The dbus server object should be responsible
for persisting these values for a given network object.
These are not properties of the adapter since the adapter could see
multiple networks each having a different desired behavior based on user
input or network provider configuration.
I think we need real world usage model information to make a good
decision on what is the correct long term solution. I will try to get
information from people using the windows WiMax common API about how and
if they are using this feature.
> 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.
I agree. When we were talking about the interfaces internally we came
to basically the same conclusion but I wanted to bring the question to
the community to see if there were any great ideas out there for a
standard configuration/profile interface. I know I don't have enough
information about other vendors adapters/firmware to have a hope of
defining an interface that would be useful and general enough.
>
> ? 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.
We had long discussions about this one too :) Having all signal come
from a single object is clearly easiest on the client. Although where
should we have the signal coming from? it kind of breaks the object
model or requires you to hold your head just right for it to make
sense :). Either solution works for me I want to bring the issue to the
list so I didn't have to answer the question why we were blurring the
lines between the objects.
Thanks for the review and input Dan I will get the proposed changes out
on the list RSN.
--Dirk
