Contiki - User contributions [en]

(NEW) Disney Magic Kingdoms Hack and Cheats for APK Android and Ios No Survey 2023

2023-03-25T19:04:24Z

Zhikunli: Created page with "Are you looking for ways to get unlimited Disney Magic Kingdoms Magic Gems? The Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator,..."

Are you looking for ways to get unlimited Disney Magic Kingdoms Magic Gems? The Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification are here to help!

The Disney Magic Kingdoms is a free-to-play mobile game, developed by Gameloft. It is based on the Disney theme parks and allows players to build and manage their own virtual kingdom. The game is available for Android and iOS devices.

Click Here >> https://cheats.pics/064ea46

The main currency of the game is Magic Gems, which can be used to purchase items, progress levels, and more. However, these gems can be difficult to obtain. This is where the Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification come in.

These tools are designed to provide players with an unlimited number of Magic Gems. All you need to do is input your username and select the number of gems you want to generate. From there, the tool will generate the gems in no time!

The Disney Magic Kingdoms Magic Gems Generator Method and Disney Magic Kingdoms Magic Gems Generator are safe and secure to use. They are also free of cost and require no human verification. With these tools, you can get unlimited Magic Gems without having to pay anything.

The Disney Magic Kingdoms Magic Gems Hack and Disney Magic Kingdoms Magic Gems Cheats can also be used to get an unlimited amount of Magic Gems. However, these methods require some technical knowledge and should only be used by experienced players.

The Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification are the best way to get unlimited Magic Gems. They are easy to use and require no technical knowledge or human verification.

So if you're looking for ways to get unlimited Disney Magic Kingdoms Magic Gems, the Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification are the perfect tools for you! Try them out today and get unlimited Magic Gems.

(WORKING) Disney Magic Kingdoms APK Hack Latest Version 2023 New Generator Magic Gems Cheats for Free

2023-03-25T19:04:19Z

Zhikunli: Created page with "Welcome to the magical world of Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Ma..."

Welcome to the magical world of Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification. This amazing resource has been created to help you enjoy all the fun of the Disney Magic Kingdoms game without the hassle of the usual grind and expense.

The Disney Magic Kingdoms game is a great way to explore the magical world of Disney and experience the magic of all of your favorite characters. Whether you’re a fan of classic Disney characters like Mickey Mouse, Cinderella, or Snow White, or modern characters like Moana and Olaf, you can explore the world of Disney with the help of the Disney Magic Kingdoms Magic Gems Generator Method. This amazing resource has been designed to help you get all the gems you need to experience the fun and excitement of the Disney Magic Kingdoms game.

Click Here >> https://cheats.pics/064ea46

The Disney Magic Kingdoms Magic Gems Generator Method provides you with an easy way to generate gems without having to put in any hard work. All you have to do is enter your username and password and you’ll have access to all of the gems you need to make your Disney Magic Kingdoms experience more enjoyable. With a few clicks of your mouse, you can get all the gems you need to make your Disney Magic Kingdoms experience more exciting and thrilling.

The Disney Magic Kingdoms Magic Gems Hack and Disney Magic Kingdoms Magic Gems Cheats are also great tools that allow you to get more out of the game. These amazing tools provide you with amazing tips and tricks to help you complete levels more quickly and get more out of your Disney Magic Kingdoms experience. With these tools, you can quickly and easily get all the gems you need to make your Disney Magic Kingdoms experience much more enjoyable.

The Disney Magic Kingdoms Magic Gems Free and Free Disney Magic Kingdoms Magic Gems Generator 2023 are also great tools that allow you to get more out of the game. These amazing tools provide you with amazing tips and tricks to help you complete levels more quickly and get more out of your Disney Magic Kingdoms experience. With these tools, you can quickly and easily get all the gems you need to make your Disney Magic Kingdoms experience much more enjoyable.

Finally, the Disney Magic Kingdoms Magic Gems No Human Verification is an amazing tool that allows you to get all the gems you need without having to enter any personally identifying information. With this tool, you can get all the gems you need without having to worry about being scammed or being exposed to any potential malicious activities. With this tool, you can easily and securely get all the gems you need to make your Disney Magic Kingdoms experience more enjoyable.

These amazing tools are just some of the resources available to help make your Disney Magic Kingdoms experience more enjoyable. With these tools, you can quickly and easily get all the gems you need to make your Disney Magic Kingdoms experience more exciting and thrilling.

(updated mathod) Free Disney Magic Kingdoms Cheats Magic Gems Generator No Human Verification 2023

2023-03-25T19:04:18Z

Zhikunli: Created page with "If you're a fan of Disney Magic Kingdoms, then you're probably familiar with Magic Gems. They're the virtual currency that you need to purchase and upgrade your characters, bu..."

If you're a fan of Disney Magic Kingdoms, then you're probably familiar with Magic Gems. They're the virtual currency that you need to purchase and upgrade your characters, buildings, and other items.

The problem is, Magic Gems are expensive and hard to come by. That's why many players have turned to Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification to get their hands on more Magic Gems.

Click Here >> https://cheats.pics/064ea46

The Disney Magic Kingdoms Magic Gems Generator Method can be used to generate an unlimited amount of Magic Gems. All you need to do is enter the amount of Gems you want and the Generator will give you a code that you can use to purchase them.

The Disney Magic Kingdoms Magic Gems Generator is a great way to get more Magic Gems without spending a lot of money. It's also very easy to use and can be used with any device, including mobile phones and tablets.

The Disney Magic Kingdoms Magic Gems Hack is another popular option for getting more Magic Gems. It works by hacking the game's system so that you can get as many Magic Gems as you want. This can be done by entering certain codes or by downloading files from the internet.

The Disney Magic Kingdoms Magic Gems Cheats is one of the most popular cheats for the game. It allows you to get unlimited Magic Gems by entering certain codes or by downloading files from the internet.

The Disney Magic Kingdoms Magic Gems Free is a great way to get more Magic Gems without spending a lot of money. It's a website that provides free Magic Gems to players who complete tasks on the website.

The Free Disney Magic Kingdoms Magic Gems Generator 2023 is another popular way to get more Magic Gems without spending a lot of money. It's an online generator that allows you to generate an unlimited amount of Magic Gems.

The Disney Magic Kingdoms Magic Gems No Human Verification is an option for getting more Magic Gems without spending a lot of money. It allows you to generate an unlimited amount of Magic Gems without having to provide any personal information.

Whether you're looking for the Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, or Disney Magic Kingdoms Magic Gems No Human Verification, you're sure to find a great way to get more Magic Gems without spending a lot of money. With one of these methods, you can get as many Magic Gems as you want without having to spend a fortune.

(Disney Magic Kingdoms Cheats) Free Disney Magic Kingdoms Generator Working Magic Gems Generator No Human Verification

2023-03-25T19:04:14Z

Zhikunli: Created page with "Are you a fan of Disney Magic Kingdoms and want to get your hands on the coveted Magic Gems? With the help of the Disney Magic Kingdoms Magic Gems Generator Method, you can ea..."

Are you a fan of Disney Magic Kingdoms and want to get your hands on the coveted Magic Gems? With the help of the Disney Magic Kingdoms Magic Gems Generator Method, you can easily generate Magic Gems for free and without having to verify yourself.

The Disney Magic Kingdoms Magic Gems Generator is a free and easy-to-use tool that allows you to generate Magic Gems with just a few clicks. This generator is designed to work with the latest version of the game and with no human verification and no downloads required, it’s the perfect way to get the Magic Gems you need to unlock new levels and get ahead in the game.

Click Here >> https://cheats.pics/064ea46

To use the Disney Magic Kingdoms Magic Gems Generator, simply fill out the form and click the “Generate” button. Once you’ve generated the Magic Gems, you can use them in the game to purchase new levels, unlock special rewards, and even purchase exclusive items.

The Disney Magic Kingdoms Magic Gems Hack is an even easier way to get the Magic Gems you need. With the hack, you can generate an unlimited number of Magic Gems without any downloads or human verification. All you need to do is enter your username and password into the hack, and you’ll be able to generate as many Magic Gems as you want for free.

The Disney Magic Kingdoms Magic Gems Cheats is another hack that is designed to make it easier to get the Magic Gems you need. This cheat allows you to unlock levels and purchase items without having to pay a dime. All you have to do is download the cheat and enter your username and password into it.

Finally, the Disney Magic Kingdoms Magic Gems Free Generator 2023 will help you get the Magic Gems you need without spending any money. The free generator uses a special algorithm to generate Magic Gems for free, and it works with the latest version of the game. All you have to do is enter your username and password into the generator, and you can get your hands on the Magic Gems you need.

No matter which method you choose to get your hands on the Magic Gems you need, you can rest assured that you’ll be able to get the Magic Gems without having to go through any human verification or downloads. With the Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification, you’ll be able to get your hands on the Magic Gems you need in no time.

(NEW CHEATS) Disney Magic Kingdoms Free Magic Gems Generator 999,999K Magic Gems Free 2023 in 5 minutes

2023-03-25T19:04:12Z

Zhikunli: Created page with "Welcome to the ultimate guide to Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney M..."

Welcome to the ultimate guide to Disney Magic Kingdoms Magic Gems Generator Method, Disney Magic Kingdoms Magic Gems Generator, Disney Magic Kingdoms Magic Gems Hack, Disney Magic Kingdoms Magic Gems Cheats, Disney Magic Kingdoms Magic Gems Free, Free Disney Magic Kingdoms Magic Gems Generator 2023, and Disney Magic Kingdoms Magic Gems No Human Verification.

Disney Magic Kingdoms is a mobile game released by Disney Interactive and Gameloft, and it has become one of the most popular mobile games on the market. The game allows players to construct their own magical kingdom and customize it with characters, attractions, and other goodies. In order to progress in the game, players need to collect Magic Gems. Magic Gems are the premium currency in the game and they are used to buy exclusive items, upgrades, and other bonuses.

Click Here >> https://cheats.pics/064ea46

Unfortunately, Magic Gems are not easy to come by. They are quite rare and require a lot of grinding to get enough for the most powerful items and upgrades. That’s why so many players are looking for ways to get more Magic Gems without having to spend any money. Fortunately, there are several methods available to help players get more Magic Gems without having to pay real money.

One of the most popular methods to get free Magic Gems is to use a Disney Magic Kingdoms Magic Gems Generator. A Magic Gems Generator is a tool that can generate unlimited amounts of Magic Gems for free. It works by generating codes that can be redeemed in the game for Magic Gems. This method is completely free and easy to use, and it’s the most reliable way to get free Magic Gems.

Another method is to use a Disney Magic Kingdoms Magic Gems Hack. A Magic Gems Hack is a tool that can modify the game’s data so that players can get free Magic Gems. This method is not recommended, however, as it can be quite risky. There is also the possibility that using such a hack can get your account banned from the game.

The last method is to use Disney Magic Kingdoms Magic Gems Cheats. Magic Gems Cheats are programs that can be used to modify the game’s code and generate Magic Gems for free. This method is also not recommended, as it can also get your account banned from the game.

These are the three methods that players can use to get free Magic Gems without having to spend real money. If you’re looking for a safe and reliable way to get free Magic Gems, then you should definitely consider using a Disney Magic Kingdoms Magic Gems Generator. This method is completely free, easy to use, and completely safe.

If you’re looking for a way to get free Magic Gems without having to go through a verification process, then you should consider using the Free Disney Magic Kingdoms Magic Gems Generator 2023. This generator is completely free and easy to use, and it can generate unlimited amounts of Magic Gems with no human verification.

Finally, if you want to get free Magic Gems without having to worry about getting your account banned, then you should consider using the Disney Magic Kingdoms Magic Gems No Human Verification method. This method is completely safe and can generate unlimited amounts of Magic Gems without having to go through a verification process.

We hope that this guide has helped you understand the different methods available to get free Magic Gems in Disney Magic Kingdoms. Whether you choose to use a Generator, a Hack, or a Cheat, we wish you the best of luck in your quest for more Magic Gems.

(NEW) Disney Magic Kingdoms Hack Unlimited Magic Gems Generator No Jailbreak or Root (No Human Verification)

2023-03-25T19:04:07Z

Zhikunli: Created page with "Are you a fan of the Disney Magic Kingdoms game? Do you want to get your hands on free Magic Gems? Well, the wait is over! Introducing the Disney Magic Kingdoms Magic Gems Gen..."

Are you a fan of the Disney Magic Kingdoms game? Do you want to get your hands on free Magic Gems? Well, the wait is over! Introducing the Disney Magic Kingdoms Magic Gems Generator Method, the ultimate resource for getting unlimited free Magic Gems in the game.

The Disney Magic Kingdoms Magic Gems Generator Method is a powerful tool that will allow you to generate an unlimited amount of Magic Gems for the Disney Magic Kingdoms game. This Magic Gems Generator Method is designed to be easy to use, fast and reliable. With just a few clicks of your mouse, you will be able to generate as many Magic Gems as you need.

Click Here >> https://cheats.pics/064ea46

The Disney Magic Kingdoms Magic Gems Generator Method also includes a powerful hack and cheats feature. With this feature, you can easily hack the game and get unlimited Magic Gems without having to spend a dime. This is a great way to get ahead in the game without spending real money.

The Disney Magic Kingdoms Magic Gems Generator Method also gives you access to the Free Disney Magic Kingdoms Magic Gems Generator 2023. This is a great way to get free Magic Gems in the game without having to spend any money. All you need to do is register for the Free Disney Magic Kingdoms Magic Gems Generator and you can start generating free Magic Gems in the game.

Finally, the Disney Magic Kingdoms Magic Gems Generator Method also includes the No Human Verification feature. This feature allows you to generate free Magic Gems without having to confirm any personal information. This feature ensures that your personal information is kept safe and secure.

If you are looking for a way to generate free Magic Gems for the Disney Magic Kingdoms game, then the Disney Magic Kingdoms Magic Gems Generator Method is the perfect resource for you. With the powerful hack and cheats feature, the Free Disney Magic Kingdoms Magic Gems Generator 2023 and the No Human Verification feature, you can easily generate an unlimited amount of Magic Gems in the game without spending real money. Get started today and get the most out of your Disney Magic Kingdoms experience.

Contiki Coffee File System

2014-11-09T10:37:29Z

Zhikunli: /* Reference */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function. 
The Idea is based on Zane D. Purvis's Coffee filesystem example.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|850px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "Coffee filesystem" 
[https://github.com/contiki-os/contiki/wiki/Coffee-filesystem-example] - Zane D. Purvis, "Coffee filesystem example"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T10:37:12Z

Zhikunli: /* Reference */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function. 
The Idea is based on Zane D. Purvis's Coffee filesystem example.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|850px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "Coffee filesystem"
[https://github.com/contiki-os/contiki/wiki/Coffee-filesystem-example] - Zane D. Purvis, "Coffee filesystem example"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T10:36:15Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function. 
The Idea is based on Zane D. Purvis's Coffee filesystem example.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|850px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T10:35:56Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
The Idea is based on Zane D. Purvis's Coffee filesystem example.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|850px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:55:50Z

Zhikunli: /* Simulation Result */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|850px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:55:11Z

Zhikunli: /* Simulation Result */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png|600px]] 
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:43:41Z

Zhikunli: /* Memory Organization */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

File:Flowchart.png

2014-11-09T07:39:39Z

Zhikunli: Zhikunli uploaded a new version of "File:Flowchart.png"

Contiki Coffee File System

2014-11-09T07:36:02Z

Zhikunli: /* get_available_fd */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:34:00Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
/*
* Copyright (c) 2011, Swedish Institute of Computer Science.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the Institute nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* This file is part of the Contiki operating system.
*/

#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:31:08Z

Zhikunli: /* Data Structure Used In The System */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Memory Organization ===
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:30:34Z

Zhikunli: /* file */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:30:01Z

Zhikunli: /* file_desc */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:29:39Z

Zhikunli: /* file */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T07:29:26Z

Zhikunli: /* file_desc */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:59:21Z

Zhikunli: /* Reference */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

== General Issues ==
1. Use sizeof() instead strlen() in the strncpy() function. 
2. Remember to include string.h, otherwise when you compile it will generate warnings.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:55:41Z

Zhikunli: /* cfs_close */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage.[1] 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:54:33Z

Zhikunli: /* Memory Organization */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t.
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:51:38Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
/*Write message to Filesystem*/
r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
/* compare with the original message to see if the message was read
correctly, if it reads fail then it will print fail*/
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);
/*Append test */
strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
/*seek test*/
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
/*if the seek fails then the second message will not
be the same as the last message write to the file*/
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:47:43Z

Zhikunli: /* Test Result */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Simulation Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:46:09Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
Modify the code provided by Contiki. 
Open contiki-2.7/examples/sky/example-coffee.c, then rewrite the file_test function.
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>

== Test Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:41:52Z

Zhikunli: /* Test Result */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
== Test Result ==
[[File:result.png]]
We can see that Coffee File System works well.

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:40:42Z

Zhikunli: /* Coding With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
== Test Result ==
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:38:34Z

Zhikunli: /* cfs_write */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.[1]

==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:38:12Z

Zhikunli: /* cfs_read */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.[1]

==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:37:42Z

Zhikunli: /* cfs_close */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:36:15Z

Zhikunli: /* find_file */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory.

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:36:01Z

Zhikunli: /* find_file */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
If the file correspond to the name is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:35:38Z

Zhikunli: /* find_file */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>
if the file is still resides in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:33:55Z

Zhikunli: /* Data Structure Used In The System */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][1] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:33:36Z

Zhikunli: /* cfs_remove */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name). After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:32:45Z

Zhikunli: /* The CFS Programming Interface */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When an open file is no longer needed, the application should close it by using cfs_close(). By closing a file, the file system can deallocate its internal resources held for the file, and possibly commit any cached data to permanent storage. 
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read() fills buf with at most len bytes, starting from the current position in the file that is stored in the file descriptor. It returns the amount of bytes read, or -1 if an error occurs.
==== cfs_write ====
cfs_write() writes len bytes from the memory buffer buf into the file, starting from the current position in the file descriptor. The file must have been opened with the CFS_WRITE flag. It returns the amount of bytes written, or -1 if an error occurred.
==== cfs_seek ====
cfs_seek() moves the current file position to the position determined by the combination of the offset and the whence. CFS_SEEK_SET tells cfs_seek() to compute the offset from the beginning of the file, i.e., as an absolute offset. CFS_SEEK_CUR specifies that the offset should be compute relative to the current position of the file position. Similarly, CFS_SEEK_END computes the offset in relation to the end of the file, and can be used to move beyond the end if the file system implementation allows it. Negative offset values are accepted by both CFS_SEEK_CUR and CFS_SEEK_END, if the program wishes to move the file position backwards from the base that is indicated by the whence parameter. cfs_seek() returns the new absolute file position upon success, or -1 if the file pointer could not be moved to the requested position.[1]
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:29:05Z

Zhikunli: /* Code With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read read size bytes from the opened file then store the date in the buf, then return the data size reader from the file.
==== cfs_write ====

==== cfs_seek ====
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== Coding With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:28:25Z

Zhikunli: /* How To Code With Coffee API */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read read size bytes from the opened file then store the date in the buf, then return the data size reader from the file.
==== cfs_write ====

==== cfs_seek ====
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:27:11Z

Zhikunli: /* Reference */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read read size bytes from the opened file then store the date in the buf, then return the data size reader from the file.
==== cfs_write ====

==== cfs_seek ====
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== How To Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:26:58Z

Zhikunli: /* Reference */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read read size bytes from the opened file then store the date in the buf, then return the data size reader from the file.
==== cfs_write ====

==== cfs_seek ====
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== How To Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[1][https://github.com/contiki-os/contiki/wiki/File-systems] - Zane D. Purvis, "File systems"

----

[[Contiki_tutorials | Back to Contiki Tutorials]]

Edited by: Zhikun Liu

Contiki Coffee File System

2014-11-09T06:23:33Z

Zhikunli: /* The CFS Programming Interface */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
cfs_read read size bytes from the opened file then store the date in the buf, then return the data size reader from the file.
==== cfs_write ====

==== cfs_seek ====
==== cfs_remove ====
cfs_remove remove the file correspond to the name. It first find the file by find_file(name), if the file is still reside in coffee_files[COFFEE_MAX_OPEN_FILES] and the physical file is still valid then it return the pointer to that file, otherwise scan the FLSAH, and cache the file into memory. After that invoke remove_by_page to delete the file.

== How To Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[1]https://github.com/contiki-os/contiki/wiki/File-systems

Contiki Coffee File System

2014-11-09T06:12:15Z

Zhikunli: /* cfs_close */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7. Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Contiki takes care of underlying hardware implementation. Coffee file system will provide a API which is similar to normal C file operations: Open a file, read and write to it and then close it. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption. 

== You Will Learn ==

Through this tutorial you are going to understand how the Coffee file system works. And get to know how to program with the coffee file system API.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== The CFS Programming Interface ===

==== cfs_open ====
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

==== cfs_close ====
<source lang="c">
void cfs_close(int fd)
{
if (FD_VALID(fd))
{
coffee_fd_set[fd].flags = COFFEE_FD_FREE;
coffee_fd_set[fd].file->references--;
coffee_fd_set[fd].file = NULL;
}
}

#define FD_VALID(fd) ((fd)>= 0 && (fd)<COFFEE_FD_SET_SIZE && coffee_fd_set[(fd)].flags!=COFFEE_FD_FREE)
</source>
When file is no longer needed, it will close the file and release the resource. It first make sure fd is valid, then set the flag in this fd_desc to COFFEE_FD_FREE, and then decrease the reference count of that file. Finally set the file_desc point to NULL.

==== cfs_read ====
==== cfs_write ====
==== cfs_seek ====
==== cfs_remove ====

== How To Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[1]https://github.com/contiki-os/contiki/wiki/File-systems

Contiki Coffee File System

2014-11-09T06:05:52Z

Zhikunli: /* cfs_open */

Contiki Coffee File System

2014-11-09T06:04:41Z

Zhikunli: /* cfs_open */

Contiki Coffee File System

2014-11-09T06:02:27Z

Zhikunli: /* Introduction */

Contiki Coffee File System

2014-11-09T05:58:04Z

Zhikunli: /* You Will Learn */

Contiki Coffee File System

2014-11-09T05:56:00Z

Zhikunli: /* Introduction */

Contiki Coffee File System

2014-11-09T05:55:26Z

Zhikunli: /* Introduction */

== Introduction ==

The tutorial covers the main features of Coffee File System available in ContikiOS 2.7.Contiki provides a set of file systems for using various kinds of storage devices in resource-constrained systems. All of these file systems implement a subset of the Contiki File System (CFS) interface, and two of them provide the full functionality: CFS-POSIX and Coffee[1]. Coffee is used with device equipped with flash memories or EEPROM. Due to the restrained resource and affected by the environment, the data transmission will get lost sometimes, which then need to be retransmitted, applying file system in the wireless sensor node will help to make the system become more reliable by store the data in the nodes locally. Since we can store the data in the node locally then we can send multiple data via one transmission, which leads to less number of transmission, then reduce the power consumption.

== You Will Learn ==

Through this tutorial you will learn about how the Coffee file system works.

== Source Code ==

~/contiki-2.7/core/cfs/cfs-coffee.h 
~/contiki-2.7/core/cfs/cfs-coffee.c

== Coffee File System API ==

=== Data Structure Used In The System===

==== Memory Organization ====
[[File:coffee-structure.png]][2] 
Coffee File System organize the file_desc as an array and mark it as a member in the protected_mem_t
<source lang="c">
/*
* The protected memory consists of structures that should not be
* overwritten during system checkpointing because they may be used by
* the checkpointing implementation. These structures need not be
* protected if checkpointing is not used.
*/
static struct protected_mem_t {
struct file coffee_files[COFFEE_MAX_OPEN_FILES];
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
coffee_page_t next_free;
char gc_wait;
} protected_mem;
static struct file * const coffee_files = protected_mem.coffee_files;
static struct file_desc * const coffee_fd_set = protected_mem.coffee_fd_set;
static coffee_page_t * const next_free = &protected_mem.next_free;
static char * const gc_wait = &protected_mem.gc_wait;
</source>

==== file_desc ====

<source lang="c">
struct file_desc {
cfs_offset_t offset;
struct file *file; // a file pointer which point to the corresponding file.
uint8_t flags; //flag used to indicate the open mode of the file and whether the fd is free.
#if COFFEE_IO_SEMANTICS
uint8_t io_flags;
#endif
};
</source>

<source lang="c">
struct file_desc coffee_fd_set[COFFEE_FD_SET_SIZE];
</source>

[[File:Datastr.png|670px]]

==== file ====
<source lang="c">
struct file {
cfs_offset_t end;
coffee_page_t page;
coffee_page_t max_pages;
int16_t record_count;
uint8_t references;
uint8_t flags;
};
</source>
[[File:file.png|670px]]

=== get_available_fd ===

<source lang="c">
static int
get_available_fd(void)
{
int i;

for(i = 0; i < COFFEE_FD_SET_SIZE; i++) {
if(coffee_fd_set[i].flags == COFFEE_FD_FREE) {
return i;
}
}
return -1;
}
</source>

Contiki is a Linux like system, everything is a file, and the opened file is represented by the file descriptor. The get_available_fd will return the smallest available fd by check the file_desc array in an ascending order, the first one with flag == 0(COFFEE_FD_FREE) is what we want. If all the flags are set, then return -1.

=== find_file ===
<source lang="c">
static struct file *
find_file(const char *name)
{
int i;
struct file_header hdr;
coffee_page_t page;

/* First check if the file metadata is cached. */
for(i = 0; i < COFFEE_MAX_OPEN_FILES; i++) {
if(FILE_FREE(&coffee_files[i])) {
continue;
}

read_header(&hdr, coffee_files[i].page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return &coffee_files[i];
}
}

/* Scan the flash memory sequentially otherwise. */
for(page = 0; page < COFFEE_PAGE_COUNT; page = next_file(page, &hdr)) {
read_header(&hdr, page);
if(HDR_ACTIVE(hdr) && !HDR_LOG(hdr) && strcmp(name, hdr.name) == 0) {
return load_file(page, &hdr);
}
}

return NULL;
}
</source>

=== cfs_open ===
cf_open is used to open a file. If it successfully open the file then it returns the file descriptor(fd), otherwise it returns -1. 
cfs_open source code:
<source lang="c">
int
cfs_open(const char *name, int flags)
{
int fd;
struct file_desc *fdp;

fd = get_available_fd(); //find the smallest available fd, see section 4.2
if(fd < 0) {
PRINTF("Coffee: Failed to allocate a new file descriptor!\n");
return -1;
}

fdp = &coffee_fd_set[fd];
fdp->flags = 0; //set the fd to FREE

fdp->file = find_file(name); //find the file corresponding to name(not exist, In flash but not cached, cached)

/*** if there isn't any corresponding file, then try to create new file ***/
if(fdp->file == NULL) {
if((flags & (CFS_READ | CFS_WRITE)) == CFS_READ) {
return -1;
}
fdp->file = reserve(name, page_count(COFFEE_DYN_SIZE), 1, 0);
if(fdp->file == NULL) {
return -1;
}
fdp->file->end = 0; // Since it's a new created file, the end will be set to 0
}
/*** find the file,seek for the end of the file***/
else if(fdp->file->end == UNKNOWN_OFFSET) {
fdp->file->end = file_end(fdp->file->page);
}

fdp->flags |= flags;
fdp->offset = flags & CFS_APPEND ? fdp->file->end : 0; //if the flag is set to APPEND, then the offset is set to the end of the file, otherwise set to 0
fdp->file->references++; //reference count will increment

return fd;
}
</source>
[[File:flowchart.png]]

== How To Code With Coffee API ==
<source lang="c">
#include <stdio.h>
#include "contiki.h"
#include "cfs/cfs.h"
#include "cfs/cfs-coffee.h"
#include <string.h>

PROCESS(example_coffee_process, "Coffee example");
AUTOSTART_PROCESSES(&example_coffee_process);
#define FILENAME "test"
/* Formatting is needed if the storage device is in an unknown state;
e.g., when using Coffee on the storage device for the first time. */
#ifndef NEED_FORMATTING
#define NEED_FORMATTING 0
#endif

static int
file_test(const char *filename, char *msg)
{
int fd;
int r;
char message[32];
char buf[64];
strncpy(message, "First Message", sizeof(message) - 1);
message[sizeof(message) - 1] = '\0';
strcpy(buf,message);
/*First message is to test if the write will succeed*/
printf("Write Test: Will write \"%s\" to file \"%s\"\n",buf,FILENAME);

/* Obtain a file descriptor for the file, capable of handling both
reads and writes. */
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}

r = cfs_write(fd, message, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",
(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
cfs_close(fd);
printf("Write Test: Successfully wrote \"%s\" to \"%s\" wrote %d bytes\n ",message,FILENAME,r);

strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_read(fd, buf, sizeof(message));
if(r != sizeof(message)) {
printf("failed to write %d bytes to %s\n",(int)sizeof(message), FILENAME);
cfs_close(fd);
return 0;
}
printf("Read Test: Read \"%s\" from \"%s\"\n",buf, FILENAME);
cfs_close(fd);

strcpy(message,"Append Something");
fd = cfs_open(FILENAME, CFS_WRITE | CFS_APPEND | CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
r = cfs_write(fd, message, sizeof(message));
cfs_close(fd);
printf("Append Test: Successfully \"%s\" to \"%s\" \n ",message,FILENAME);
strcpy(buf,"fail");
fd = cfs_open(FILENAME, CFS_READ);
if(fd < 0) {
printf("failed to open %s\n", FILENAME);
return 0;
}
cfs_read(fd,buf,sizeof(message));
printf("Read First Part \"%s\"\n",buf);
if(cfs_seek(fd, sizeof(message), CFS_SEEK_SET) == -1) {
printf("seek failed\n");
cfs_close(fd);
return 0;
}
//cfs_seek(fd, sizeof(message), CFS_SEEK_SET);
cfs_read(fd,buf,sizeof(message));
printf("Read Second Part: \"%s\"\n",buf);
cfs_close(fd);
/* Release the internal resources held by Coffee for
the file descriptor. */
cfs_remove(FILENAME);
fd = cfs_open(FILENAME, CFS_READ);
if(fd != -1) {
printf("ERROR: could read from memory\n");
return 0;
}
printf("Successfully removed file\n");
return 1;
}

PROCESS_THREAD(example_coffee_process, ev, data)
{
PROCESS_BEGIN();

#if NEED_FORMATTING
cfs_coffee_format();
#endif

/* Ensure that we will be working with a new file. */
cfs_remove(FILENAME);

if(file_test(FILENAME, "The first test") == 0) {
printf("file test 1 failed\n");
}
printf("test succeed\n");

PROCESS_END();
}

</source>
[[File:result.png]]

==Reference ==
[1]https://github.com/contiki-os/contiki/wiki/File-systems