wrapper/vasum.h

   1 /*
   2  *  Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Krzysztof Dynowski <k.dynowski@samsung.com>
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License");
   7  *  you may not use this file except in compliance with the License.
   8  *  You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *  Unless required by applicable law or agreed to in writing, software
  13  *  distributed under the License is distributed on an "AS IS" BASIS,
  14  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *  See the License for the specific language governing permissions and
  16  *  limitations under the License
  17  */
  18
  19
  20 /**
  21  * @file
  22  * @author  Krzysztof Dynowski (k.dynowski@samsung.com)
  23  * @brief   Vasum old API
  24  */
  25
  26 #ifndef __VASUM_H__
  27 #define __VASUM_H__
  28
  29 #include <unistd.h>
  30 #include <limits.h>
  31 #include <inttypes.h>
  32 #include <sys/types.h>
  33 #include <sys/mount.h>
  34
  35 #include "vasum_list.h"
  36
  37 #ifndef API
  38 #define API __attribute__((visibility("default")))
  39 #endif // API
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /*
  46  * <tt>
  47  * Revision History:
  48  * </tt>
  49  */
  50
  51 /**
  52  * @addtogroup CONTEXT vasum context
  53  * @{
  54 */
  55
  56 /**
  57  *@brief vasum handle for interact with vasum server process. This is opaque data type.
  58  */
  59 typedef struct vsm_context* vsm_context_h;
  60
  61 /**
  62  * @brief Create vsm context
  63  * \par Description:
  64  * The vsm context is an abstraction of the logical connection between the zone controller and it's clients.
  65  * and vsm_context_h object should be finalized when interaction with the vasum server is no longer required.\n
  66  * \return An instance of vsm context on success, or NULL
  67  * \retval vsm_context_h     successful
  68  * \retval NULL               get vasum context failed.
  69  * \par Known issues/bugs:
  70  *  Only a host process has permission for vsm_create_context();
  71  * \pre vsm-zone-svc must be started
  72  * \see vsm_cleanup_context()
  73 */
  74 API vsm_context_h vsm_create_context(void);
  75
  76 /**
  77  * @brief Cleanup zone control context
  78  * \par Description:
  79  * vsm_cleanup_context() finalizes vsm context and release all resources allocated to the vsm context.\n
  80  * This function should be called if interaction with the zone controller is no longer required.
  81  * \param[in] ctx vsm context
  82  * \return #VSM_ERROR_NONE on success.
  83  * \pre vsm_context_h must be initialized by vsm_create_context()
  84  * \post vsm context_h will not be valid after calling this API
  85  * \see vsm_create_context()
  86 */
  87 API int vsm_cleanup_context(vsm_context_h ctx);
  88
  89 /**
  90  * @brief Get file descriptor associated with event dispatcher of zone control context
  91  * \par Description:
  92  * The function vsm_get_poll_fd() returns the file descriptor associated with the event dispatcher of vsm context.\n
  93  * The file descriptor can be bound to another I/O multiplexing facilities like epoll, select, and poll.
  94  * \param[in] ctx vsm context
  95  * \return On success, a nonnegative file descriptor is returned. On negative error code is returned.
  96  * \retval fd nonnegative integer fd value for getting vasum event and refresh vsm_context_h.
  97  * \retval #VSM_ERROR_INVALID invalid vsm_context_h
  98  * \pre vsm_context_h must be initialized by vsm_create_context()
  99  * \see vsm_create_context()
 100 */
 101 API int vsm_get_poll_fd(vsm_context_h ctx);
 102
 103 /**
 104  * @brief Wait for an I/O event on a VSM context
 105  * \par Description:
 106  * vsm_enter_eventloop() waits for event on the vsm context.\n
 107  *\n
 108  * The call waits for a maximum time of timout milliseconds. Specifying a timeout of -1 makes vsm_enter_eventloop() wait indefinitely,
 109  * while specifying a timeout equal to zero makes vsm_enter_eventloop() to return immediately even if no events are available.
 110  * \param[in] ctx vsm context
 111  * \param[in] flags Reserved
 112  * \param[in] timeout Timeout time (milisecond), -1 is infinite
 113  * \return 0 on success,  or negative error code.
 114  * \pre vsm context must be initialized by vsm_create_context()
 115  * \see vsm_create_context(), vsm_get_poll_fd()
 116 */
 117 API int vsm_enter_eventloop(vsm_context_h ctx, int flags, int timeout);
 118
 119 /**
 120  * @brief Enumeration for vasum error.
 121  */
 122 typedef enum {
 123     VSM_ERROR_NONE,            /**< The operation was successful */
 124     VSM_ERROR_GENERIC,        /**< Non-specific cause */
 125     VSM_ERROR_INVALID,        /**< Invalid argument */
 126     VSM_ERROR_CANCELED,        /**< The requested operation was cancelled */
 127     VSM_ERROR_ABORTED,        /**< Operation aborted */
 128     VSM_ERROR_REFUSED,        /**< Connection refused */
 129     VSM_ERROR_EXIST,        /**< Target exists */
 130     VSM_ERROR_BUSY,            /**< Resource is busy */
 131     VSM_ERROR_IO,            /**< I/O error*/
 132     VSM_ERROR_TIMEOUT,        /**< Timer expired */
 133     VSM_ERROR_OVERFLOW,        /**< Value too large to be stored in data type */
 134     VSM_ERROR_OUT_OF_MEMORY,    /**< No memory space */
 135     VSM_ERROR_OUT_OF_RANGE,        /**< Input is out of range */
 136     VSM_ERROR_NOT_PERMITTED,        /**< Operation not permitted */
 137     VSM_ERROR_NOT_IMPLEMENTED,    /**< Function is not implemented yet */
 138     VSM_ERROR_NOT_SUPPORTED,    /**< Operation is not supported */
 139     VSM_ERROR_ACCESS_DENIED,    /**< Access privilege is not sufficient */
 140     VSM_ERROR_NO_OBJECT,        /**< Object not found */
 141     VSM_ERROR_BAD_STATE,        /**< Bad state */
 142     VSM_MAX_ERROR = VSM_ERROR_BAD_STATE
 143 }vsm_error_e;
 144
 145 /**
 146  * @brief Get last vasum error code from vsm_context.
 147  * \param[in] ctx vsm context
 148  * \return vasum error enum value.
 149  * \par Known issues/bugs:
 150  *     thread non-safe
 151  * \see vsm_error_string()
 152 */
 153 API vsm_error_e vsm_last_error(vsm_context_h ctx);
 154
 155 /**
 156  * @brief Get vasum error string.
 157  * \par Description:
 158  * return string pointer for vasum error string.
 159  * \param[in] error vsm_error_e.
 160  * \return string pointer value represent to error code.
 161  * \warning Do not free returned pointer.
 162 */
 163 API const char *vsm_error_string(vsm_error_e error);
 164
 165 /// @}
 166
 167 /**
 168  * @addtogroup LIFECYCLE Vasum Lifecycle
 169  * @{
 170  */
 171
 172 /**
 173  * @brief vsm_zone_h opaque datatype which is used to represent an instance of zone.
 174  */
 175
 176 typedef struct vsm_zone* vsm_zone_h;
 177
 178 /**
 179  * @brief Definition for default zone name.
 180  * Default zone is started at boot sequence by systemd.
 181 */
 182 #define VSM_DEFAULT_ZONE "personal"
 183
 184
 185 /**
 186  * @brief Create a new persistent zone
 187  * \par Description:
 188  * vsm_create_zone() triggers zone controller to create new persistent zone.\n\n
 189  * The zone controller distinguishes two types of zones: peristent and transient.
 190  * Persistent zones exist indefinitely in storage.
 191  * While, transient zones are created and started on-the-fly.\n\n
 192  * Creating zone requires template.\n
 193  * In general, creating a zone involves constructing root file filesystem and
 194  * generating configuration files which is used to feature the zone.
 195  * Moreover, it often requires downloading tools and applications pages,
 196  * which are not available in device.
 197  * In that reason, Vasum Framework delegates this work to templates.
 198  * \param[in] ctx vsm context
 199  * \param[in] zone_name zone name
 200  * \param[in] template_name template name to be used for constructing the zone
 201  * \param[in] flag Reserved
 202  * \return 0 on success, or negative integer error code on error.
 203  * \retval #VSM_ERROR_NONE     Successful
 204  * \retval #VSM_ERROR_INVALID  Invalid arguments
 205  * \retval #VSM_ERROR_EXIST    The same name zone is existed.
 206  * \retval #VSM_ERROR_GENERIC  Lxc failed to create zone.
 207  * \retval #VSM_ERROR_IO       Database access failed
 208 */
 209 API int vsm_create_zone(vsm_context_h ctx, const char *zone_name, const char *template_name, int flag);
 210
 211 /**
 212  * @brief Destroy persistent zone
 213  * \par Description:
 214  * The function vsm_destroy_zone() triggers zone controller to destroy persistent zone corresponding to the given name.\n
 215  * All data stored in the repository of the zone are also deleted if force argument is set.
 216  * Once the zone repository is deleted, it cannot be recovered.
 217  * \param[in] ctx vsm context
 218  * \param[in] zone_name zone name
 219  * \param[in] force forced flags
 220  * - 0 : do not destory running zone.
 221  * - non-zero : if zone is running, shutdown forcefully, and destroy.
 222  * \return 0 on success, or negative integer error code on error.i
 223  * \retval #VSM_ERROR_NONE       Successful
 224  * \retval #VSM_ERROR_BUSY       Target zone is running
 225  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 226  * \retval #VSM_ERROR_GENERIC    Lxc failed to destroy zone
 227  * \retval #VSM_ERROR_IO         Database access failed
 228 */
 229 API int vsm_destroy_zone(vsm_context_h ctx, const char *zone_name, int force);
 230
 231 /**
 232  * @brief Start an execution of a persistent zone
 233  * \par Description:
 234  * The function vsm_start_zone() triggers zone controller to start zone corresponding to the given name.\n
 235  * Caller can speficy the type of zones: transient and peristent.
 236  * Persistent zones need to be defined before being start up(see vsm_create_zone())
 237  * While, transient zones are created and started on-the-fly.
 238  * \param[in] ctx vsm context
 239  * \param[in] zone_name zone name
 240  * \return 0 on success, or negative integer error code on error.
 241  * \retval #VSM_ERROR_NONE       Successful
 242  * \retval #VSM_ERROR_INVALID    Invalid argument.
 243  * \retval #VSM_ERROR_BUSY       Target zone is already running state.
 244  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 245  * \retval #VSM_ERROR_GENERIC    Lxc failed to start zone
 246 */
 247 API int vsm_start_zone(vsm_context_h ctx, const char *zone_name);
 248
 249 /**
 250  * @brief Stop an execution of running zone
 251  * \par Description:
 252  * Send request to stop running zone.\n
 253  * \param[in] ctx vsm context
 254  * \param[in] zone_name zone name
 255  * \param[in] force option to shutdown.
 256  *    - 0 : send SIGPWR signal to init process of target zone.
 257  *  - non-zero : terminate all processes in target zone.
 258  * \return 0 on success, or negative integer error code on error.
 259  * \retval #VSM_ERROR_NONE       Successful
 260  * \retval #VSM_ERROR_INVALID    Invalid argument.
 261  * \retval #VSM_ERROR_BAD_STATE  Failed to lookup running zone.
 262  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 263  * \retval #VSM_ERROR_GENERIC    Lxc failed to destroy zone
 264 */
 265 API int vsm_shutdown_zone(vsm_context_h ctx, const char *zone_name, int force);
 266
 267 /**
 268  * @brief Shutdown zone and prevent starting zone
 269  * \par Description:
 270  *  Prevent starting target zone.
 271  *  If target zone is running, shutdown the zone first.
 272  * \param[in] ctx vsm context
 273  * \param[in] zone_name zone name
 274  * \return 0 on success, or negative integer error code on error.
 275  * \retval #VSM_ERROR_NONE       Successful
 276  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 277  * \retval #VSM_ERROR_GENERIC    Locking failed.
 278 */
 279 API int vsm_lock_zone(vsm_context_h ctx, const char *zone_name, int shutdown);
 280
 281 /**
 282  * @brief Allow a zone to be launched
 283  * \par Description:
 284  * Remove lock applied to the zone corresponding to the given name.
 285  * \param[in] ctx vsm context
 286  * \param[in] zone_name zone name
 287  * \return 0 on success, or negative integer error code on error.
 288  * \retval #VSM_ERROR_NONE       Successful
 289  * \retval #VSM_ERROR_GENERIC    Unlocking failed.
 290 */
 291 API int vsm_unlock_zone(vsm_context_h ctx, const char *zone_name);
 292
 293 /**
 294  * @brief Switch target zone to foreground
 295  * \par Description:
 296  * Switch target zone to foreground on device.
 297  * \param[in] zone vsm_zone_h
 298  * \return 0 on success, or negative integer error code on error.
 299  * \retval #VSM_ERROR_NONE       Successful
 300  * \retval #VSM_ERROR_INVALID    vsm_zone_h is invalid
 301  */
 302 API int vsm_set_foreground(vsm_zone_h zone);
 303
 304 /**
 305  * @brief Get current foreground zone on device
 306  * \par Description:
 307  * Get foreground zone handle.
 308  * \param[in] ctx vsm_context_h
 309  * \return 0 on success, or negative integer error code on error.
 310  * \retval #VSM_ERROR_NONE       Successful
 311  * \retval #VSM_ERROR_INVALID    vsm_context_h is invalid
 312  */
 313 API vsm_zone_h vsm_get_foreground(vsm_context_h ctx);
 314
 315 /// @}
 316 /**
 317  * @addtogroup ACCESS Vasum Access
 318  * @{
 319 */
 320
 321 /**
 322  * @brief Definition for zone states.
 323  * This definition shows the available states.
 324 */
 325 typedef enum {
 326     VSM_ZONE_STATE_STOPPED,  /**< Zone stopped */
 327     VSM_ZONE_STATE_STARTING, /**< Zone is prepare for running */
 328     VSM_ZONE_STATE_RUNNING,  /**< Zone is running on device */
 329     VSM_ZONE_STATE_STOPPING, /**< Zone is stopping by request */
 330     VSM_ZONE_STATE_ABORTING, /**< Zone is failed to start */
 331     VSM_ZONE_STATE_FREEZING, /**< Reserved State */
 332     VSM_ZONE_STATE_FROZEN,   /**< Reserved State */
 333     VSM_ZONE_STATE_THAWED,   /**< Reserved State */
 334     VSM_ZONE_MAX_STATE = VSM_ZONE_STATE_THAWED
 335 } vsm_zone_state_t;
 336
 337
 338 /**
 339  * @brief Definition for zone events
 340 */
 341 typedef enum {
 342     VSM_ZONE_EVENT_NONE,      /**< Zone has no event */
 343     VSM_ZONE_EVENT_CREATED,   /**< Zone is created */
 344     VSM_ZONE_EVENT_DESTROYED, /**< Zone is destroted */
 345     VSM_ZONE_EVENT_SWITCHED,  /**< Foreground is switched */
 346     VSM_ZONE_MAX_EVENT = VSM_ZONE_EVENT_SWITCHED
 347 } vsm_zone_event_t;
 348
 349
 350 /**
 351  * @brief Definition for zone iteration callback function.
 352  */
 353 typedef void (*vsm_zone_iter_cb)(vsm_zone_h zone, void *user_data);
 354 /**
 355  * @brief Definition for zone state changed callback function.
 356  */
 357 typedef int (*vsm_zone_state_changed_cb)(vsm_zone_h zone, vsm_zone_state_t state,  void *user_data);
 358 /**
 359  * @brief Definition for zone event callback function.
 360  */
 361 typedef int (*vsm_zone_event_cb)(vsm_zone_h zone, vsm_zone_event_t event, void *user_data);
 362
 363 /**
 364  * @brief Interate all zone instances which are in running state
 365  * \par Description:
 366  * This API traverses all zones which are in running state, and callback function will be called on every entry.
 367  * \param[in] ctx vsm context
 368  * \param[in] callback Function to be executed in iteration, which can be NULL
 369  * \param[in] user_data Parameter to be passed to callback function
 370  * \return 0 on success, or negative integer error code on error.
 371  * \retval #VSM_ERROR_NONE           Successful
 372  * \retval #VSM_ERROR_OUT_OF_MEMORY  Zone handle allocation failed
 373  * \retval #VSM_ERROR_GENERIC        Zone initialize failed
 374  * \remark In case of callback and is NULL,
 375  *  This API refresh vsm_context which means reloading current running zone to vsm_context again.
 376 */
 377 API int vsm_iterate_zone(vsm_context_h ctx, vsm_zone_iter_cb callback, void *user_data);
 378
 379 /**
 380  * @brief Find zone corresponding to the name
 381  * The function vsm_lookup_zone_by_name() looks for the zone instance corresponding to the given name.
 382  * \param[in] ctx vsm context
 383  * \param[in] name zone name
 384  * \return Zone instance on success, or NULL on error.
 385  * \retval vsm_zone_h  Successful
 386  * \retval NULL        Failed to lookup
 387  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or vsm_context_h does not have current zone status.
 388  * \see vsm_create_context(), vsm_enter_eventloop()
 389 */
 390 API vsm_zone_h vsm_lookup_zone_by_name(vsm_context_h ctx, const char *name);
 391
 392 /**
 393  * @brief Find zone instance associated with the process id
 394  * \par Description:
 395  * The function vsm_lookup_zone_by_pid() looks for the zone instance associated with the given pid.
 396  * \param[in] ctx vsm context
 397  * \param[in] pid Process id
 398  * \return Zone instance on success, or NULL on error.
 399  * \retval vsm_zone_h  Successful
 400  * \retval NULL        Failed to lookup
 401  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or vsm_context_h does not have current zone status.
 402  * \see vsm_create_context(), vsm_enter_eventloop()
 403 */
 404 API vsm_zone_h vsm_lookup_zone_by_pid(vsm_context_h ctx, pid_t pid);
 405
 406 /**
 407  * @brief Register zone status changed callback
 408  * \par Description:
 409  * Register a callback function for zone status change.
 410  * \param[in] ctx vsm context
 411  * \param[in] callback Callback function to invoke when zone satte event occurs
 412  * \return Callback handle on success, or negative error code on error.
 413  * \retval handle nonnegative handle id for callback.
 414  * \retval #VSM_ERROR_OUT_OF_MEMORY  Callback hanlder allocation failed.
 415  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or callback function does not called.
 416  * \see vsm_create_context(), vsm_enter_eventloop(), vsm_del_state_changed_callback()
 417 */
 418 API int vsm_add_state_changed_callback(vsm_context_h ctx, vsm_zone_state_changed_cb callback, void *user_data);
 419
 420 /**
 421  * @brief Deregister zone status changed callback handler
 422  * \par Description:
 423  * Remove an event callback from the zone control context.
 424  * \param[in] ctx vsm context
 425  * \param[in] handle Callback Id to remove
 426  * \return 0 on success, or negative integer error code on error.
 427  * \retval #VSM_ERROR_NONE Successful
 428  * \retval #VSM_ERROR_NO_OBJECT Failed to lookup callback handler
 429 */
 430 API int vsm_del_state_changed_callback(vsm_context_h ctx, int handle);
 431
 432 /**
 433  * @brief Register zone event callback
 434  * \par Description:
 435  * Register a callback function for zone event.
 436  * \param[in] ctx vsm context
 437  * \param[in] callback callback function to invoke when zone event occurs
 438  * \return positive callback handle on success, or negative error code on error.
 439  * \retval handle nonnegative handle id for callback.
 440  * \retval #VSM_ERROR_OUT_OF_MEMORY  Callback hanlder allocation failed.
 441  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or callback function does not called.
 442  * \see vsm_create_context(), vsm_enter_eventloop(), vsm_del_state_changed_callback()
 443 */
 444 API int vsm_add_event_callback(vsm_context_h ctx, vsm_zone_event_cb callback, void *user_data);
 445
 446 /**
 447  * @brief Deregister zone event callback handler
 448  * \par Description:
 449  * Remove an event callback from the zone control context.
 450  * \param[in] ctx vsm context
 451  * \param[in] handle callback handle to remove
 452  * \return 0 on success, or negative integer error code on error.
 453  * \retval #VSM_ERROR_NONE Successful
 454  * \retval #VSM_ERROR_NO_OBJECT Failed to lookup callback handler
 455 */
 456 API int vsm_del_event_callback(vsm_context_h ctx, int handle);
 457
 458 /**
 459  * @brief Zone attach parameters
 460  * Arguments are same as linux system-call execv()
 461  */
 462 typedef struct vsm_attach_command_s {
 463     char * exec;      /**< Program binary path */
 464     char ** argv;     /**< An array of argument pointers to null-terminated strings include program path */
 465 } vsm_attach_command_s;
 466
 467 /**
 468  * @brief Zone attach option
 469  */
 470 typedef struct vsm_attach_options_s {
 471     uid_t uid;        /**< requested uid*/
 472     gid_t gid;        /**< requested gid*/
 473     int env_num;      /**< requested environ count */
 474     char **extra_env; /**< requested environ string pointer array. */
 475 } vsm_attach_options_s;
 476
 477 /**
 478  * @brief default attach options
 479  * \n
 480  * uid = root\n
 481  * gid = root\n
 482  * env = no extra env\n
 483  */
 484
 485 #define VSM_ATTACH_OPT_DEFAULT {  (uid_t)0, (gid_t)0,  0, NULL }
 486
 487 /**
 488  * @brief Launch a process in a running zone.
 489  * \par Description:
 490  * Execute specific command inside the zone with given arguments and environment
 491  * \param[in] zone_name vsm_zone_h
 492  * \param[in] command vsm attach command
 493  * \param[in] opt vsm attach options (can be NULL), using VSM_ATTACH_OPT_DEFAULT
 494  * \param[out] attached_process process pid
 495  * \return On sucess 0, otherwise, a negative integer error code on error
 496  * \retval #VSM_ERROR_NONE           Successful
 497  * \retval #VSM_ERROR_INVALID        Invalid arguments
 498  * \retval #VSM_ERROR_NO_OBJECT      Target zone is not running state
 499  * \retval #VSM_ERROR_GENERIC        IPC failed
 500  */
 501 API int vsm_attach_zone(vsm_context_h ctx, const char * zone_name, vsm_attach_command_s * command, vsm_attach_options_s * opt, pid_t *attached_process);
 502
 503 /**
 504  * @brief Launch a process in a running zone and wait till child process exited.
 505  * \par Description:
 506  * Execute specific command inside the zone with given arguments and environment
 507  * \param[in] zone_name vsm_zone_h
 508  * \param[in] command vsm attach command
 509  * \param[in] opt vsm attach options (can be NULL), using VSM_ATTACH_OPT_DEFAULT
 510  * \return On sucess waitpid exit code or attached process, or a negative error code
 511  * \retval #VSM_ERROR_NONE           Successful
 512  * \retval #VSM_ERROR_INVALID        Invalid arguments
 513  * \retval #VSM_ERROR_NO_OBJECT      Target zone is not running state
 514  * \retval #VSM_ERROR_GENERIC        IPC failed or waitpid error
 515  */
 516 API int vsm_attach_zone_wait(vsm_context_h ctx, const char * zone_name, vsm_attach_command_s * command, vsm_attach_options_s * opt);
 517
 518 /**
 519  * @brief Get name string of zone.
 520  * \par Description:
 521  * Get name string of zone.
 522  * \param[in] zone vsm zone handle
 523  * \return a pointer of zone name string on sucess or NULL on fail.
 524  * \retval name string value of zone.
 525  * \retval NULL vsm_zone_h is invalid.
 526  * \warning Do not modify or free returned pointer memroy.
 527  *          This memory will be cleanup by vsm_cleanup context()
 528 */
 529 API const char * vsm_get_zone_name(vsm_zone_h zone);
 530
 531 /**
 532  * @brief Get zone root ablsolute path on host side.
 533  * \par Description:
 534  * Get rootpath string of zone.
 535  * \param[in] zone vsm zone handle
 536  * \return a pointer of zone rootpath string on sucess or NULL on fail.
 537  * \retval rootpath string value of zone.
 538  * \retval NULL vsm_zone_h is invalid.
 539  * \warning Do not modify or free returned memroy.
 540  *          This memory will be cleanup by vsm_cleanup context()
 541 */
 542 API const char * vsm_get_zone_rootpath(vsm_zone_h zone);
 543
 544 /**
 545  * @brief Get type of running zone.
 546  * \par Description:
 547  * Get type string of zone. This value is defined in template file when using vsm_create_zone()
 548  * \param[in] zone vsm zone handle
 549  * \return a pointer of zone path string on sucess or NULL on fail.
 550  * \retval rootpath string value of zone.
 551  * \retval NULL vsm_zone_h is invalid.
 552  * \see vsm_create_zone()
 553  * \warning Do not modify or free returned memroy.
 554  *          This memory will be cleanup by vsm_cleanup context()
 555 */
 556 API const char * vsm_get_zone_type(vsm_zone_h zone);
 557
 558 /**
 559  * @brief Check zone handle, a host or a normal zone by zone handle.
 560  * \param[in] zone vsm zone handle
 561  * \return positive integer on host case, or 0 on normal zone.
 562  * \retval positive target zone is host zone.
 563  * \retval NULL     target zone is NOT host.
 564 */
 565 API int vsm_is_host_zone(vsm_zone_h zone);
 566
 567 /**
 568  * @brief get zone state.
 569  * \par Description:
 570  * Get zone state value by zone handle.
 571  * \param[in] zone vsm zone handle
 572  * \return vsm_zone_state_t value, or negative value.
 573  * \retval state vsm_zone_state_t value of zone
 574  * \retval #VSM_ERROR_INVALID vsm_zone_h is invalid
 575 */
 576
 577 API vsm_zone_state_t vsm_get_zone_state(vsm_zone_h zone);
 578
 579 /**
 580  * @brief get zone id by handle.
 581  * \par Description:
 582  * Get zone id value by zone handle.
 583  * \param[in] zone vsm zone handle
 584  * \return interger id value of zone or negative error.
 585  * \retval id nonnegative interger value.
 586  * \retval #VSM_ERROR_INVALID vsm_zone_h is invalid
 587  * \remarks id '0' is reserved for host.
 588 */
 589 API int vsm_get_zone_id(vsm_zone_h zone);
 590
 591 /**
 592  * @brief Set userdata pointer value in vsm_zone_h.
 593  * \par Description:
 594  * Get zone id value by zone handle.
 595  * \param[in] zone vsm zone handle
 596  * \return On success 0, or negative error.
 597  * \retval #VSM_ERROR_NONE     Successful.
 598  * \retval #VSM_ERROR_INVALID  vsm_zone_h is invalid
 599  * \warning This userdata have to be free before vsm_cleanup_context() or VSM_ZONE_STATE_STOPPED callback handler
 600 */
 601 API int vsm_set_userdata(vsm_zone_h zone, void * userdata);
 602
 603 /**
 604  * @brief Set userdata pointer value in vsm_zone_h.
 605  * \par Description:
 606  * Get zone id value by zone handle.
 607  * \param[in] zone vsm zone handle
 608  * \return On success pointer of userdata, or NULL pointer
 609  * \retval userdata pointer of userdata.
 610  * \retval NULL invalid vsm_zone_h.
 611  * \remark initial value is pointer of self vsm_zone_h
 612 */
 613 API void * vsm_get_userdata(vsm_zone_h zone);
 614
 615
 616 /**
 617  * @brief join current process into zone.
 618  * \par Synopsys:
 619  * Change self peer credential to target zone
 620  * \param[in] zone vsm_zone_h
 621  * \return before vsm_zone on success, or NULL on error.
 622  * \retval vsm_zone_h before zone handle, If caller process running in host, then host handle returned.
 623  * \retval NULL       invalid zone handle.
 624  * \pre parameter vsm zone must be lookup by vsm lookup APIs
 625  * \post  After finish target zone procedure, must join again before zone by same API.
 626  * \warning This function is not thread-safe. \n
 627  *   All requests of threads in same process are considered target zone request to other host processes.
 628  */
 629 API vsm_zone_h vsm_join_zone(vsm_zone_h zone);
 630
 631 /**
 632  * @brief get canonical file path based on current zone.
 633  * \par Description:
 634  *    get canonical file path based on current zone.
 635  * \param[in] input_path requested zone path
 636  * \param[out] output_path string pointer for canonicalized output path
 637  * \return int positive string length of output_path, or negative error code on error.
 638  * \retval #VSM_ERROR_INVALID Invalid arguments.
 639  * \retval #VSM_ERROR_GENERIC gethostname() is failed.
 640  * \post Out buffer(*output_path) have to be freed by caller after use.
 641  * \remarks This API can call inside zone without vsm_context_h
 642  *   It means this API can call library side for apps.
 643  */
 644 API int vsm_canonicalize_path(const char *input_path, char **output_path);
 645
 646 /**
 647  * @brief Check current environment, a host or virtualized zone.
 648  * \par Description:
 649  *    Check current caller process environment.
 650  * \return positive integer on running in zone, or 0 on running in host.
 651  * \retval NULL     Current process running in host.
 652  * \remarks This API can call inside zone without vsm_context_h
 653  *   It means this API can call library side for apps.
 654  */
 655 API int vsm_is_virtualized(void);
 656
 657 /**
 658  * @brief Check equivalence between caller and target pid.
 659  * \par Description:
 660  *    Check API caller process and target pid running in same zone.
 661  * \retval NULL       target process is running in another zone.
 662  * \retval 1        target process is running in same zone.
 663  * \retval -1       failed to check target process.
 664  * \remarks This API can check real zone of target pid.
 665             Real zone is not changed by even join API.
 666  */
 667 API int vsm_is_equivalent_zone(vsm_context_h ctx, pid_t pid);
 668
 669 /**
 670  * @brief Translate zone pid to host pid.
 671  * \par Description:
 672  *    This API would translate zone namespace pid to host namespace pid.
 673  * \param[in] zone  the zone of target process
 674  * \param[in] pid   target process id of zone namespace
 675  * \return positive pid or negative error code.
 676  * \retval pid                       translated host pid of zone process.
 677  * \retval #VSM_ERROR_NO_OBJECT      No such process in a target zone.
 678  * \retval #VSM_ERROR_NOT_PERMITTED  Permission denied to get target pid info.
 679  * \retval #VSM_ERROR_NOT_SUPPORTED  Kernel config is not enabled about pid namespace.
 680  * \retval #VSM_ERROR_INVALID        Arguments is invalid.
 681  * \retval #VSM_ERROR_IO             Failed to get process info.
 682  * \retval #VSM_ERROR_GENERIC        Failed to matching zone pid to host pid.
 683  */
 684 API int vsm_get_host_pid(vsm_zone_h zone, pid_t pid);
 685
 686
 687 /// @}
 688
 689 /**
 690  * @addtogroup NETWORK Vasum Network
 691  * @{
 692 */
 693
 694 /**
 695  * @brief Types of virtual network interfaces
 696  */
 697 typedef enum {
 698     VSM_NETDEV_VETH, /**< Virtual Ethernet(veth), this type device will be attached to host-side network bridge */
 699     VSM_NETDEV_PHYS, /**< Physical device */
 700     VSM_NETDEV_MACVLAN /**< Mac VLAN, this type isn't implemented yet */
 701 } vsm_netdev_type_t;
 702
 703 typedef enum {
 704     VSM_NETDEV_ADDR_IPV4, /**< IPV4 Address family */
 705     VSM_NETDEV_ADDR_IPV6 /**< IPV6 Address family */
 706 } vsm_netdev_addr_t;
 707
 708 /**
 709  * @brief Network device information
 710  */
 711 typedef struct vsm_netdev *vsm_netdev_h;
 712
 713 /**
 714  * @brief Definition for zone network devince iteration callback function.
 715  */
 716 typedef void (*vsm_zone_netdev_iter)(struct vsm_netdev *, void *user_data);
 717
 718 /**
 719  * @brief Create a new network device and assisgn it to zone
 720  * \par Description:
 721  * This function creates net netdev instance and assign it to the given zone.
 722  * \param[in] zone Zone
 723  * \param[in] type Type of network device to be create
 724  * \param[in] target
 725  * - If type is veth, this will be bridge name to attach.
 726  * - If type is phys, this will be ignored.
 727  * \param[in] netdev Name of network device to be create
 728  * \return Network devce on success, or NULL on error.
 729  * \retval vsm_netdev_h New net device handle
 730  * \retval NULL         Failed to create netdev
 731  * \see vsm_create_netdev()
 732  * \par Known Issues:
 733  *  Macvlan is not implemented yet.
 734  */
 735 API vsm_netdev_h vsm_create_netdev(vsm_zone_h zone, vsm_netdev_type_t type, const char *target, const char *netdev);
 736
 737 /**
 738  * @brief Removes a network device from zone
 739  * \par Description:
 740  * This function remove the given netdev instance from the zone control context.
 741  * \param[in] netdev network device to be removed
 742  * \return 0 on success, or negative integer error code on error.
 743  * \retval #VSM_ERROR_NONE           Successful
 744  * \retval #VSM_ERROR_INVALID        Invalid arguments
 745  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 746  * \see vsm_destroy_netdev()
 747  */
 748 API int vsm_destroy_netdev(vsm_netdev_h netdev);
 749
 750 /**
 751  * @brief Iterates network devices found in the zone vsm context and executes callback() on each interface.
 752  * \par Description:
 753  * vsm_destroy_netdev() scans all network interfaces which are registered in the vsm context, and calls callback() on each entry.
 754  * \param[in] zone Zone
 755  * \param[in] callback Function to be executed in iteration, which can be NULL
 756  * \param[in] user_data Parameter to be delivered to callback function
 757  * \return 0 on success, or negative integer error code on error.
 758  * \retval #VSM_ERROR_NONE           Successful
 759  * \retval #VSM_ERROR_INVALID        Invalid arguments
 760  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 761  * \see vsm_create_netdev(), vsm_destroy_netdev()
 762  */
 763 API int vsm_iterate_netdev(vsm_zone_h zone, vsm_zone_netdev_iter callback, void *user_data);
 764
 765 /**
 766  * @brief Find a network device corresponding to the name
 767  * \par Description:
 768  * The function vsm_lookup_netdev_by_name() looks for a network interface.
 769  * \param[in] name Network device name to search
 770  * \return Network device on success, or NULL on error.
 771  * \retval vsm_netdev_h Target net device handle
 772  * \retval NULL         Failed to lookup netdev
 773  */
 774
 775 API vsm_netdev_h vsm_lookup_netdev_by_name(vsm_zone_h zone, const char *name);
 776
 777 /**
 778  * @brief Turn up a network device in the zone
 779  * \par Description:
 780  * This function turns up the given netdev instance in the zone.
 781  * \param[in] netdev network device to be removed
 782  * \return 0 on success, or negative integer error code on error.
 783  * \retval #VSM_ERROR_NONE           Successful
 784  * \retval #VSM_ERROR_INVALID        Invalid arguments
 785  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 786  * \see vsm_down_netdev()
 787  */
 788 API int vsm_up_netdev(vsm_netdev_h netdev);
 789
 790 /**
 791  * @brief Turn down a network device in the zone
 792  * \par Description:
 793  * This function turns down the given netdev instance in the zone.
 794  * \param[in] netdev network device to be removed
 795  * \return 0 on success, or negative integer error code on error.
 796  * \retval #VSM_ERROR_NONE           Successful
 797  * \retval #VSM_ERROR_INVALID        Invalid arguments
 798  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 799  * \see vsm_down_netdev()
 800  */
 801 API int vsm_down_netdev(vsm_netdev_h netdev);
 802
 803 /**
 804  * @brief Get ip address from a network device
 805  * \par Description:
 806  * The function vsm_get_ip_addr_netdev() get ip address from a network interface
 807  * \param[in] netdev Network device to get address
 808  * \param[in] addr_family Address family
 809  * \param[out] addr Buffer to get address from a network device
 810  * \param[out] size Size of buffer
 811  * \return 0 on success, or negative integer error code on error.
 812  * \retval #VSM_ERROR_NONE           Successful
 813  * \retval #VSM_ERROR_INVALID        Invalid arguments
 814  * \retval #VSM_ERROR_OVERFLOW       Parameter overflow
 815  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 816  * \see vsm_set_ip_addr_netdev()
 817  */
 818 API int vsm_get_ip_addr_netdev(vsm_netdev_h netdev, vsm_netdev_addr_t addr_family, char *addr, int size);
 819
 820 /**
 821  * @brief Set ip address to a network device
 822  * \par Description:
 823  * The function vsm_set_ip_addr_netdev() set ipv4 address to a network interface
 824  * \param[in] netdev Network device to set address
 825  * \param[in] addr_family Address family
 826  * \param[in] addr IP address string to be set
 827  * \param[in] prefix prefix ( ex> 192.168.122.1/24, 24 is prefix )
 828  * \return 0 on success, or negative integer error code on error.
 829  * \retval #VSM_ERROR_NONE           Successful
 830  * \retval #VSM_ERROR_INVALID        Invalid arguments
 831  * \retval #VSM_ERROR_OVERFLOW       Parameter overflow
 832  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 833  * \see vsm_get_ip_addr_netdev()
 834  */
 835 API int vsm_set_ip_addr_netdev(vsm_netdev_h netdev, vsm_netdev_addr_t addr_family, const char *addr, int prefix);
 836
 837
 838
 839 /// @}
 840
 841 /**
 842  * @addtogroup DEVICE Vasum Device
 843  * @{
 844 */
 845
 846 /**
 847  * @brief Grant device to zone
 848  * \par Description:
 849  * Request permission device file node to target zone.
 850  * \param[in] zone vsm_zone_h
 851  * \param[in] path device node path
 852  * \param[in] flags requested permission O_RDWR, O_WRONLY, O_RDONLY
 853  * \return 0 on success, or negative integer error code on error.
 854  * \retval #VSM_ERROR_NONE           Successful
 855  * \retval #VSM_ERROR_INVALID        Invalid arguments
 856  * \retval #VSM_ERROR_NOT_PERMITTED  Change cgroup is not permitted
 857  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 858  * \see vsm_revoke_device()
 859  */
 860 API int vsm_grant_device(vsm_zone_h zone, const char *path, uint32_t flags);
 861
 862 /**
 863  * @brief Revoke device from the zone
 864  * \par Description:
 865  * Revoke device node permissions from target zone.
 866  * \param[in] zone vsm_zone_h
 867  * \param[in] path device node path
 868  * \return 0 on success, or negative integer error code on error.
 869  * \retval #VSM_ERROR_NONE           Successful
 870  * \retval #VSM_ERROR_INVALID        Invalid arguments
 871  * \retval #VSM_ERROR_NOT_PERMITTED  Change cgroup is not permitted
 872  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 873  * \see vsm_grant_device()
 874  */
 875 API int vsm_revoke_device(vsm_zone_h zone, const char *path);
 876 /// @}
 877
 878
 879 /**
 880  * @addtogroup RESOURCE Vasum Resource
 881  * @{
 882  */
 883
 884 /**
 885  * @brief Definition for declare file type.
 886 */
 887 typedef enum {
 888     VSM_FSO_TYPE_DIR,  /**< Directoy type */
 889     VSM_FSO_TYPE_REG,  /**< Regular file type */
 890     VSM_FSO_TYPE_FIFO, /**< Fifo file type */
 891     VSM_FSO_TYPE_SOCK, /**< Socket file type */
 892     VSM_FSO_TYPE_DEV,  /**< Device node type */
 893     VSM_FSO_MAX_TYPE = VSM_FSO_TYPE_DEV
 894 } vsm_fso_type_t;
 895
 896
 897 /**
 898  * @brief Declare file mode.
 899 */
 900 typedef mode_t vsm_mode_t;
 901
 902 /**
 903  * @brief Declare specific file object to every zone.
 904  * \par Description:
 905  * Declare host file system to every running zone.
 906  * In case of host target file exist, create new file in running zone. or create a new file in running zone.
 907  * And add hook info in vsm-resource-provier for automatically link host target file to starting zone.
 908  * Smack labels are also copied as same as host labels.
 909  * \param[in] ctx vsm context
 910  * \param[in] ftype Type of file system object
 911  * \param[in] path Path for the file system object
 912  * \param[in] flags Flasg
 913  * \param[in] mode mode
 914  * \return zero on success, or negative value on error.
 915  * \retval #VSM_ERROR_NONE      successful.
 916  * \retval #VSM_ERROR_INVALID   Invalid file type or path.
 917  * \retval #VSM_ERROR_GENERIC   Error in vasum server side.
 918  * \retval #VSM_ERROR_NO_OBJECT Source file is not exist in host filesystem
 919 */
 920 API int vsm_declare_file(vsm_context_h ctx, vsm_fso_type_t ftype, const char *path, int flags, vsm_mode_t mode);
 921
 922 /**
 923  * @brief Declare hardlink to every zone.
 924  * \par Description:
 925  * Declare hardlink to host file to every running zone.
 926  * And add hook info in vsm-resource-provier for automatically link host target file to starting zone.
 927  * In general, this function is used to share file host and all running zones.
 928  * Smack labels are also copied as same as host labels.
 929  * \param[in] ctx vsm context
 930  * \param[in] source source
 931  * \param[in] target target
 932  * \return zero on success, or negative value on error.
 933  * \retval #VSM_ERROR_NONE      successful
 934  * \retval #VSM_ERROR_INVALID   Invalid provision type to db.
 935  * \retval #VSM_ERROR_GENERIC   Error in vasum server side.
 936  * \retval #VSM_ERROR_NO_OBJECT Source file is not exist in host filesystem
 937 */
 938 API int vsm_declare_link(vsm_context_h ctx , const char *source, const char *target);
 939 /// @}
 940
 941
 942 /*
 943     Below datatypes will be opaque.
 944 */
 945 typedef struct vsm_context {
 946     void * signal_channel;
 947     void * manage_method_channel;
 948     void * unpriv_method_channel;
 949     vsm_error_e error;
 950     pthread_rwlock_t lock;
 951     struct adt_list listeners;
 952     struct vsm_zone *root_zone;
 953     struct vsm_zone *foreground_zone;
 954     struct adt_list sc_listeners;
 955     struct adt_list ev_listeners;
 956     void * vsm_ops;
 957 } vsm_context_s;
 958
 959 typedef struct vsm_zone {
 960     struct vsm_zone *parent;
 961     char *name;
 962     char *type;
 963     int terminal;
 964     vsm_zone_state_t state;
 965     char *rootfs_path;
 966     pthread_rwlock_t lock;
 967     struct adt_list children;
 968     struct adt_list devices;
 969     struct adt_list netdevs;
 970     void *user_data;
 971     struct adt_list list;
 972     struct vsm_context *ctx;
 973     int id;
 974 } vsm_zone_s;
 975
 976 typedef struct vsm_netdev {
 977     struct vsm_zone *zone;
 978     char *name;
 979     vsm_netdev_type_t type;
 980     struct adt_list list;
 981 } vsm_netdev_s;
 982
 983 /*
 984     Below APIs will be removed.
 985 */
 986
 987 typedef int (*vsm_zone_state_cb)(vsm_zone_h zone, vsm_zone_state_t state ,vsm_zone_event_t event, void *user_data);
 988
 989 API int vsm_add_state_callback(vsm_context_h ctx, vsm_zone_state_cb callback, void *user_data);
 990
 991 API int vsm_del_state_callback(vsm_context_h ctx, int handle);
 992
 993 API int vsm_get_zone_terminal(vsm_zone_h zone);
 994
 995 #ifdef __cplusplus
 996 }
 997 #endif
 998
 999 #endif /*! __VASUM_H__ */