Documentation/kbuild are now limited to kernel development information,
so there is no point asking people to look there, when
searching information about building the kernel.
Pinting to README makes most sense

Patch from: YOSHIFUJI Hideaki <yoshfuji@wide.ad.jp>

make dep is obsolete - so remove it from the documentation
at various places

Originally by Michael Still <mikal@stillhq.com>

This patch adds two new targets to the docbook makefile -- mandocs, and
installmandocs. The targets require two new perl scripts in the scripts/
directory, but in return we get a series of man pages for kernel
functions, which are installed in man section 9. This is a good thing, as
many programmers expect documentation to be available with man, and
hunting through various PS or PDF documents to find the documentation for
the function you want can be quite frustrating.

The man pages are just extracted from the various existing DocBook SGML
documents, which are generated by kernel-doc. You also need to have
docbook2man installed on your machine.

Please note the formatting is not perfect, but I will tweak
other stuff later with further patches -- this is just an initial
implementation.

Sample output (HTMLised) can be found at
http://www.stillhq.com/linux/mandocs/2.5.68/ and
http://www.stillhq.com/linux/mandocs/2.5.70/

commands.txt
Content was not updated for a long time, and README includes the same info

random.txt
make help includes the same info (in compressed format)

When CONFIG_DEBUG_INFO is set to Y, -g will be added to CFLAGS.
Several architectures already put -g in CFLAGS, often via a patch
to the top-level makefile.
This option is put in the kernel hacking menu, guarded by CONFIG_DEBUG_KERNEL.

Added CONFIG_DEBUG_INFO in Kconfig for the architectures that
already had CONFIG_DEBUG_KERNEL

Thanks to Riley Williams

Patch by Matthew Wilcox
Eliminate ifneq by introducing a kbuild style assignment
whitespace -> tabs
 

Patch originally by HJ Lu.

The filesystem was previously embedded in a .o file using ld.
Embedding the filesystem using ld broke as a result ia64 and maybe more
architectures.

The better way to do this is to use the .incbin feature, as already
used for vsyscall for i386. .incbin has the advantage that ELH header
is correct, as required by ia64 - and maybe other archs.
This change will break architectures relying on binutils older than
2.11.90.0.23 released on 2001-07-14.
Most notably arm will break in some configurations due to this.
The rationale behing introducing .incbin is that ia64 needs this change
and the .incbin feature has been present in binutils for a number
of years now.
arm will thus have to catch up with binutils - or patch usr/Makefile
to stay compatible with the 2.5 kernel.

The definition of LDFLAGS_BLOB removed for all architectures - it was 
obsoleted by this change.
Except for arm - that may require it due to the tool compatibility issue.

into home.transmeta.com:/home/torvalds/v2.5/linux

into kroah.com:/home/greg/linux/BK/i2c-2.5

Boot ROMs have talked TFTP forever.  Some do it over USB now.

  - switch to usb_buffer_alloc

We cannot sensibly support O_DIRECT reads or writes when all writes are
journalled.

This is because the VFS explicitly avoids syncing the file metadata during
O_DIRECT reads and writes.  ext3 with journalled data will leave pending
changes in memory and they will overwrite the results of O_DIRECT writes, and
O_DIRECT reads will not return the latest data.

Setting the a_op to null will cause opens and fcntl(F_SETFL) to return
-EINVAL if O_DIRECT is requested.

Minro tweak: once log_wait_for_space() has created sufficient space in the
journal to start the new handle, hang onto the spinlock as
start_this_handle() loops around to reevaluate the journal's state.

It prevents anyone else from zooming in and stealing the space we just made.

There are various places in which JBD is starting a commit against a
transaction without sufficient locking in place to ensure that that
transaction is still alive.

Change it so that log_start_commit() takes a transaction ID instead.  Make
the caller take a copy of that ID inside the appropriate locks.

log_do_checkpoint is playing around with a transaction pointer without enough
locking to ensure that it is valid.  Fix that up by revalidating the
transaction after acquiring the right locks.

With data=ordered it is often the case that a quick write-and-truncate will
leave large numbers of pages on the page LRU with no ->mapping, and attached
buffers.  Because ext3 was not ready to let the pages go at the time of
truncation.

These pages are trivially reclaimable, but their seeming absence makes the VM
overcommit accounting confused (they don't count as "free", nor as
pagecache).  And they make the /proc/meminfo stats look odd.

So what we do here is to try to strip the buffers from these pages as the
buffers exit the journal commit.

This was a flag which said "the transaction's time is active".
timer_pending() could have told us that, but in fact there is no need to
query it at all.

Fix various problems which cropped up due to MAP_SHARED traffic on
data=journal with blocksize < PAGE_CACHE_SIZE.

All relate to handling the "pending truncate" buffers outside i_size.

start_this_handle() can decide to add this handle to a transaction, but
kjournald then moves the handle into commit phase.

Extend the coverage of j_state_lock so that start_this_transaction()'s
examination of journal->j_state is atomic wrt journal_commit_transaction().

Try to trap some more state when an assertion which cannot happen happens.

Before taking the highly-taken j_list_lock, take a peek to seem if this
buffer is already journalled and in the appropriate state.

ext3 no longer keeps the filesystem-wide free blocks counter and free inodes
counter up to date all the time in the superblock.  Because that requires
fs-wide locking.  These counters are only needed at runtime for the Orlov
allocator heuristics, and we are now using a fuzzy per-cpu coutner for that.

These counters are rather unnecessary: the same info is present in the file
allocation maps and inode tables, the group descriptor blocks and the
bitmaps.

e2fsck will be changed to downgrade the seriousness of this inconsistency.

The filesystem _will_ write these numbers out in the superblock on a clean
unmount, based on the sum of the free block and inode counts in the group
descriptors.

From: Andreas Gruenbacher <agruen@suse.de>

This function can leak a posix_acl on an error path.

The ioctl handler can leave a transaction open on an error path.  That
will wedge up the filesystem.

add a dump_stack() to a can't-happen path which happened during development.

There is a race between transaction commit's attempt to free journal_heads
and journal_try_to_free_buffers' attempt.

Fix that by taking a ref against the journal_head in
journal_try_to_free_buffers().

ext3's fully data-journalled mode has been broken for a year.  This patch
fixes it up.

The prepare_write/commit_write/writepage implementations have been split up.
Instead of having each function handle all three journalling mode we now have
three separate sets of address_space_operations.

The problematic part of data=journal is MAP_SHARED writepage traffic: pages
which don't have buffers.  In 2.4 these were cheatingly treated as
data-ordered buffers and that caused several nasty problems.

Here we do it properly: writepage traffic is fully journalled.  This means
that the various workarounds for the 2.4 scheme can be removed, when I
remember where they all are.

The PG_checked flag has been borrowed: it it set in the atomic set_page_dirty
a_op to tell the subsequent writepage() that this page needs to have buffers
attached, dirtied and journalled.

This rather defines PG_checked as "fs-private info in page->flags" and it
should be renamed sometime.

Avoid holding the journal's j_list_lock while copying the buffer_head's data.
We hold jbd_lock_bh_state() during the copy, which is all that is needed.

In start_this_handle() the caller does not have a handle ref pinning the
transaction open, and so the call to log_start_commit() is racy because some
other CPU could take the transaction into commit state independently.

Fix that by holding j_state_lock (which pins j_running_transaction) across
the log_start_commit() call.

Plug a conceivable race with the freeing up of trasnactions, and add some
more debug checks.

Drop in a few assertions to ensure that the locking rules are being adhered
to.

Add a comment describing why a race isn't there.

After ext3_writepage() has called block_write_full_page() it will walk the
page's buffer ring dropping the buffer_head refcounts.

It does this wrong - on the final loop it will dereference the buffer_head
which it just dropped the refcount on.  Poisoned oopses have been seen
against bh->b_this_page.

Change it to take a local copy of b_this_page prior to dropping the bh's
refcount.

We need to check that buffer is still journalled _after_ taking the right
locks.

There's a bug: a caller tries to journal a buffer and then decides he didn't
want to after all.  He calls journal_release_buffer().

But journal_release_buffer() is only allowed to give the caller a buffer
credit back if it was the caller who added the buffer in the first place.

journal_release_buffer() currently looks at the buffer state to work that
out, but gets it wrong: if the buffer has been moved onto a different list by
some other part of ext3 the credit is bogusly not returned to the caller and
the fs can later go BUG due to handle credit exhaustion.


The fix:

Change journal_get_undo_access() to return the number of buffers which the
caller actually added to the journal.  (one or zero).

When the caller later calls journal_release_buffer(), he passes in that
count, to tell journal_release_buffer() how many credits the caller should
get back.

For API consistency this change should also be made to
journal_get_create_access() and journal_get_write_access().  But there is no
requirement for that in ext3 at this time.


The remaining bug:

This logic effectively gives another transaction handle a free buffer credit.
These could conceivably accumulate and cause a journal overflow.  This is a
separate problem and needs changes to the t_outstanding_credits accounting
and the logic in start_this_handle.