Re: [PATCH] netfs: Update main API document

[Bagas Sanjaya]

On Tue, Apr 08, 2025 at 04:09:57PM +0100, David Howells wrote:
> + * For writeback, it is unknown how much there will be to write until the
                                             "... will be written ..."
> +   pagecache is walked, so no limit is set by the library.
> <snipped>...
> +Further, if a read from the cache fails, the library will ask the filesystem to
> +do the read instead, renegotiating and retiling the subrequests as necessary.
Read from the filesystem itself or direct read?

> +When writeback occurs, folios that are so marked will only be written to the
> +cache and not to the server.  Writeback handles mixed cache-only writes and
> +server-and-cache writes by using two streams, sending one to the cache and one
> +to the server.  The server stream will have gaps in it corresponding to those
"... and another to the server."
> +folios.
> +
> <snipped>...
> +Netfslib will pin resources on an inode for future writeback (such as pinning
> +use of an fscache cookie) when an inode is dirtied.  However, this needs
> +managing.  Firstly, a function is provided to unpin the writeback in
inode management?
> +``->write_inode()``::
>  
> <snipped>...
> +The fields generally of interest to a filesystem are::
>  
>  	struct netfs_io_request {
> +		enum netfs_io_origin	origin;
>  		struct inode		*inode;
>  		struct address_space	*mapping;
> -		struct netfs_cache_resources cache_resources;
> +		struct netfs_group	*group;
> +		struct netfs_io_stream	io_streams[];
>  		void			*netfs_priv;
> -		loff_t			start;
> -		size_t			len;
> -		loff_t			i_size;
> -		const struct netfs_request_ops *netfs_ops;
> +		void			*netfs_priv2;
> +		unsigned long long	start;
> +		unsigned long long	len;
> +		unsigned long long	i_size;
>  		unsigned int		debug_id;
> +		unsigned long		flags;
>  		...
>  	};
>  
> -The above fields are the ones the netfs can use.  They are:
> +They are:
"These fields are, in detail:"
> <snipped>...
> +The stream struct looks like::
"The stream struct is defined as::"
> +
> +	struct netfs_io_stream {
> +		unsigned char		stream_nr;
> +		bool			avail;
> +		size_t			sreq_max_len;
> +		unsigned int		sreq_max_segs;
> +		unsigned int		submit_extendable_to;
> +		...
> +	};
> +
> <snipped>...
> +The table starts with a pair of optional pointers to memory pools from which
> +requests and subrequests can be allocated.  If these are not given, netfslib
> +has default pools that it will use.  If the filesystem wraps the netfs structs
                     "... it will use instead."
> +in its own larger structs, then it will need to use its own pools.  Netfslib
> +will allocate directly from the pools.
>  
> <snipped>...
> +   This is not permitted to return an error.  In the event of failure,
> +   ``netfs_prepare_write_failed()`` must be called.
"This method is not permitted to return an error. Instead, in the event of
failure, ..."

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Attachment: signature.asc
Description: PGP signature