fsal api has changed quite a bit and documentation is seriously lacking

[drieber]

Late 2023 we discovered the fsal API had changed, and when we looked at fsals that ship with ganesha we found all of them were using many of the facilities in src/include/FSAL/fsal_commonlib.h:

• fsal_start_io
• fsal_start_global_io
• fsal_complete_io
• fsal_start_fd_work
• fsal_complete_fd_work
• insert_fd_lru
• merge_share
• fsal_close_fd
• fsal_reopen_fd
• close_fsal_fd
• check_share_conflict
• check_share_conflict_and_update
• update_share_counters
• Also the fsal_obj_handle::obj_lock

Most of those functions do not have any documentation. It is really really hard to understand exactly how those APIs should be used. I cannot overemphasize enough how this hurts our nfs-ganesha adoption plans in my team at Google.

[drieber]

Is there any chance to prioritize this? As a FSAL author it is nearly impossible to figure out what to do.
Thanks!

[dang]

Most or all of those functions are doxygen documented in fsal/commonlib.c. Basically all of our API-level documentation is done via doxygen comments on the function's implementation.

[drieber]

I am mostly concerned about these:

• fsal_start_io
• fsal_start_global_io
• fsal_complete_io
• fsal_start_fd_work
• fsal_complete_fd_work
• insert_fd_lru
• Also the fsal_obj_handle::obj_lock

All fsals that ship with ganesha call most of these, so it appears to me this is definitely part of the FSAL api. It would greatly help to have a doc or comments on the header file or whatever that describes global file descriptors, and FD lru. How is this used? What is the policy? Etc.

[ffilz]

There is some in code documentation on those in commonlib.c.

I can try and find some time to improve the documentation of all of that...

[drieber]

Perhaps the most useful thing would be one or two pages on what those functions are about, and not necessarily a bunch of comments on each of the functions (although that would also be super useful).

What is this "fd lru" thing?
What is bump fd lru for?
In fact, what IS an fd?
How do I configure fd lru in ganesha config?
etc.....

Please keen in mind developers that write their own FSAL.

[ffilz]

I'm working on, and will submit tomorrow, a patch that adds more description about fsal_fd and the API with the definition of struct fsal_fd.

As to how to configure, we don't really have much suggestion for that, but I will document the mdcache parameters that are passed onto the fd_lru.

The most important ones are the FD_Limit_Percent, FD_HWMark_Percent, and FD_LWMark_Percent that govern the size of the fd_lru based on a percentage of the process RLIMIT_NOFILE (ulimit -n)