Re: [PATCH] libpoke,ios: Move IOS dev comments to public header libpoke

[Jose E. Marchesi]

This is OK for master.

If both interfaces ever diverge, we can document the differences in the
ios-dev.h internal header.

Thanks!


> 2022-01-14  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>
>       * libpoke/ios-dev.h (struct ios_dev_if): Move comments to
>       libpoke.h.
>       * libpoke/libpoke.h (struct ios_iod_if): Add comments moved
>       from ios-dev.h
> ---
>  ChangeLog         |  7 +++++++
>  libpoke/ios-dev.h | 48 ++++-------------------------------------------
>  libpoke/libpoke.h | 48 +++++++++++++++++++++++++++++++++++++++++++----
>  3 files changed, 55 insertions(+), 48 deletions(-)
>
> diff --git a/ChangeLog b/ChangeLog
> index d9d122ed..0ad25e9a 100644
> --- a/ChangeLog
> +++ b/ChangeLog
> @@ -1,3 +1,10 @@
> +2022-01-14  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
> +
> +     * libpoke/ios-dev.h (struct ios_dev_if): Move comments to
> +     libpoke.h.
> +     * libpoke/libpoke.h (struct ios_iod_if): Add comments moved
> +     from ios-dev.h
> +
>  2022-01-14  Mohammad-Reza Nabipoor  <mnabipoor@gnu.org>
>  
>       * testsuite/lib/poke.exp (tests_pattern): New variable.
> diff --git a/libpoke/ios-dev.h b/libpoke/ios-dev.h
> index 4c154d78..3be1c295 100644
> --- a/libpoke/ios-dev.h
> +++ b/libpoke/ios-dev.h
> @@ -47,62 +47,22 @@ typedef uint64_t ios_dev_off;
>  #define IOD_EINVAL -6 /* Invalid argument.  */
>  
>  /* Each IO backend should implement a device interface, by filling an
> -   instance of the struct defined below.  */
> +   instance of the struct defined below.
> +
> +   See the pk_iod_if struct in libpoke.h for an explanation of the
> +   interface functions.  */
>  
>  struct ios_dev_if
>  {
> -  /* Return the name of this device interface. Cannot return NULL. */
> -
>    const char *(*get_if_name) ();
> -
> -  /* Determine whether the provided HANDLER is recognized as a valid
> -     device spec by this backend, and if so, return its normalized
> -     form (caller will free).  In case of error, return NULL.  This function
> -     sets the ERROR to error code or to IOD_OK.  */
> -
>    char * (*handler_normalize) (const char *handler, uint64_t flags, int* 
> error);
> -
> -  /* Open a device using the provided HANDLER.  Return the opened
> -     device, or NULL in case of errors.  Set the ERROR to error code or to
> -     IOD_OK.  Note that this function assumes that HANDLER is recognized as a
> -     handler by the backend.  DATA is the `data' pointer below, intended to 
> be
> -     used as an IOD-specific payload specified by the author of IOD.  */
> -
>    void * (*open) (const char *handler, uint64_t flags, int *error, void 
> *data);
> -
> -  /* Close the given device.  Return the error code if there was an error
> -     during the operation, IOD_OK otherwise.  */
> -
>    int (*close) (void *dev);
> -
> -  /* Read a small byte buffer from the given device at the given byte offset.
> -     Return 0 on success, or IOD_EOF on error, including on short reads.  */
> -
>    int (*pread) (void *dev, void *buf, size_t count, ios_dev_off offset);
> -
> -  /* Write a small byte buffer to the given device at the given byte offset.
> -     Return 0 on success, or IOD_EOF on error, including short writes.  */
> -
>    int (*pwrite) (void *dev, const void *buf, size_t count, ios_dev_off 
> offset);
> -
> -  /* Return the flags of the device, as it was opened.  */
> -
>    uint64_t (*get_flags) (void *dev);
> -
> -  /* Return the size of the device, in bytes.  */
> -
>    ios_dev_off (*size) (void *dev);
> -
> -  /* If called on a in-stream, free the buffer before OFFSET.  If called on
> -     an out-stream, flush the data till OFFSET and free the buffer before
> -     OFFSET.  Otherwise, do not do anything.  Return IOS_OK in success and
> -     an error code on failure.  */
> -
>    int (*flush) (void *dev, ios_dev_off offset);
> -
> -  /* IOD-specific data payload that will be passed to OPEN function.  If not
> -     used, it should be NULL.  */
> -
>    void *data;
>  };
>  
> diff --git a/libpoke/libpoke.h b/libpoke/libpoke.h
> index 0bc3c0bd..b88b047f 100644
> --- a/libpoke/libpoke.h
> +++ b/libpoke/libpoke.h
> @@ -1126,20 +1126,60 @@ typedef uint64_t pk_iod_off;
>  #define PK_IOD_EOF    -5
>  #define PK_IOD_EINVAL -6
>  
> -/* See the ios_dev_if struct in ios-dev.h for an explanation of the
> -   interface functions.  */
> -
>  struct pk_iod_if
>  {
> +  /* Return the name of this device interface. Cannot return NULL. */
> +
>    const char *(*get_if_name) ();
> -  char *(*handler_normalize) (const char *handler, uint64_t flags, int 
> *error);
> +
> +  /* Determine whether the provided HANDLER is recognized as a valid
> +     device spec by this backend, and if so, return its normalized
> +     form (caller will free).  In case of error, return NULL.  This function
> +     sets the ERROR to error code or to IOD_OK.  */
> +
> +  char * (*handler_normalize) (const char *handler, uint64_t flags, int* 
> error);
> +
> +  /* Open a device using the provided HANDLER.  Return the opened
> +     device, or NULL in case of errors.  Set the ERROR to error code or to
> +     IOD_OK.  Note that this function assumes that HANDLER is recognized as a
> +     handler by the backend.  DATA is the `data' pointer below, intended to 
> be
> +     used as an IOD-specific payload specified by the author of IOD.  */
> +
>    void * (*open) (const char *handler, uint64_t flags, int *error, void 
> *data);
> +
> +  /* Close the given device.  Return the error code if there was an error
> +     during the operation, IOD_OK otherwise.  */
> +
>    int (*close) (void *dev);
> +
> +  /* Read a small byte buffer from the given device at the given byte offset.
> +     Return 0 on success, or IOD_EOF on error, including on short reads.  */
> +
>    int (*pread) (void *dev, void *buf, size_t count, pk_iod_off offset);
> +
> +  /* Write a small byte buffer to the given device at the given byte offset.
> +     Return 0 on success, or IOD_EOF on error, including short writes.  */
> +
>    int (*pwrite) (void *dev, const void *buf, size_t count, pk_iod_off 
> offset);
> +
> +  /* Return the flags of the device, as it was opened.  */
> +
>    uint64_t (*get_flags) (void *dev);
> +
> +  /* Return the size of the device, in bytes.  */
> +
>    pk_iod_off (*size) (void *dev);
> +
> +  /* If called on a in-stream, free the buffer before OFFSET.  If called on
> +     an out-stream, flush the data till OFFSET and free the buffer before
> +     OFFSET.  Otherwise, do not do anything.  Return IOS_OK in success and
> +     an error code on failure.  */
> +
>    int (*flush) (void *dev, pk_iod_off offset);
> +
> +  /* IOD-specific data payload that will be passed to OPEN function.  If not
> +     used, it should be NULL.  */
> +
>    void *data;
>  };