kernel/file.c

Headers

The usual kernel headers plus those that define the objects an open file can refer to: kernel/fs.h and kernel/file.h (inodes and struct file), the two lock headers, kernel/stat.h for struct stat, and kernel/proc.h for myproc. struct pipe stays opaque: only kernel/pipe.c knows its fields, and this file only passes pointers to it along.

The device switch and the open-file table

devsw (“device switch”) has one entry per major device number, up to NDEV = 10. Each entry holds two function pointers, the device’s read and write. Drivers fill in their entry at boot; the only one in xv6 is the console, consoleinit sets devsw[CONSOLE] (kernel/console.c:201). Entries left at zero mean “no such device”.

ftable holds all open files in the system, NFILE = 100 of them, with a spinlock protecting each entry’s ref. An entry with ref == 0 is free. Being in .bss, the table starts all zeros: every entry free, of type FD_NONE.

Descriptors and table entries are not one-to-one. Several descriptors, in one process (after dup) or in several (after fork), can point to the same struct file, and then they share its offset. ref counts those pointers.

fileinit(): set up the table's lock

Called once by hart 0 from main. The entries need no initialization (see above).

filealloc(): claim a free open-file entry

Finds an entry with ref == 0 and claims it by setting ref = 1, both under ftable.lock, so two processes can never claim the same entry. The other fields are left for the caller to fill in: sys_open sets the type, inode, offset and access mode, and pipealloc sets up the two ends of a pipe. Filling them in after the lock is released is safe, since no other code looks at an entry that it did not allocate or receive.

Returns 0 when all 100 entries are in use; open and pipe then fail.

filedup(): one more descriptor for the same open file

Increments the reference count. sys_dup calls it when a second descriptor is made for the same file, and kfork calls it for each of the parent’s open descriptors, so that parent and child share the open files (kernel/proc.c:287).

Duplicating a free entry (ref < 1) would resurrect something that may already have been handed to someone else, so it is a kernel bug and panics.

fileclose(): drop a reference, and close for real on the last one

Called by sys_close, by kexit for every descriptor the process still has open, and by sys_open and sys_pipe to undo a half-finished allocation.

If other descriptors still refer to the file, only the count changes. On the last reference the entry is freed, and then the object behind it is released: a pipe end is closed with pipeclose, an inode reference is dropped with iput.

Notice the two-step shape. The entry is copied into the local ff, marked free, and the lock released before the cleanup. The cleanup may sleep (iput may wait for the disk), and xv6 does not allow sleeping while holding a spinlock. The copy is needed because once the entry is marked free and the lock released, filealloc on another CPU may hand it out and overwrite its fields.

The iput is wrapped in begin_op/end_op because it may be the last reference to a file that was deleted while open, in which case iput frees the file’s blocks and inode, and those writes must be part of a transaction.

filestat(): fstat for an open file

Implements the fstat system call (sys_fstat). Only files that have an inode, plain files, directories and devices, have metadata; for a pipe it returns -1.

The inode is locked while stati copies the fields, so they come from a single moment (and, if the inode has not been read yet, ilock reads it from disk). The result is built in a kernel variable and then copied to the user’s address with copyout, which fails, giving -1, if addr is not valid writable user memory.

fileread(): read from whatever the file is

The common entry point of the read system call (sys_read). After checking that the file was opened for reading and n is not negative, it dispatches on the type:

• FD_PIPE: piperead takes bytes from the pipe’s buffer, sleeping until a writer provides some.
• FD_DEVICE: call the device’s read function from devsw, after checking that the major number is in range and the device has a read function. The first argument, 1, says that addr is a user address.
• FD_INODE: lock the inode, readi from the file’s current offset, and advance the offset by what was read. A return of 0 means end of file.

The inode case needs no transaction: reading never writes to the disk. The offset is updated while the inode lock is held, so two processes sharing one struct file (after fork) cannot both read the same bytes with the same offset.

filewrite(): checks, pipes and devices

The write counterpart of fileread, called from sys_write. The access check, the pipe case (pipewrite) and the device case (through devsw) mirror fileread exactly. Only writing to an inode is different, because it changes the disk and must be cut into file-system operations of bounded size, each part of a transaction.

Why writes are split into 3-block chunks

Every block a file system operation (one begin_op/end_op pair) changes is held in the log until the transaction it belongs to commits; the log may group several concurrent operations into one transaction. begin_op reserves room for at most MAXOPBLOCKS = 10 blocks per outstanding operation. A single writei of a large buffer could change far more blocks than that, so filewrite writes at most max bytes per operation:

((MAXOPBLOCKS - 1 - 1 - 2) / 2) * BSIZE = ((10 - 4) / 2) * 1024 = 3072 bytes.

Each term is a block one chunk might have to log:

• - 1: the inode’s own block, rewritten by iupdate at the end of writei (new size, new block addresses).
• - 1: the indirect block, changed when bmap records a newly allocated block in it.
• - 2: slop for a write that does not start on a block boundary: 3072 bytes then touch 4 data blocks instead of 3. (The first of them always exists already, because the write starts at or before the end of the file, so at most 3 are newly allocated.)
• / 2: each data block may cost two log entries: the data block itself and the free bitmap block whose bit balloc sets when the block is new.

Worst case: 4 data blocks, 4 bitmap updates (3 new data blocks plus the new indirect block), the indirect block, and the inode = 10 = MAXOPBLOCKS. (On the default disk there is only one bitmap block, so the real use is lower: repeated writes to one block occupy a single log slot.)

One file-system operation per chunk

Each chunk is a complete file system operation: begin_op, ilock, writei at the current offset, advance the offset, iunlock, end_op. The order matters: begin_op comes before the inode lock. begin_op may sleep until the log commits, and a commit waits for every operation in progress to finish. A process sleeping in begin_op while holding an inode lock could block an operation that needs that lock, which then never finishes, so the commit never happens.

Two consequences you can observe. A large write is not atomic: after a crash, the first chunks may be on disk and the rest not. And another process’s writes to the same file can land between chunks, since the inode lock is released after each one.

If writei wrote less than asked (disk full, bad user address, file at its maximum size), the loop stops.

All or error

The return value is n if every byte was written and -1 otherwise, even if some chunks were written successfully; those bytes stay in the file. A file type other than the three known ones means the struct file is corrupt, and the kernel panics.