kernel/file.h

C header · 40 lines · annotated 100% · kernel · upstream

Included by 7 files

kernel/console.c, kernel/file.c, kernel/fs.c, kernel/pipe.c, kernel/printk.c, kernel/sysfile.c, user/init.c

About this file

The in-memory structures of the file layer: struct file, one open file (struct file); struct inode, the kernel’s in-memory copy of an inode; and struct devsw, the table that connects device files to their drivers. Their on-disk counterparts are in kernel/fs.h.

kernel/file.c and kernel/fs.c contain the code that manages these structures, and kernel/sysfile.c and kernel/pipe.c use them. The header is also included by user/init.c, which needs the CONSOLE constant to create the console device file.

Read before: kernel/fs.h. Read next: kernel/fs.c, kernel/file.c.

Show notes inline

1struct file {
2  enum { FD_NONE, FD_PIPE, FD_INODE, FD_DEVICE } type;
3  int ref; // reference count
4  char readable;
5  char writable;
6  struct pipe *pipe; // FD_PIPE
7  struct inode *ip;  // FD_INODE and FD_DEVICE
8  uint off;          // FD_INODE
9  short major;       // FD_DEVICE
10};
11
12#define major(dev)  ((dev) >> 16 & 0xFFFF)
13#define minor(dev)  ((dev) & 0xFFFF)
14#define mkdev(m, n) ((uint)((m) << 16 | (n)))
15
16// in-memory copy of an inode
17struct inode {
18  uint dev;              // Device number
19  uint inum;             // Inode number
20  int ref;               // Reference count
21  struct sleeplock lock; // protects everything below here
22  int valid;             // inode has been read from disk?
23
24  short type; // copy of disk inode
25  short major;
26  short minor;
27  short nlink;
28  uint size;
29  uint addrs[NDIRECT + 1];
30};
31
32// map major device number to device functions.
33struct devsw {
34  int (*read)(int, uint64, int);
35  int (*write)(int, uint64, int);
36};
37
38extern struct devsw devsw[];
39
40#define CONSOLE 1

Lines 1–10

struct file: one open file

What a file descriptor points to. Each successful open creates one in ftable, and pipe creates two (one per end); dup and fork make more descriptors point to the same one. The type decides which of the remaining fields mean anything:

`type`	object	fields used
`FD_NONE`	(free entry)	none
`FD_PIPE`	one end of a pipe	`pipe`
`FD_INODE`	a file or directory	`ip`, `off`
`FD_DEVICE`	a device such as the console	`ip`, `major`

readable and writable record the access mode chosen at open and are checked on every fileread and filewrite. They are char only to save space; each holds 0 or 1.

ref is protected by ftable.lock. off is protected by the inode’s lock: code reads and updates it only while holding ip->lock, which is what keeps processes that share this struct file from using the same offset twice.

Line 2

What the entry refers to. FD_NONE (0) is the value of a free entry; an anonymous enum used directly as the field’s type.

Line 3

How many file descriptors point to this entry. 0 means the entry is free.

Line 6

The pipe, for FD_PIPE files.

Line 7

The inode, for files, directories and devices. The open file holds one inode reference, dropped by iput in fileclose.

Line 8

Where the next read or write starts, for FD_INODE files. Devices and pipes have no offset.

Line 9

The device’s major number, copied from the inode at open, used to index devsw.

Lines 12–14

Packing device numbers (unused)

Helpers that pack a major and a minor device number into one value (major in the high 16 bits, minor in the low 16) and unpack them. Nothing in this version of xv6 uses them: inodes store major and minor as separate fields, and mknod passes them separately.

They do not interfere with the fields called major and minor in the structures here: a function-like macro such as major(dev) is expanded only where its name is followed by (, so f->major is left alone.

Lines 12–13

Extract the major number (bits 31–16) and the minor number (bits 15–0) from a packed device number.

Line 14

Pack major m and minor n into one uint.

Lines 16–30

struct inode: the in-memory copy of an inode

One entry of itable in kernel/fs.c. The fields fall into two groups, protected by different locks:

dev, inum, ref: which inode this entry holds and how many in-memory pointers refer to it (its reference count). Protected by itable.lock.
everything after lock: protected by lock, the per-inode sleep lock, exactly as the comment on line 21 says. valid records whether the fields below it have been read from the disk yet (ilock does that). The rest is a copy of the on-disk dinode (on-disk inode), field for field; any change to it must be written back with iupdate.

Note the difference between ref and nlink. ref counts pointers in memory (open files, current directories, lookups in progress) and is never stored on disk; nlink is the on-disk link count (nlink), the number of directory entries naming the inode.

Lines 18–19

Which disk and which inode number this entry holds.

Line 20

The number of in-memory references; the entry is free when it is 0.

Line 21

The inode’s sleeplock, taken by ilock. It may be held across disk I/O.

Line 22

1 once the fields below have been read from the disk.

Line 24

T_DIR, T_FILE or T_DEVICE (from kernel/stat.h); 0 would mean a free inode.

Lines 25–26

Device numbers, meaningful only for T_DEVICE inodes.

Line 27

The link count (nlink): directory entries that name this inode.

Line 28

The file’s size in bytes.

Line 29

The disk addresses of the first 12 data blocks, plus the indirect block in addrs[12].

Lines 32–38

devsw: from major device number to driver

A device file is an inode of type T_DEVICE whose major number selects a driver. devsw (defined in kernel/file.c) is indexed by that number; each entry holds two function pointers. Their arguments are a flag that is 1 if the address is a user virtual address, the address, and a byte count; they return the number of bytes transferred or -1. fileread and filewrite call through them for FD_DEVICE files.

The extern declaration lets every file that includes this header use the array defined once in file.c.

Lines 34–35

Pointers to the device’s read and write functions; see the block note for the arguments.

Line 40

The console's major number

The console is device 1. consoleinit installs its read and write functions in devsw[CONSOLE], and the first user program, user/init.c, creates the device file with mknod("console", CONSOLE, 0) if it does not exist, then opens it as file descriptors 0, 1 and 2.