[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] libpoke,ios: Move IOS dev comments to public header libpoke
From: |
Jose E. Marchesi |
Subject: |
Re: [PATCH] libpoke,ios: Move IOS dev comments to public header libpoke |
Date: |
Thu, 13 Jan 2022 23:50:25 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
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;
> };