2
README for external mac80211 subsystem package
3
Copyright (c) 2007, Intel Corporation
5
version: mac80211-${MAC80211_VERSION}
9
This archive provides a package for the mac80211 subsystem,
10
installable into most kernels with a version of 2.6.18 or
11
later. You can determine your kernel version by running:
16
NOTE: The mac80211 subsystem is being developed by a group of
17
community developers. Intel put together this packaging system
18
in order to better facilitate the widespread availability and
19
adoption of the subsystem.
21
This file provides an overview of why the mac80211 package exists,
22
what it does, and how it does it.
36
If you're a user that just wants to try and get up and running
37
as quickly as possible, here are the simplest steps we have so
42
The above, if it succeeds, should patch your current running
43
kernel source tree to contain the mac80211 subsystem sources. Now
44
you need to configure your kernel build to build the mac80211
47
% cd /lib/modules/\$(uname -r)/build
50
You will want to set the following to <M>:
55
Generic IEEE 802.11 Networking Stack (dscape)
57
You can turn on the sub-options for that subsystem if you want.
59
Select 'Exit' until it prompts to save your kernel configuration
60
and select 'Yes'. Now you can build the module:
63
% make modules_install
65
NOTE: As of mac80211-2.0.0 you must also enable CONFIG_CFG80211 and
66
rebuild your main kernel image. This is because the latest mac80211
67
changes re-implement the kernel built-in from net/core/wireless.c as
68
part of the net/wireless/ sources.
73
You will then need to reboot into the new kernel (vs. just loading the
79
The network community for the Linux kernel typically has an
80
approach of focusing purely on the 'tip'. To the average
81
user that means that bug fixes, patches, and enhancements will
82
only be available to you if you can upgrade to the latest
83
development kernel. For some, this is acceptable. For others,
86
This package is created in order to try and provide the user (you)
87
with fixes and enhancements that affect *just* the wireless
88
subsystem required for use with your hardware.
90
As with any software, new changes may introduce new bugs.
91
Upgrading from one version of the mac80211 subsystem to the
92
next might regress a problem, or even introduce a new one --
93
if it does, and you find it, please file a bug at
94
http://bughost.org under the project 'mac80211'.
99
So what does this package contain? It represents the latest
100
version of the mac80211 as available via the GIT repository
103
git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-dev.git
105
In addition to the above, any patches submitted by the mac80211 subsystem
106
developers which are deemed to be bug fixes or improve existing
107
functionality which have not been made available in the GIT repository.
109
When you run make on your system, the build scripts will examine your
110
target kernel to determine which backward compatibility changes are
111
required to compile on your system. A side effect of the mac80211
112
developers using the latest kernel tip as their baseline is that the
113
subsystem itself emerges to use whichever new features or APIs may have
114
been made available in the rest of the kernel. This will typically
115
break building and running on kernels released prior to those changes.
116
The build system for this package attempts to correct that behavior.
121
When you run the build, it runs a series of scripts against the
122
target kernel. The target is specified via KSRC=/patch/to/kernel.
123
If no KSRC is provided, it will default to looking in:
125
/lib/modules/\$(uname -r)/build
127
Each of the scripts attempts to determine if a given set of
128
kernel functionality is present. In the good old days, a module
129
could do something simple like:
131
#if LINUX_VERSION_CODE < KERNEL_VERSION(2,6,19)
134
/* some other code */
137
Over the last few years, however, this approach has broken due
138
to a number of reasons. The two most prominent causes are:
140
* Kernel API and structure changes occurring within
141
an -rc update (which can not be checked with the
142
KERNEL_VERSION macro)
144
* Distributions backporting new kernel features into
145
older kernels such that the older vanilla kernel
146
(as originally provided by Linus) does not have the
147
feature but the distributor does.
149
An example of what a script might do is perform a grep operation
150
on a particular header file to determine if the parameters
151
passed to a function have changed, or if a particular definition
155
What is in a release?
157
The details of how a typical release cycle is as follows:
159
1. Latest files are obtained from Jiri's GIT
160
repository into a local GIT tree (eg., /repos/jbenc)
162
2. mac80211 subsystem files are copied from the GIT tree into
163
the 'origin' directory via:
165
% make BASE=/repos/jbenc origin
167
3. The patches in the 'pending' directory are applied to the
168
'origin' in numerical sequence to build a new tree stored
169
in the 'modified' directory.
171
4. Miscellaneous testing is performed (build iwlwifi, associate,
174
5. The files in 'stubs' are sourced with the following
175
environment variables defined:
176
MAC80211_VERSION=versionstring
177
with the output of that sourcing going into the base
178
directory as a file with the same name (eg., stubs/README
179
creates README). This is used to update the documentation
180
to contain the latest version fields.
182
6. The package is tarballed up with a version stamp named:
183
mac80211-\${MAC80211_VERSION}.tgz
185
7*. A test system performs a tinderbox build of the package
187
* Linus' vanilla kernels > 2.6.18
188
* Latest kernel sources version available as a 'stable'
189
package from the following distributions (alphabetical):
196
* This is not yet done. Currently I have to do the smoke test
197
build by hand, which means I'm only building against the latest
198
Gentoo kernel and a couple other random kernel images I have on
204
The build supports multiple targets depending on what you
205
are trying to do. This section provides an overview of each
209
Removes *.ko, *.o, and *.mod.c from the tree. This
210
also deletes the compat directory (built with the
217
Updates the tip sources. Specify the source repository
218
via BASE= on the make command line.
220
NOTE: The script will not perform any GIT fetching
221
from the Internet and will only copy the mac80211 related
222
files from the directory specified. If you want to
223
update to the latest GIT version you would need to
224
first obtain Jiri Benc's GIT repository and then direct
225
the make to that directory via BASE. By default,
226
the script will look in /home/repos/mac80211/
228
Once the tip files are copied, the patches in 'pending'
229
are applied in sequential order.
231
See scripts/generate_origin
235
Creates a modified 'tip' applying all of the patches
236
from the 'pending' directory.
238
See scripts/generate_modified
242
Examines if the target kernel can be used without
243
any changes to the modified mac80211 sources provided in the
244
tip directory and creates a compatible version of the
245
sources from 'modified' in the 'compatitble' directory.
247
See scripts/generate_source
251
Examines if the target kernel can be used without
252
any changes to the modified mac80211 sources provided in the
253
tip directory and creates a compatible version of the
254
sources from 'origin' in the 'compatitble' directory.
256
You would typically use this if you want a "pure" version
257
of mac80211 compatible with your kernel.
259
See scripts/generate_source
263
Transfers the generated or tip sources into the target
264
kernel. This will also patch the required kernel
265
build files (Makefile, Kconfig, etc.) as needed in order
266
to add the mac80211 subsystem to the build.
268
See scripts/patch_kernel
272
Builds a distribution tarball and places it in the
273
distros directory. The filename for the tarball is
274
mac80211-\${MAC80211_VERSION}.tgz.
276
NOTE: MAC80211_VERSION defaults to 'test'.
280
Updating compatibility
282
Ok -- you're developing, or you just moved to a new kernel and
283
*WHAM* the kernel build breaks. Once the root cause of the
284
build failure is determined, a patch is required in order
285
to support making that kernel 'just work' for everyone else.
287
The following are the typical steps performed:
293
Now, edit the sources in the compatible/ directory. You can test
294
your sources by running:
297
% cd /lib/modules/\$(uname -r)/build
298
% make menuconfig <-- If you haven't already enabled mac80211
301
Once you are satisfied the build problems are fixed, create
304
% diff -Nupr old compatible > compatible-\$(uname -r).patch
306
The work to this point is a huge help to others in the community
307
so go ahead and send the patch to the mac80211-devel mailing list.
309
If you want to figure out how to modify the mac80211 package so
310
that it will automatically apply your patch if needed, look
311
in the following scripts:
313
scripts/determine_compat
314
scripts/generate_compatible
319
The mac80211 package uses a three field versioning scheme:
323
X will increase whenever a new base/tip is taken from the kernel.
324
You can see tip/GIT for the commit ID head cached when the
325
'make update' target was used.
327
Y will increase as snapshots are made available in the external
328
package that may contain code which has not yet been merged into
331
Z will increase only as bug or compatibility patches are made
332
available against a given snapshot. Z increases will not contain
333
new functionality and are intended to only provide stability
added
removed
updates/wireless/iwlwifi/mac80211/stubs/README
