Github/littlefs
1
Fork 0
Code Actions Activity

attrs: (Re)implemented lfsr_setattr/getattr/etc

Browse Source 
These functions provide simple access to littlefs's custom attributes,
which are small pieces of user-specified metadata that can be attached
to files, dirs, root, etc:

- lfsr_getattr    - Reads an attribute
- lfsr_sizeattr   - Gets the size of an attribute
- lfsr_setattr    - Writes an attribute
- lfsr_removeattr - Removes an attribute

You may notice these functions look quite a bit different from their
previous incarnations. This is because the custom attribute API is
getting an overhaul based on feedback provided by users

The previous API had some real design flaws that interfered with
usability, but now that things have had some time to settle (6 years!),
hopefully most of the pain points are clear.

Notable changes:

- lfsr_getattr's return value is now limited by buffer size.

  The intention of the previous API, where lfsr_getattr always returns
  the attr size, even if it's larger than the buffer, was to allow users
  to find the attr size without an infinitely large buffer.

  In defense of this design, Linux's getxattr does something somewhat
  similar, returning the attr size when the buffer size equals zero.
  Though getxattr does truncate when buffer size is non-zero, which is
  probably safer.

  But, let's be honest, this multipurpose abuse of lfsr_getattr's return
  value is inconsistent with other read functions and potentially
  dangerous for users.

  I think one of the reasons for this API in Linux-land is the limited
  syscall numbers discouraging new functions, but we have no such
  limitation here! We might as well add a dedicated function for
  this: lfsr_sizeattr.

- No more padding with zeros!

  This was a cludge to get around the lack of returned size in custom
  attributes attached to files, but is inconsistent with other read
  functions, so needs to go.

  In general, inconsistencies violate user assumptions, and are usually
  a sign of a bad API.

- lfsr_setattr now takes flags.

  This gives lfsr_setattr more flexiblity in how it operates, and may
  make future extensions easier.

  lfsr_setattr currently supports two flags, which may look a bit
  familiar:

    LFS_A_CREAT     0x04  // Create an attr if it does not exist
    LFS_A_EXCL      0x08  // Fail if an attr already exists

  One long-term idea is to eventually add a simple lfsr_set function to
  make it easier to create small files, so this sort of design overlap
  between lfsr_setattr and lfsr_file_open is hopefully a good thing.

---

Code-wise, these function are really not that bad. Adding functions adds
code, but these are just small wrappers over our internal lookup/commit
functions:

           code          stack
  before: 36556           2608
  after:  37116 (+1.5%)   2608 (+0.0%)

Of course the real cost of custom attributes is how they interact with
open files, a detail which is conveniently missing for now...
This commit is contained in:
Christopher Haster
2024-08-22 00:01:29 -05:00
parent ad919f38d7
commit f539d3341c
5 changed files with 1749 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lfs.c
+127 -1
View File
@@ -9417,7 +9417,7 @@ static int lfsr_mtree_pathlookup(lfs_t *lfs, const char *path,
lfsr_mdir_t *mdir_, lfsr_tag_t *tag_,
lfsr_did_t *did_, const char **name_, lfs_size_t *name_size_) {
// setup root
lfsr_mdir_t mdir = {.mid = -1};
lfsr_mdir_t mdir = lfs->mroot;
lfsr_tag_t tag = LFSR_TAG_DIR;
lfsr_did_t did = LFSR_DID_ROOT;
@@ -11053,6 +11053,132 @@ int lfsr_dir_rewind(lfs_t *lfs, lfsr_dir_t *dir) {
/// Custom attribute stuff ///
static int lfsr_lookupattr(lfs_t *lfs, const char *path, uint8_t type,
lfsr_mdir_t *mdir_, lfsr_data_t *data_) {
// lookup our entry
lfsr_tag_t tag;
int err = lfsr_mtree_pathlookup(lfs, path,
mdir_, &tag, NULL, NULL, NULL);
if (err && err != LFS_ERR_EXIST
&& err != LFS_ERR_INVAL) {
return err;
}
// doesn't exist? note orphans don't really exist
if (!err || tag == LFSR_TAG_ORPHAN) {
return LFS_ERR_NOENT;
}
// lookup our attr
err = lfsr_mdir_lookup(lfs, mdir_, LFSR_TAG_ATTR(type),
data_);
if (err) {
if (err == LFS_ERR_NOENT) {
return LFS_ERR_NOATTR;
}
return err;
}
return 0;
}
lfs_ssize_t lfsr_getattr(lfs_t *lfs, const char *path, uint8_t type,
void *buffer, lfs_size_t size) {
// lookup our attr
lfsr_mdir_t mdir;
lfsr_data_t data;
int err = lfsr_lookupattr(lfs, path, type,
&mdir, &data);
if (err) {
return err;
}
// read the attr
return lfsr_data_read(lfs, &data, buffer, size);
}
lfs_ssize_t lfsr_sizeattr(lfs_t *lfs, const char *path, uint8_t type) {
// lookup our attr
lfsr_mdir_t mdir;
lfsr_data_t data;
int err = lfsr_lookupattr(lfs, path, type,
&mdir, &data);
if (err) {
return err;
}
// return the attr size
return lfsr_data_size(data);
}
int lfsr_setattr(lfs_t *lfs, const char *path, uint8_t type,
const void *buffer, lfs_size_t size,
uint32_t flags) {
// unknown flags?
LFS_ASSERT((flags & ~(
LFS_A_CREAT
| LFS_O_EXCL)) == 0);
// prepare our filesystem for writing
int err = lfsr_fs_mkconsistent(lfs);
if (err) {
return err;
}
// lookup our attr
lfsr_mdir_t mdir;
lfsr_data_t data;
err = lfsr_lookupattr(lfs, path, type,
&mdir, &data);
if (err && err != LFS_ERR_NOATTR) {
return err;
}
// doesn't exist?
if (!lfsr_o_iscreat(flags)
&& err == LFS_ERR_NOATTR) {
return LFS_ERR_NOATTR;
// does exist?
} else if (lfsr_o_iscreat(flags)
&& lfsr_o_isexcl(flags)
&& err != LFS_ERR_NOATTR) {
return LFS_ERR_EXIST;
}
// commit our attr
lfs_alloc_ckpoint(lfs);
return lfsr_mdir_commit(lfs, &mdir, LFSR_ATTRS(
LFSR_ATTR(
LFSR_TAG_ATTR(type), 0,
LFSR_DATA_BUF(buffer, size))));
}
int lfsr_removeattr(lfs_t *lfs, const char *path, uint8_t type) {
// prepare our filesystem for writing
int err = lfsr_fs_mkconsistent(lfs);
if (err) {
return err;
}
// lookup our attr
lfsr_mdir_t mdir;
err = lfsr_lookupattr(lfs, path, type,
&mdir, NULL);
if (err) {
return err;
}
// commit our removal
lfs_alloc_ckpoint(lfs);
return lfsr_mdir_commit(lfs, &mdir, LFSR_ATTRS(
LFSR_ATTR(
LFSR_TAG_RM | LFSR_TAG_ATTR(type), 0,
LFSR_DATA_NULL())));
}
/// File operations ///