contiki学习笔记（九）文件系统CFS

十二、contiki文件系统接口

Contiki文件系统接口(CFS)定义了一个用于读取目录和读写文件的抽象API。

Files
file	cfs-coffee.h
 	
Header for the Coffee file system.

file	cfs.h
 	
CFS header file.

Defines

#define	CFS_COFFEE_IO_FLASH_AWARE 0x1
 	Instruct Coffee that the access pattern to this file is adapted to 
 	flash I/O semantics by design, and Coffee should therefore 
 	not invoke its own micro logs when file modifications occur. 
 	通知Coffee，这个文件的访问模式是经过设计适应于flash I/O语义的，
 	因此，当文件修改发生时，Coffee不应该调用它自己的微日志。
#define	CFS_COFFEE_IO_FIRM_SIZE 0x2
 	Instruct Coffee not to attempt to extend the file when there is an 
 	attempt to write past the reserved file size. 
 	当试图写入超过保留的文件大小时，指示Coffee不要试图扩展文件。
#define	CFS_READ   1
 	Specify that cfs_open() should open a file for reading. 
 	指定cfs_open()应该打开一个文件进行读取。
#define	CFS_WRITE   2
 	Specify that cfs_open() should open a file for writing. 
 	指定cfs_open()应该打开一个文件进行写入。
#define	CFS_APPEND   4
 	Specify that cfs_open() should append written data to the file rather 
 	指定cfs_open()应该将写入的数据附加到文件中than overwriting it. 
#define	CFS_SEEK_SET   0
 	Specify that cfs_seek() should compute the offset from the 
 	beginning of the file. 
 	指定cfs_seek()应该计算从文件开头开始的偏移量。
#define	CFS_SEEK_CUR   1
 	Specify that cfs_seek() should compute the offset 
 	from the current position of the file pointer. 
 	指定cfs_seek()应该计算文件指针当前位置的偏移量。
#define	CFS_SEEK_END   2
 	Specify that cfs_seek() should compute the offset 
 	from the end of the file. 
 	指定cfs_seek()应该计算从文件末尾开始的偏移量。

Functions

CCIF int	cfs_open (const char *name, int flags)
 	Open a file. 
CCIF void	cfs_close (int fd)
 	Close an open file. 
CCIF int	cfs_read (int fd, void *buf, unsigned int len)
 	Read data from an open file. 
CCIF int	cfs_write (int fd, const void *buf, unsigned int len)
 	Write data to an open file. 
CCIF cfs_offset_t	cfs_seek (int fd, cfs_offset_t offset, int whence)
 	Seek to a specified position in an open file. 
 	在打开的文件中查找指定的位置。
CCIF int	cfs_remove (const char *name)
 	Remove a file. 
CCIF int	cfs_opendir (struct cfs_dir *dirp, const char *name)
 	Open a directory for reading directory entries. 
 	打开一个目录来读取目录条目。
CCIF int	cfs_readdir (struct cfs_dir *dirp, struct cfs_dirent *dirent)
 	Read a directory entry. 
 	读取目录项。
CCIF void	cfs_closedir (struct cfs_dir *dirp)
 	Close a directory opened with cfs_opendir(). 
 	关闭用cfs opendir()打开的目录。
	
Functions called from application programs
从应用程序调用的函数
int	cfs_coffee_reserve (const char *name, cfs_offset_t size)
 	Reserve space for a file. 
 	为文件保留空间。
int	cfs_coffee_configure_log (const char *file, 
	unsigned log_size, unsigned log_entry_size)
 	Configure the on-demand log file. 
 	配置随需应变日志文件。
int	cfs_coffee_set_io_semantics (int fd, unsigned flags)
 	Set the I/O semantics for accessing a file. 
 	设置访问文件的I/O语义。
int	cfs_coffee_format (void)
 	Format the storage area assigned to Coffee. 
 	格式化分配给Coffee的存储区域。
void *	cfs_coffee_get_protected_mem (unsigned *size)
 	Points out a memory region that may not be altered
 	 during checkpointing operations that use the file system. 
 	 指出一个可能不会被改变的记忆区域
		在使用文件系统的检查点操作期间。

Detailed Description
Contiki文件系统接口(CFS)定义了一个用于读取目录和读写文件的抽象API。
CFS API有意保持简单。CFS API是模仿POSIX文件API建模的，并且稍微简化了一些。

Define Documentation

#define CFS_APPEND 4
指定cfs_open()应该将写入的数据附加到文件中，而不是覆盖它。
由cfs_open().调用

该常量向cfs_open()表明，应该打开用于写入的文件将获得附加到文件末尾的写入数据。默认行为(没有CFS_APPEND)是用新数据覆盖文件。

#define CFS_COFFEE_IO_FIRM_SIZE 0x2
当试图写入超过保留的文件大小时，指示Coffee不要试图扩展文件。

当文件有严格的大小限制时，就需要一种保护措施来防止写超过这个限制。

#define CFS_COFFEE_IO_FLASH_AWARE 0x1
通知Coffee，这个文件的访问模式是经过设计适应于flash I/O语义的，
因此，当文件修改发生时，Coffee不应该调用它自己的微日志。
这种语义I/O设置在实现基于咖啡的闪存算法时非常有用。

#define CFS_READ 1
指定cfs_open()应该打开一个文件进行读取。
这个常量向cfs_open()表明应该打开一个文件以供读取。
如果文件被打开用于写，那么应该使用CFS_WRITE，
而CFS_READ + CFS_WRITE表示文件被打开用于读和写。
由cfs_open(), and cfs_read().调用

#define CFS_SEEK_CUR 1
指定cfs_seek()应该计算文件指针当前位置的偏移量。
由cfs_seek(), and elfloader_arch_relocate().调用

#define CFS_SEEK_END 2
指定cfs_seek()应该计算从文件末尾开始的偏移量。
由 cfs_seek().调用

#define CFS_SEEK_SET 0
指定cfs_seek()应该计算从文件开头开始的偏移量。
由cfs_seek(), elfloader_arch_relocate(), 
and elfloader_arch_write_rom().调用

#define CFS_WRITE 2
指定cfs_open()应该打开一个文件进行写入。
个常量向cfs_open()表明应该打开一个文件进行写入。
如果文件被打开用于读取，那么应该使用CFS_READ，
而CFS_READ + CFS_WRITE表示文件同时被打开用于读取和写入。
由cfs_open(), and cfs_write().调用

Function Documentation

CCIF void cfs_close	(	int	fd	)	
Close an open file.
此函数关闭先前使用cfs_open()打开的文件。

Parameters:
fd 打开文件的文件描述符。

CCIF void cfs_closedir	(	struct cfs_dir *	dirp	)	
关闭用cfs opendir()打开的目录。

Parameters:
dirp 指向结构cfs_dir的指针，该结构已被cfs_opendir()打开。

int cfs_coffee_configure_log	(	const char *	file,
unsigned	log_size,
unsigned	log_entry_size 
)		
配置随需应变日志文件。

Parameters:
file 文件名
log_size 总的日志大小
log_entry_size 日志条目大小。
Returns:
0代表成功，-1代表失败。
当文件数据第一次被修改时，Coffee为文件创建一个微日志。微日志存储了一个修改表，其参数——日志大小和日志条目大小——可以通过cfs_coffee_configure_log函数进行修改。

int cfs_coffee_format	(	void		)	
格式化分配给咖啡的存储区域。
咖啡通过将所有位设置为0来格式化底层存储。格式化必须在第一次使用咖啡之前完成。

Returns:
0代表成功，-1代表失败。

void* cfs_coffee_get_protected_mem	(	unsigned *	size	)	
指出在使用文件系统的检查点操作期间可能不会更改的内存区域。

Parameters:
size
Returns:
指向受保护内存的指针。
此函数返回受保护的内存指针，并将其大小写入给定的参数。主要用于sensornet检查点，以保护基于cff的检查点操作期间的咖啡状态。

i

nt cfs_coffee_reserve	(	const char *	name,
cfs_offset_t	size 
)		
为文件保留空间。
Coffee对文件使用顺序的页面结构。顺序结构可以保留一定的大小。
如果一个文件在第一次打开时没有被保留，那么它将被分配一个默认大小。

Parameters:
name 文件名
size 文件大小.
Returns:
0代表成功，-1代表失败。

int cfs_coffee_set_io_semantics	(	int	fd,
unsigned	flags 
)		
设置访问文件的I/O语义。

Parameters:
fd 用来访问文件的文件描述符。
flags 一个标志的位向量。
Coffee用于各种存储类型，默认的I/O文件语义对于某个文件的访问模式可能不是最优的。因此，这个函数允许程序员在通过特定文件描述符访问的文件上切换/O语义。

CCIF int cfs_open	(	const char *	name,
int	flags 
)		
Open a file.

Parameters:
name 文件名.
flags CFS_READ, or CFS_WRITE/CFS_APPEND, or both.
Returns:
一个文件描述符，如果文件可以打开，或者-1如果文件不能打开。
这个函数打开一个文件并返回打开文件的文件描述符。如果文件不能打开，函数返回-1。该函数可以打开一个文件进行读取或写入，或者两者同时进行。

打开的文件必须使用cfs_close()关闭。

CCIF int cfs_opendir	(	struct cfs_dir *	dirp,
const char *	name 
)		
打开一个目录来读取目录条目。

Parameters:
dirp 指向由函数填充的结构cfs_dir的指针。
name 目录的名称。
Returns:
如果无法打开目录，则为0或-1。

CCIF int cfs_read	(	int	fd,
void *	buf,
unsigned int	len 
)		
Read data from an open file.

Parameters:
fd 打开文件的文件描述符。
buf 从文件中读取数据的缓冲区。
len 应该读取的字节数。
Returns:
从文件中实际读取的字节数。
此函数将数据从打开的文件读入缓冲区。文件必须首先使用cfs_open()和CFS_READ标志打开。

CCIF int cfs_readdir	(	struct cfs_dir *	dirp,
struct cfs_dirent *	dirent 
)		
读取目录项。

Parameters:
dirp 指向结构cfs_dir的指针，该结构已被cfs_opendir()打开。
dirent 指向由cfs_readdir()填充的结构cfs_dirent的指针
Return values:
如果读取了目录项，则为0。
-1如果没有更多的目录条目可以读取。

CCIF int cfs_remove	(	const char *	name	)	
Remove a file.

Parameters:
name 文件名
Return values:
0 如果文件被删除。
Returns:
-1 如果文件无法删除或不存在。

CCIF cfs_offset_t cfs_seek	(	int	fd,
cfs_offset_t	offset,
int	whence 
)		
在打开的文件中查找指定的位置。
由elfloader_arch_relocate(), and elfloader_arch_write_rom().调用

Parameters:
fd 打开文件的文件描述符。
offset 文件中相对或绝对的位置。
whence 确定如何解释偏移参数。
Returns:
文件中的新位置，或者(cfs_offset_t)-1(如果查找失败)。
此函数将文件位置移动到文件中的指定位置。从文件中读取或写入文件的下一个字节将位于由偏移参数和where参数组合决定的位置。

CCIF int cfs_write	(	int	fd,
const void *	buf,
unsigned int	len 
)		
Write data to an open file.

Parameters:
fd elfloader_arch_relocate(), and elfloader_arch_write_rom().
buf 将数据写入文件的缓冲区。
len 应该写入的字节数。
Returns:
实际写入文件的字节数。
此函数将数据从内存缓冲区读写到打开的文件。文件必须使用cfs_open()和CFS_WRITE标志打开。