Firmware versioning best practices II

Firmware versioning best practices II

[Luis R. Rodriguez]

Last year, with the help of the community we at Atheros opened up the
first (to my knowledge) firmware for a device driver used on the Linux
kernel. The community has been advancing the firmware and making
changes and even an alternative driver with more features is being
baked. We hadn't dealt with open firmware before and this itself
raises a few management questions about the firmware APIs, code
revision and general best practices which are likely not documented
anywhere. We reviewed this on linux-wireless last year [1] and Pavel
Roskin made a good suggestion for model to follow. I still have a few
more questions though and wanted a wider review on this.

I've documented a summary of what we have discussed and suggested so far here:

http://wireless.kernel.org/en/developers/Documentation/firmware-versioning

We should still address how drivers should deprecate firmware. Can we
deprecate old firmware APIs from drivers on each kernel release? Any
other comments or feedback?

[1] http://wireless.kernel.org/en/developers/Documentation/firmware-versioning

  Luis

Re: Firmware versioning best practices II

[David Woodhouse]

On Fri, 2010-02-19 at 18:23 -0800, Luis R. Rodriguez wrote:
> Last year, with the help of the community we at Atheros opened up the
> first (to my knowledge) firmware for a device driver used on the Linux
> kernel. The community has been advancing the firmware and making
> changes and even an alternative driver with more features is being
> baked. We hadn't dealt with open firmware before and this itself
> raises a few management questions about the firmware APIs, code
> revision and general best practices which are likely not documented
> anywhere. We reviewed this on linux-wireless last year [1] and Pavel
> Roskin made a good suggestion for model to follow. I still have a few
> more questions though and wanted a wider review on this.
> 
> I've documented a summary of what we have discussed and suggested so far here:
> 
> http://wireless.kernel.org/en/developers/Documentation/firmware-versioning
> 
> We should still address how drivers should deprecate firmware. Can we
> deprecate old firmware APIs from drivers on each kernel release? Any
> other comments or feedback?
> 
> [1] http://wireless.kernel.org/en/developers/Documentation/firmware-versioning
> 
>   Luis

So far it looks like you've just rewritten a subset of the rules for
handling shared library sonames.

I wouldn't suggest that including the API version as a _separate_ field
from the code version is best practice. Why not just bump the major # of
the code version when you change the API, just as we do with shared
libraries?

That doesn't prevent some people from using foo-$APIVER-$CODEVER if they
really have to, of course -- if they have firmware which can be
conditionally compiled for both old and new APIs, for example. But I
don't think it should be recommended.

-- 
David Woodhouse                            Open Source Technology Centre
David.Woodhouse@intel.com                              Intel Corporation

Re: Firmware versioning best practices II

[Johannes Berg]

[-- Attachment #1: Type: text/plain, Size: 700 bytes --]

On Sat, 2010-02-20 at 10:35 +0000, David Woodhouse wrote:

> That doesn't prevent some people from using foo-$APIVER-$CODEVER if
> they really have to, of course -- if they have firmware which can be
> conditionally compiled for both old and new APIs, for example. But I
> don't think it should be recommended.

That doesn't make much sense anyway. If the firmware filename is
foo-$APIVER-$CODEVER every code change would need a corresponding driver
change. If it is just foo-$APIVER then the $CODEVER can be embedded in
the firmware file and printed so you know which code you're using, but
if it doesn't influence the API I don't see why it should be part of the
filename?

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

Re: Firmware versioning best practices II

[David Woodhouse]

On Sat, 2010-02-20 at 12:00 +0100, Johannes Berg wrote:
> That doesn't make much sense anyway. If the firmware filename is
> foo-$APIVER-$CODEVER every code change would need a corresponding driver
> change. If it is just foo-$APIVER then the $CODEVER can be embedded in
> the firmware file and printed so you know which code you're using, but
> if it doesn't influence the API I don't see why it should be part of the
> filename? 

The idea is that just like with shared libraries, you have a symlink
from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.

For shared libraries, it's easy to create those symlinks automatically
using ldconfig. For firmware that doesn't really work though -- since
the soname isn't encoded in the file like it is in ELF libraries.

-- 
David Woodhouse                            Open Source Technology Centre
David.Woodhouse@intel.com                              Intel Corporation

Re: Firmware versioning best practices II

[Johannes Berg]

[-- Attachment #1: Type: text/plain, Size: 1075 bytes --]

On Sat, 2010-02-20 at 11:09 +0000, David Woodhouse wrote:
> On Sat, 2010-02-20 at 12:00 +0100, Johannes Berg wrote:
> > That doesn't make much sense anyway. If the firmware filename is
> > foo-$APIVER-$CODEVER every code change would need a corresponding
> driver
> > change. If it is just foo-$APIVER then the $CODEVER can be embedded
> in
> > the firmware file and printed so you know which code you're using,
> but
> > if it doesn't influence the API I don't see why it should be part of
> the
> > filename? 
> 
> The idea is that just like with shared libraries, you have a symlink
> from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.

Ah ok. I indeed do that manually with iwlwifi firmware :)

> For shared libraries, it's easy to create those symlinks automatically
> using ldconfig. For firmware that doesn't really work though -- since
> the soname isn't encoded in the file like it is in ELF libraries.

Right. Though I guess we could come up with a unified firmware wrapper
format that the firmware loader can unwrap.

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 801 bytes --]

Re: Firmware versioning best practices II

[David Woodhouse]

On Sat, 2010-02-20 at 12:10 +0100, Johannes Berg wrote:
> On Sat, 2010-02-20 at 11:09 +0000, David Woodhouse wrote:
> > On Sat, 2010-02-20 at 12:00 +0100, Johannes Berg wrote:
> > > That doesn't make much sense anyway. If the firmware filename is
> > > foo-$APIVER-$CODEVER every code change would need a corresponding
> > driver
> > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
> > in
> > > the firmware file and printed so you know which code you're using,
> > but
> > > if it doesn't influence the API I don't see why it should be part of
> > the
> > > filename? 
> > 
> > The idea is that just like with shared libraries, you have a symlink
> > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
> 
> Ah ok. I indeed do that manually with iwlwifi firmware :)
> 
> > For shared libraries, it's easy to create those symlinks automatically
> > using ldconfig. For firmware that doesn't really work though -- since
> > the soname isn't encoded in the file like it is in ELF libraries.
> 
> Right. Though I guess we could come up with a unified firmware wrapper
> format that the firmware loader can unwrap.

I suppose we could, but this seems like overkill to me.

-- 
David Woodhouse                            Open Source Technology Centre
David.Woodhouse@intel.com                              Intel Corporation

Re: Firmware versioning best practices II

[Marcel Holtmann]

Hi David,

> > > > That doesn't make much sense anyway. If the firmware filename is
> > > > foo-$APIVER-$CODEVER every code change would need a corresponding
> > > driver
> > > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
> > > in
> > > > the firmware file and printed so you know which code you're using,
> > > but
> > > > if it doesn't influence the API I don't see why it should be part of
> > > the
> > > > filename? 
> > > 
> > > The idea is that just like with shared libraries, you have a symlink
> > > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
> > 
> > Ah ok. I indeed do that manually with iwlwifi firmware :)
> > 
> > > For shared libraries, it's easy to create those symlinks automatically
> > > using ldconfig. For firmware that doesn't really work though -- since
> > > the soname isn't encoded in the file like it is in ELF libraries.
> > 
> > Right. Though I guess we could come up with a unified firmware wrapper
> > format that the firmware loader can unwrap.
> 
> I suppose we could, but this seems like overkill to me.

I have to agree. This looks like total overkill to me.

Just use the $APIVER in the firmware filename. And if someone wants to
keep track of more details then they can manually symlink them.

Unless we have full control over the source code of every firmware used
in the kernel, why bother. It is up to the companies providing them
anyway to make sure everything works as expected and the community can't
fix it.

Regards

Marcel

Re: Firmware versioning best practices II

[Luis R. Rodriguez]

On Sun, Feb 21, 2010 at 2:13 AM, Marcel Holtmann <marcel@holtmann.org> wrote:
> Hi David,
>
>> > > > That doesn't make much sense anyway. If the firmware filename is
>> > > > foo-$APIVER-$CODEVER every code change would need a corresponding
>> > > driver
>> > > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
>> > > in
>> > > > the firmware file and printed so you know which code you're using,
>> > > but
>> > > > if it doesn't influence the API I don't see why it should be part of
>> > > the
>> > > > filename?
>> > >
>> > > The idea is that just like with shared libraries, you have a symlink
>> > > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
>> >
>> > Ah ok. I indeed do that manually with iwlwifi firmware :)
>> >
>> > > For shared libraries, it's easy to create those symlinks automatically
>> > > using ldconfig. For firmware that doesn't really work though -- since
>> > > the soname isn't encoded in the file like it is in ELF libraries.
>> >
>> > Right. Though I guess we could come up with a unified firmware wrapper
>> > format that the firmware loader can unwrap.
>>
>> I suppose we could, but this seems like overkill to me.
>
> I have to agree. This looks like total overkill to me.
>
> Just use the $APIVER in the firmware filename.

OK -- so what goes into linux-firmware is just the latest

foo-$(API)

> And if someone wants to
> keep track of more details then they can manually symlink them.

Well do we want the older foo-$(API)-$(VAR) files in linux-firmware
too for those companies/developers wishing to do this?

What about deprecating APIs of the firmware based on kernel releases.
I see it reasonable to deprecate a firmware API completely for a
future kernel release provided you maintain all features and
functionality in par. Does that sound reasonable?

> Unless we have full control over the source code of every firmware used
> in the kernel, why bother. It is up to the companies providing them
> anyway to make sure everything works as expected and the community can't
> fix it.

Well that's exactly it -- we do have access to the code for ar9170 for
example, so these details will become more relevant in the future.

 Luis

Re: Firmware versioning best practices II

[Marcel Holtmann]

Hi Luis,

> >> > > > That doesn't make much sense anyway. If the firmware filename is
> >> > > > foo-$APIVER-$CODEVER every code change would need a corresponding
> >> > > driver
> >> > > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
> >> > > in
> >> > > > the firmware file and printed so you know which code you're using,
> >> > > but
> >> > > > if it doesn't influence the API I don't see why it should be part of
> >> > > the
> >> > > > filename?
> >> > >
> >> > > The idea is that just like with shared libraries, you have a symlink
> >> > > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
> >> >
> >> > Ah ok. I indeed do that manually with iwlwifi firmware :)
> >> >
> >> > > For shared libraries, it's easy to create those symlinks automatically
> >> > > using ldconfig. For firmware that doesn't really work though -- since
> >> > > the soname isn't encoded in the file like it is in ELF libraries.
> >> >
> >> > Right. Though I guess we could come up with a unified firmware wrapper
> >> > format that the firmware loader can unwrap.
> >>
> >> I suppose we could, but this seems like overkill to me.
> >
> > I have to agree. This looks like total overkill to me.
> >
> > Just use the $APIVER in the firmware filename.
> 
> OK -- so what goes into linux-firmware is just the latest
> 
> foo-$(API)
> 
> > And if someone wants to
> > keep track of more details then they can manually symlink them.
> 
> Well do we want the older foo-$(API)-$(VAR) files in linux-firmware
> too for those companies/developers wishing to do this?

personally I would say no, but for some projects it might make sense. I
would just leave this up to the project/driver itself.

> What about deprecating APIs of the firmware based on kernel releases.
> I see it reasonable to deprecate a firmware API completely for a
> future kernel release provided you maintain all features and
> functionality in par. Does that sound reasonable?

Realistically you have to deprecate firmware versions at some point
anyway. So yes, that makes sense. However I would leave this again up to
the driver itself and how far the maintainers wanna go in supported
older API versions.

> > Unless we have full control over the source code of every firmware used
> > in the kernel, why bother. It is up to the companies providing them
> > anyway to make sure everything works as expected and the community can't
> > fix it.
> 
> Well that's exactly it -- we do have access to the code for ar9170 for
> example, so these details will become more relevant in the future.

That is one of the few exception. However even for ar9170 there has to
be release engineering team that creates the binary and uploads it into
linux-firmware.git since I don't see the majority of people compiling it
from source. And at that point the release engineering needs to test the
API compatibility.

Regards

Marcel

Re: Firmware versioning best practices II

[Luis R. Rodriguez]

On Mon, Feb 22, 2010 at 11:27 AM, Marcel Holtmann <marcel@holtmann.org> wrote:
> Hi Luis,
>
>> >> > > > That doesn't make much sense anyway. If the firmware filename is
>> >> > > > foo-$APIVER-$CODEVER every code change would need a corresponding
>> >> > > driver
>> >> > > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
>> >> > > in
>> >> > > > the firmware file and printed so you know which code you're using,
>> >> > > but
>> >> > > > if it doesn't influence the API I don't see why it should be part of
>> >> > > the
>> >> > > > filename?
>> >> > >
>> >> > > The idea is that just like with shared libraries, you have a symlink
>> >> > > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
>> >> >
>> >> > Ah ok. I indeed do that manually with iwlwifi firmware :)
>> >> >
>> >> > > For shared libraries, it's easy to create those symlinks automatically
>> >> > > using ldconfig. For firmware that doesn't really work though -- since
>> >> > > the soname isn't encoded in the file like it is in ELF libraries.
>> >> >
>> >> > Right. Though I guess we could come up with a unified firmware wrapper
>> >> > format that the firmware loader can unwrap.
>> >>
>> >> I suppose we could, but this seems like overkill to me.
>> >
>> > I have to agree. This looks like total overkill to me.
>> >
>> > Just use the $APIVER in the firmware filename.
>>
>> OK -- so what goes into linux-firmware is just the latest
>>
>> foo-$(API)
>>
>> > And if someone wants to
>> > keep track of more details then they can manually symlink them.
>>
>> Well do we want the older foo-$(API)-$(VAR) files in linux-firmware
>> too for those companies/developers wishing to do this?
>
> personally I would say no, but for some projects it might make sense. I
> would just leave this up to the project/driver itself.

OK

>> What about deprecating APIs of the firmware based on kernel releases.
>> I see it reasonable to deprecate a firmware API completely for a
>> future kernel release provided you maintain all features and
>> functionality in par. Does that sound reasonable?
>
> Realistically you have to deprecate firmware versions at some point
> anyway. So yes, that makes sense.

OK

> However I would leave this again up to
> the driver itself and how far the maintainers wanna go in supported
> older API versions.

I was looking for general rules and guidelines to document. That
includes things to do and things to not do. It sounds we are flexible
with what people can do with their firmware and their driver firmware
API. The things to not do are not so clear though still. I am
wondering specifically about deprecation of older firmware APIs, or
are we flexible enough to allow any firmware API rewrite so long as
its properly supported?

>> > Unless we have full control over the source code of every firmware used
>> > in the kernel, why bother. It is up to the companies providing them
>> > anyway to make sure everything works as expected and the community can't
>> > fix it.
>>
>> Well that's exactly it -- we do have access to the code for ar9170 for
>> example, so these details will become more relevant in the future.
>
> That is one of the few exception. However even for ar9170 there has to
> be release engineering team that creates the binary and uploads it into
> linux-firmware.git

Release engineering team? Hah.

> since I don't see the majority of people compiling it
> from source.

I am curious how distributions will want to handle this. Distributions
with sane people might just ship a gcc built open firmware binary but
utopian distributions like Debian might require to build the whole
thing for redistribution. I don't know.

> And at that point the release engineering needs to test the
> API compatibility.

Release engineering.. heh...

  Luis

Re: Firmware versioning best practices II

[Marcel Holtmann]

Hi Luis,

> >> >> > > > That doesn't make much sense anyway. If the firmware filename is
> >> >> > > > foo-$APIVER-$CODEVER every code change would need a corresponding
> >> >> > > driver
> >> >> > > > change. If it is just foo-$APIVER then the $CODEVER can be embedded
> >> >> > > in
> >> >> > > > the firmware file and printed so you know which code you're using,
> >> >> > > but
> >> >> > > > if it doesn't influence the API I don't see why it should be part of
> >> >> > > the
> >> >> > > > filename?
> >> >> > >
> >> >> > > The idea is that just like with shared libraries, you have a symlink
> >> >> > > from the 'soname' foo-3.fw to the actual file foo-3-1.4.1.fw.
> >> >> >
> >> >> > Ah ok. I indeed do that manually with iwlwifi firmware :)
> >> >> >
> >> >> > > For shared libraries, it's easy to create those symlinks automatically
> >> >> > > using ldconfig. For firmware that doesn't really work though -- since
> >> >> > > the soname isn't encoded in the file like it is in ELF libraries.
> >> >> >
> >> >> > Right. Though I guess we could come up with a unified firmware wrapper
> >> >> > format that the firmware loader can unwrap.
> >> >>
> >> >> I suppose we could, but this seems like overkill to me.
> >> >
> >> > I have to agree. This looks like total overkill to me.
> >> >
> >> > Just use the $APIVER in the firmware filename.
> >>
> >> OK -- so what goes into linux-firmware is just the latest
> >>
> >> foo-$(API)
> >>
> >> > And if someone wants to
> >> > keep track of more details then they can manually symlink them.
> >>
> >> Well do we want the older foo-$(API)-$(VAR) files in linux-firmware
> >> too for those companies/developers wishing to do this?
> >
> > personally I would say no, but for some projects it might make sense. I
> > would just leave this up to the project/driver itself.
> 
> OK
> 
> >> What about deprecating APIs of the firmware based on kernel releases.
> >> I see it reasonable to deprecate a firmware API completely for a
> >> future kernel release provided you maintain all features and
> >> functionality in par. Does that sound reasonable?
> >
> > Realistically you have to deprecate firmware versions at some point
> > anyway. So yes, that makes sense.
> 
> OK
> 
> > However I would leave this again up to
> > the driver itself and how far the maintainers wanna go in supported
> > older API versions.
> 
> I was looking for general rules and guidelines to document. That
> includes things to do and things to not do. It sounds we are flexible
> with what people can do with their firmware and their driver firmware
> API. The things to not do are not so clear though still. I am
> wondering specifically about deprecation of older firmware APIs, or
> are we flexible enough to allow any firmware API rewrite so long as
> its properly supported?

this is more a driver problem. If the firmware API changes, then the
driver must support some of the older versions. Obviously supporting all
API versions becomes a major pain at some point. And then you have to
deprecate a firmware version.

How many firmware API you support should be really up to the driver
maintainer, but at minimum it should be the previous one. That is at
least my take on this.

> >> > Unless we have full control over the source code of every firmware used
> >> > in the kernel, why bother. It is up to the companies providing them
> >> > anyway to make sure everything works as expected and the community can't
> >> > fix it.
> >>
> >> Well that's exactly it -- we do have access to the code for ar9170 for
> >> example, so these details will become more relevant in the future.
> >
> > That is one of the few exception. However even for ar9170 there has to
> > be release engineering team that creates the binary and uploads it into
> > linux-firmware.git
> 
> Release engineering team? Hah.

Let me translate this a bit. Whoever does create the source tarball
release should also build a binary release. So both packages have proper
version information, but inside the binary release, the filename is only
firmware-$(API).

> > since I don't see the majority of people compiling it
> > from source.
> 
> I am curious how distributions will want to handle this. Distributions
> with sane people might just ship a gcc built open firmware binary but
> utopian distributions like Debian might require to build the whole
> thing for redistribution. I don't know.

I would welcome distros going that far and building the firmware if it
is possible, but I am not sure if most people would bother.

> > And at that point the release engineering needs to test the
> > API compatibility.
> 
> Release engineering.. heh...

As I said, whoever releases the source tarball should also do basic
checks with the binary firmware that results from it. Someone has to do
it. Otherwise there is no point here anyway.

Regards

Marcel