From 11e22ba171625ec32a82deb9b41a6e8347fe17ff Mon Sep 17 00:00:00 2001 From: frank zago Date: Sat, 20 Sep 2014 10:22:23 -0500 Subject: [PATCH] LU-5657 man: manpages for Lustre HSM user API Added 2 man pages describing the following HSM user API functions: llapi_hsm_action_begin llapi_hsm_action_end llapi_hsm_action_get_dfid llapi_hsm_action_get_fd llapi_hsm_action_progress llapi_hsm_copytool_get_fd llapi_hsm_copytool_recv llapi_hsm_copytool_register llapi_hsm_copytool_unregister Change-Id: Icd9c738c7b5287b5cfac2db4b697acb5a9e758ba Signed-off-by: frank zago Reviewed-on: http://review.whamcloud.com/12061 Reviewed-by: Henri Doreau Tested-by: Jenkins Reviewed-by: John L. Hammond Tested-by: Maloo Reviewed-by: Oleg Drokin --- lustre/doc/Makefile.am | 14 ++- lustre/doc/llapi_hsm_action_begin.rst | 109 +++++++++++++++++++++++ lustre/doc/llapi_hsm_action_end.3 | 1 + lustre/doc/llapi_hsm_action_get_dfid.3 | 1 + lustre/doc/llapi_hsm_action_get_fd.3 | 1 + lustre/doc/llapi_hsm_action_progress.3 | 1 + lustre/doc/llapi_hsm_copytool_get_fd.3 | 1 + lustre/doc/llapi_hsm_copytool_recv.3 | 1 + lustre/doc/llapi_hsm_copytool_register.rst | 135 +++++++++++++++++++++++++++++ lustre/doc/llapi_hsm_copytool_unregister.3 | 1 + lustre/doc/lustreapi.rst | 38 +++++++- 11 files changed, 298 insertions(+), 5 deletions(-) create mode 100644 lustre/doc/llapi_hsm_action_begin.rst create mode 100644 lustre/doc/llapi_hsm_action_end.3 create mode 100644 lustre/doc/llapi_hsm_action_get_dfid.3 create mode 100644 lustre/doc/llapi_hsm_action_get_fd.3 create mode 100644 lustre/doc/llapi_hsm_action_progress.3 create mode 100644 lustre/doc/llapi_hsm_copytool_get_fd.3 create mode 100644 lustre/doc/llapi_hsm_copytool_recv.3 create mode 100644 lustre/doc/llapi_hsm_copytool_register.rst create mode 100644 lustre/doc/llapi_hsm_copytool_unregister.3 diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 4925ceb..eb98b01 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -52,9 +52,13 @@ MANFILES = lustre.7 lfs.1 mount.lustre.8 lctl.8 lnetctl.8 \ llapi_layout_pattern_get.3 llapi_layout_pattern_set.3 \ llapi_layout_pool_name_get.3 llapi_layout_pool_name_set.3 \ llapi_layout_stripe_count_get.3 llapi_layout_stripe_count_set.3 \ - llapi_layout_stripe_size_get.3 llapi_layout_stripe_size_set.3 \ + llapi_layout_stripe_size_get.3 llapi_layout_stripe_size_set.3 \ llapi_path2fid.3 llapi_group_lock.3 llapi_group_unlock.3 \ - ll_decode_filter_fid.8 llapi_path2parent.3 llapi_fd2parent.3 + ll_decode_filter_fid.8 llapi_path2parent.3 llapi_fd2parent.3 \ + llapi_hsm_copytool_unregister.3 llapi_hsm_copytool_get_fd.3 \ + llapi_hsm_copytool_recv.3 llapi_hsm_action_end.3 \ + llapi_hsm_action_progress.3 llapi_hsm_action_get_dfid.3 \ + llapi_hsm_action_get_fd.3 SERVER_MANFILES = mkfs.lustre.8 tunefs.lustre.8 @@ -67,8 +71,10 @@ endif # Generated manpages with their sources in ReST. Generated files are # not part of the dist target; they may or may not have been # generated (see --disable-manpages option). -RST_MANFILES = lustreapi.rst -GEN_MANFILES = lustreapi.7 +RST_MANFILES = lustreapi.rst llapi_hsm_action_begin.rst \ + llapi_hsm_copytool_register.rst +GEN_MANFILES = lustreapi.7 llapi_hsm_action_begin.3 \ + llapi_hsm_copytool_register.3 if UTILS if MANPAGES diff --git a/lustre/doc/llapi_hsm_action_begin.rst b/lustre/doc/llapi_hsm_action_begin.rst new file mode 100644 index 0000000..fc6b740 --- /dev/null +++ b/lustre/doc/llapi_hsm_action_begin.rst @@ -0,0 +1,109 @@ +====================== +llapi_hsm_action_begin +====================== + +------------------------------ +Lustre API copytool management +------------------------------ + +:Author: Frank Zago +:Date: 2014-09-24 +:Manual section: 3 +:Manual group: Lustre HSM User API + + +SYNOPSIS +======== + +**#include ** + +**int llapi_hsm_action_begin(struct hsm_copyaction_private \*\***\ phcp\ **, +const struct hsm_copytool_private \***\ ct\ **, const struct +hsm_action_item \***\ hai\ **, int** restore_mdt_index\ **, int** +restore_open_flags\ **, bool** is_error\ **)** + +**int llapi_hsm_action_end(struct hsm_copyaction_private \*\***\ phcp\ **, +const struct hsm_extent \***\ he\ **, int** hp_flags\ **, int** errval\ **)** + +**int llapi_hsm_action_progress(struct hsm_copyaction_private \***\ hcp\ **, +const struct hsm_extent \***\ he\ **, __u64** total\ **, int** hp_flags\ **)** + +**int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private \***\ hcp\ **, +lustre_fid \***\ fid\ **)** + +**int llapi_hsm_action_get_fd(const struct hsm_copyaction_private \***\ hcp\ **)** + + +DESCRIPTION +=========== + +When a copytool is ready to process an HSM action received through +**llapi_hsm_copytool_recv**\ (), it must first call +**llapi_hsm_action_begin**\ () to initialize the internal action +state, stored in *phcp*. *ct* is the opaque copytools handle +previously returned by **llapi_hsm_copytool_register**\ (). *hai* is +the request. *restore_mdt_index* and *restore_open_flags* are only +used for an **HSMA_RESTORE** type of request. *restore_mdt_index* is +the MDT index on which to create the restored file, or -1 for +default. If the copytool does not intend to process the request, it +should set *is_error* to **true**, and then call +**llapi_hsm_action_end**\ (). + +While performing a copy (i.e. the HSM request is either +**HSMA_ARCHIVE** or **HSMA_RESTORE**), the copytool can inform Lustre +of the progress of the operation with **llapi_hsm_action_progress**\ +(). *he* is the interval (*offset*, *length*) of the data copied. Each +interval must be unique; i.e. there must not be any overlap. *length* +is the total length that is expected to be transfered. *hp_flags* +should be 0. The progress can be checked on any Lustre client by +calling **llapi_hsm_current_action**\ (), or by using **lfs +hsm_action**. + +Once the HSM request has been performed, the destination file must be +closed, and **llapi_hsm_action_end**\ () must be called to free-up the +allocated ressources and signal Lustre that the file is now available +to consumers. *errval* is set to 0 on success. On error, it must be an +errno, and hp_flags can be set to **HP_FLAG_RETRY** if the request is +retryable, 0 otherwise. *he* is the interval (*offset*, *length*) of +the data copied. It can be the *hai_extent* of the HSM request. + +For a restore operation, a volatile file, invisible to ls, is +created. **llapi_hsm_action_get_fd**\ () will return a file descriptor +to it. It is the responsibility of the copytool to close the returned +file descriptor when the data transfer is +done. **llapi_hsm_action_get_dfid**\ () will return the FID of the volatile +file, which can then be used with **llapi_open_by_fid**\ () to open +the file in a different process, or on a different node. + +**llapi_hsm_action_get_fd**\ () and **llapi_hsm_action_get_dfid**\ () +can be called for an archive operation too. The returned file +descriptor and the FID are from the file to be archived. + + +RETURN VALUE +============ + +**llapi_hsm_action_get_fd**\ () returns a file descriptor on +success. The other functions return 0 on success. All functions return +a negative errno on failure. + + +ERRORS +====== + +The negative errno can be, but is not limited to: + +**-EINVAL** An invalid value was passed, the copytool is not + registered, ... + +**-ENOMEM** Not enough memory to allocate a resource. + + +SEE ALSO +======== + +**llapi_hsm_copytool_register**\ (3), **llapi_hsm_copytool_recv**\ (3), +**lustreapi**\ (7), **lfs**\ (1) + +See *lhsmtool_posix.c* in the Lustre sources for a use case of this +API. diff --git a/lustre/doc/llapi_hsm_action_end.3 b/lustre/doc/llapi_hsm_action_end.3 new file mode 100644 index 0000000..940e387 --- /dev/null +++ b/lustre/doc/llapi_hsm_action_end.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_action_begin.3 diff --git a/lustre/doc/llapi_hsm_action_get_dfid.3 b/lustre/doc/llapi_hsm_action_get_dfid.3 new file mode 100644 index 0000000..940e387 --- /dev/null +++ b/lustre/doc/llapi_hsm_action_get_dfid.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_action_begin.3 diff --git a/lustre/doc/llapi_hsm_action_get_fd.3 b/lustre/doc/llapi_hsm_action_get_fd.3 new file mode 100644 index 0000000..940e387 --- /dev/null +++ b/lustre/doc/llapi_hsm_action_get_fd.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_action_begin.3 diff --git a/lustre/doc/llapi_hsm_action_progress.3 b/lustre/doc/llapi_hsm_action_progress.3 new file mode 100644 index 0000000..940e387 --- /dev/null +++ b/lustre/doc/llapi_hsm_action_progress.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_action_begin.3 diff --git a/lustre/doc/llapi_hsm_copytool_get_fd.3 b/lustre/doc/llapi_hsm_copytool_get_fd.3 new file mode 100644 index 0000000..b18b515 --- /dev/null +++ b/lustre/doc/llapi_hsm_copytool_get_fd.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_copytool_register.3 diff --git a/lustre/doc/llapi_hsm_copytool_recv.3 b/lustre/doc/llapi_hsm_copytool_recv.3 new file mode 100644 index 0000000..b18b515 --- /dev/null +++ b/lustre/doc/llapi_hsm_copytool_recv.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_copytool_register.3 diff --git a/lustre/doc/llapi_hsm_copytool_register.rst b/lustre/doc/llapi_hsm_copytool_register.rst new file mode 100644 index 0000000..cc75566 --- /dev/null +++ b/lustre/doc/llapi_hsm_copytool_register.rst @@ -0,0 +1,135 @@ +=========================== +llapi_hsm_copytool_register +=========================== + +------------------------------ +Lustre API copytool management +------------------------------ + +:Author: Frank Zago +:Date: 2014-09-24 +:Manual section: 3 +:Manual group: Lustre HSM User API + + +SYNOPSIS +======== + +**#include ** + +**int llapi_hsm_copytool_register(struct hsm_copytool_private \*\***\ priv\ **, +const char \***\ mnt\ **, int** archive_count\ **, int \***\ archives\ **, +int** rfd_flags\ **)** + +**int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\***\ priv +**)** + +**int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \***\ ct\ **)** + +**int llapi_hsm_copytool_recv(struct hsm_copytool_private \***\ priv\ **, +**struct hsm_action_list \*\***\ hal\ **, int \***\ msgsize\ **)** + +**struct hsm_action_item \*hai_first(struct hsm_action_list \***\ hal\ **)** + +**struct hsm_action_item \*hai_next(struct hsm_action_item \***\ hai\ **)** + + +DESCRIPTION +=========== + +To receive HSM requests from a Lustre filesystem, a copytool +application must register with Lustre by calling +**llapi_hsm_copytool_register**\ (). The mountpoint of the Lustre +filesystem to monitor is indicated by *mnt*. *archives* is an array +with up to 32 elements indicating which archive IDs to register +for. Each element is a number from 1 to 32. *archive_count* is the +number of valid elements in the *archive* array. If an element in +*archives* is 0, or if *archive_count* is 0, then all archives will be +monitored. *rfd_flags* determines whether **llapi_hsm_copytool_recv** +will be blocking, with 0, or non-blocking, with O_NONBLOCK. + +**llapi_hsm_copytool_register** returns *priv*, an opaque +pointer that must be used with the other functions. + +**llapi_hsm_copytool_unregister** unregisters a copytool. *priv* is +the opaque handle returned by **llapi_hsm_copytool_register**. + +**llapi_hsm_copytool_get_fd** returns the file descriptor used by the +library to communicate with the kernel. This descriptor is only +intended to be used with **select(2)** or **poll(2)**. *rfd_flags* +should have been set to O_NONBLOCK. + +To receive the requests, the application has to call +**llapi_hsm_copytool_recv**. When it returns 0, a message is available +in *hal*, and its size in bytes is returned in *msgsize*. *hal* points +to a buffer allocated by the Lustre library. It contains one or more +HSM requests. This buffer is valid until the next call to +**llapi_hsm_copytool_recv**. + +*hal* is composed of a header of type *struct hsm_action_list* +followed by one or several HSM requests of type *struct +hsm_action_item*:: + + struct hsm_action_list { + __u32 hal_version; + __u32 hal_count; /* number of hai's to follow */ + __u64 hal_compound_id; /* returned by coordinator */ + __u64 hal_flags; + __u32 hal_archive_id; /* which archive backend */ + __u32 padding1; + char hal_fsname[0]; /* null-terminated name of filesystem */ + }; + + struct hsm_action_item { + __u32 hai_len; /* valid size of this struct */ + __u32 hai_action; /* hsm_copytool_action, but use known size */ + lustre_fid hai_fid; /* Lustre FID to operated on */ + lustre_fid hai_dfid; /* fid used for data access */ + struct hsm_extent hai_extent; /* byte range to operate on */ + __u64 hai_cookie; /* action cookie from coordinator */ + __u64 hai_gid; /* grouplock id */ + char hai_data[0]; /* variable length */ + }; + +To iterate through the requests, use **hai_first** to get the first +request, then **hai_next**. + + +RETURN VALUE +============ + +**llapi_hsm_copytool_register** and **llapi_hsm_copytool_unregister** +return 0 on success. On error, a negative errno is returned. + +**llapi_hsm_copytool_get_fd** returns the file descriptor associated + with the register copytool. On error, a negative errno is returned. + +**llapi_hsm_copytool_recv** returns 0 when a message is available. If +the copytool was set to non-blocking operation, -EWOULDBLOCK is +immediately returned if no message is available. On error, a negative +errno is returned. + + +ERRORS +====== + +**-EINVAL** An invalid value was passed, the copytool is not + registered, ... + +**-ESHUTDOWN** The transport endpoint shutdown. + +**-EPROTO** Lustre protocol error. + +**-EWOULDBLOCK** No HSM message is available, and the copytool was set +to not block on receives. + + +SEE ALSO +======== + +**llapi_hsm_action_begin**\ (3), **llapi_hsm_action_end**\ (3), +**llapi_hsm_action_progress**\ (3), **llapi_hsm_action_get_dfid**\ (3), +**llapi_hsm_action_get_fd**\ (3), **lustreapi**\ (7) + +See *lhsmtool_posix.c* in the Lustre sources for a use case of this +API. diff --git a/lustre/doc/llapi_hsm_copytool_unregister.3 b/lustre/doc/llapi_hsm_copytool_unregister.3 new file mode 100644 index 0000000..b18b515 --- /dev/null +++ b/lustre/doc/llapi_hsm_copytool_unregister.3 @@ -0,0 +1 @@ +.so man3/llapi_hsm_copytool_register.3 diff --git a/lustre/doc/lustreapi.rst b/lustre/doc/lustreapi.rst index bc0da2c..331beb0 100644 --- a/lustre/doc/lustreapi.rst +++ b/lustre/doc/lustreapi.rst @@ -7,7 +7,7 @@ The Lustre API library ---------------------- :Author: Lustre contributors -:Date: 2009-08-10 +:Date: 2014-09-21 :Manual section: 7 :Manual group: The Lustre API library @@ -23,6 +23,42 @@ The lustreapi library provides functions to access and/or modify settings specific to the Lustre filesystem (allocation policies, quotas, etc). +The library provides the following functions: + +**HSM** + + int llapi_hsm_copytool_register(struct hsm_copytool_private \*\*priv, + const char \*mnt, int archive_count, int \*archives, + int rfd_flags) + + int llapi_hsm_copytool_unregister(struct hsm_copytool_private \*\*priv) + + int llapi_hsm_copytool_get_fd(struct hsm_copytool_private \*ct) + + int llapi_hsm_copytool_recv(struct hsm_copytool_private \*priv, + struct hsm_action_list \*\*hal, int \*msgsize) + + struct hsm_action_item \*hai_first(struct hsm_action_list \*hal) + + struct hsm_action_item \*hai_next(struct hsm_action_item \*hai) + + int llapi_hsm_action_begin(struct hsm_copyaction_private \*\*phcp, + const struct hsm_copytool_private \*ct, const struct + hsm_action_item \*hai, int restore_mdt_index, int + restore_open_flags, bool is_error) + + int llapi_hsm_action_end(struct hsm_copyaction_private \*\*phcp, + const struct hsm_extent \*he, int hp_flags, int errval) + + int llapi_hsm_action_progress(struct hsm_copyaction_private \*hcp, + const struct hsm_extent \*he, __u64 total, int hp_flags) + + int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private \*hcp, + lustre_fid \*fid) + + int llapi_hsm_action_get_fd(const struct hsm_copyaction_private \*hcp) + + SEE ALSO ======== -- 1.8.3.1