include/peripheral_io.h

   1 /*
   2  * Copyright (c) 2016-2017 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_SYSTEM_PERIPHERAL_IO_H__
  18 #define __TIZEN_SYSTEM_PERIPHERAL_IO_H__
  19
  20 #include <stdint.h>
  21 #include <tizen.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @file peripheral_io.h
  34  * @brief This file contains the peripheral-io API.
  35  */
  36
  37 /**
  38  * @brief Enumeration for peripheral-io error.
  39  * @since_tizen 4.0
  40  */
  41 typedef enum {
  42         PERIPHERAL_ERROR_NONE                = TIZEN_ERROR_NONE,                /**< Successful */
  43         PERIPHERAL_ERROR_IO_ERROR            = TIZEN_ERROR_IO_ERROR,            /**< I/O error */
  44         PERIPHERAL_ERROR_NO_DEVICE           = TIZEN_ERROR_NO_SUCH_DEVICE,      /**< No such device */
  45         PERIPHERAL_ERROR_TRY_AGAIN           = TIZEN_ERROR_TRY_AGAIN,           /**< Try again */
  46         PERIPHERAL_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,       /**< Out of memory */
  47         PERIPHERAL_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED,   /**< Permission denied */
  48         PERIPHERAL_ERROR_RESOURCE_BUSY       = TIZEN_ERROR_RESOURCE_BUSY,       /**< Device or resource busy */
  49         PERIPHERAL_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  50         PERIPHERAL_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,       /**< Not supported */
  51         PERIPHERAL_ERROR_UNKNOWN             = TIZEN_ERROR_UNKNOWN,             /**< Unknown error */
  52 } peripheral_error_e;
  53
  54 /**
  55 * @}
  56 */
  57
  58 /**
  59  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE
  60  * @{
  61  */
  62
  63 /**
  64  * @brief Enumeration of GPIO direction options.
  65  * @since_tizen 4.0
  66  */
  67 typedef enum {
  68         PERIPHERAL_GPIO_DIRECTION_IN = 0,              /**< Input Mode */
  69         PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_HIGH,  /**< Output mode with high value */
  70         PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW,   /**< Output mode with low value */
  71 } peripheral_gpio_direction_e;
  72
  73 /**
  74  * @brief Enumeration of edge types for the GPIO interrupt.
  75  * @since_tizen 4.0
  76  */
  77 typedef enum {
  78         PERIPHERAL_GPIO_EDGE_NONE = 0,  /**< No interrupt on GPIO */
  79         PERIPHERAL_GPIO_EDGE_RISING,    /**< Interrupt on rising only */
  80         PERIPHERAL_GPIO_EDGE_FALLING,   /**< Interrupt on falling only */
  81         PERIPHERAL_GPIO_EDGE_BOTH,      /**< Interrupt on rising & falling */
  82 } peripheral_gpio_edge_e;
  83
  84 /**
  85  * @brief The handle of a GPIO pin.
  86  * @since_tizen 4.0
  87  */
  88 typedef struct _peripheral_gpio_s *peripheral_gpio_h;
  89
  90 /**
  91  * @platform
  92  * @brief Opens a GPIO pin.
  93  * @since_tizen 4.0
  94  * @privlevel platform
  95  * @privilege http://tizen.org/privilege/peripheralio
  96  * @remarks @a gpio should be released with peripheral_gpio_close()
  97  *
  98  * @param[in] gpio_pin The GPIO pin number
  99  * @param[out] gpio The GPIO handle is created on success
 100  *
 101  * @return 0 on success, otherwise a negative error value
 102  * @retval #PERIPHERAL_ERROR_NONE Successful
 103  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 104  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 105  * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
 106  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 107  * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
 108  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 109  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 110  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 111  *
 112  * @post peripheral_gpio_close()
 113  */
 114 int peripheral_gpio_open(int gpio_pin, peripheral_gpio_h *gpio);
 115
 116 /**
 117  * @platform
 118  * @brief Closes a GPIO pin.
 119  * @since_tizen 4.0
 120  * @privlevel platform
 121  * @privilege http://tizen.org/privilege/peripheralio
 122  *
 123  * @param[in] gpio The GPIO handle
 124  *
 125  * @return 0 on success, otherwise a negative error value
 126  * @retval #PERIPHERAL_ERROR_NONE Successful
 127  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 128  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 129  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 130  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 131  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 132  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 133  *
 134  * @pre peripheral_gpio_open()
 135  */
 136 int peripheral_gpio_close(peripheral_gpio_h gpio);
 137
 138 /**
 139  * @platform
 140  * @brief Sets the GPIO direction.
 141  * @since_tizen 4.0
 142  * @privlevel platform
 143  * @privilege http://tizen.org/privilege/peripheralio
 144  *
 145  * @param[in] gpio The GPIO handle
 146  * @param[in] direction The direction of the GPIO pin
 147  *
 148  * @return 0 on success, otherwise a negative error value
 149  * @retval #PERIPHERAL_ERROR_NONE Successful
 150  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 151  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 152  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 153  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 154  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 155  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 156  *
 157  * @see peripheral_gpio_direction_e
 158  */
 159 int peripheral_gpio_set_direction(peripheral_gpio_h gpio, peripheral_gpio_direction_e direction);
 160
 161 /**
 162  * @platform
 163  * @brief Sets the GPIO edge mode.
 164  * @since_tizen 4.0
 165  * @privlevel platform
 166  * @privilege http://tizen.org/privilege/peripheralio
 167  *
 168  * @param[in] gpio The GPIO handle
 169  * @param[in] edge The edge mode of the GPIO pin
 170  *
 171  * @return 0 on success, otherwise a negative error value
 172  * @retval #PERIPHERAL_ERROR_NONE Successful
 173  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 174  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 175  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 176  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 178  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 179  *
 180  * @see peripheral_gpio_edge_e
 181  */
 182 int peripheral_gpio_set_edge_mode(peripheral_gpio_h gpio, peripheral_gpio_edge_e edge);
 183
 184 /**
 185  * @platform
 186  * @brief The GPIO interrupted callback called when the GPIO interrupt is triggered.
 187  * @since_tizen 4.0
 188  *
 189  * @param[in] gpio The GPIO handle
 190  * @param[in] error The GPIO error
 191  * @param[in] user_data The user data passed from the callback registration function
 192  *
 193  * @see peripheral_gpio_set_interrupted_cb()
 194  */
 195 typedef void(*peripheral_gpio_interrupted_cb)(peripheral_gpio_h gpio, peripheral_error_e error, void *user_data);
 196
 197 /**
 198  * @platform
 199  * @brief Sets the GPIO interrupted callback to be invoked when the GPIO interrupt is triggered.
 200  * @since_tizen 4.0
 201  * @privlevel platform
 202  * @privilege http://tizen.org/privilege/peripheralio
 203  *
 204  * @param[in] gpio The GPIO handle
 205  * @param[in] callback The GPIO interrupted callback function to set
 206  * @param[in] user_data The user data to be passed to the callback function
 207  *
 208  * @return 0 on success, otherwise a negative error value
 209  * @retval #PERIPHERAL_ERROR_NONE Successful
 210  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 211  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 213  *
 214  * @post peripheral_gpio_unset_interrupted_cb()
 215  * @see peripheral_gpio_set_edge_mode()
 216  */
 217 int peripheral_gpio_set_interrupted_cb(peripheral_gpio_h gpio, peripheral_gpio_interrupted_cb callback, void *user_data);
 218
 219 /**
 220  * @platform
 221  * @brief Unsets the GPIO interrupted callback.
 222  * @since_tizen 4.0
 223  * @privlevel platform
 224  * @privilege http://tizen.org/privilege/peripheralio
 225  *
 226  * @param[in] gpio The GPIO handle
 227  *
 228  * @return 0 on success, otherwise a negative error value
 229  * @retval #PERIPHERAL_ERROR_NONE Successful
 230  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 231  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 232  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 233  *
 234  * @pre peripheral_gpio_set_interrupted_cb()
 235  */
 236 int peripheral_gpio_unset_interrupted_cb(peripheral_gpio_h gpio);
 237
 238 /**
 239  * @platform
 240  * @brief Gets the current value of the GPIO pin.
 241  * @since_tizen 4.0
 242  * @privlevel platform
 243  * @privilege http://tizen.org/privilege/peripheralio
 244  *
 245  * @param[in] gpio The GPIO handle
 246  * @param[out] value The value to get
 247  *
 248  * @return 0 on success, otherwise a negative error value
 249  * @retval #PERIPHERAL_ERROR_NONE Successful
 250  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 251  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 252  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 253  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 254  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 255  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 256  *
 257  * @see peripheral_gpio_write()
 258  */
 259 int peripheral_gpio_read(peripheral_gpio_h gpio, uint32_t *value);
 260
 261 /**
 262  * @platform
 263  * @brief Sets the value of the GPIO pin.
 264  * @since_tizen 4.0
 265  * @privlevel platform
 266  * @privilege http://tizen.org/privilege/peripheralio
 267  *
 268  * @param[in] gpio The GPIO handle
 269  * @param[in] value The value to set (must be 0 or 1)
 270  *
 271  * @return 0 on success, otherwise a negative error value
 272  * @retval #PERIPHERAL_ERROR_NONE Successful
 273  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 274  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 275  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 276  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 277  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 278  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 279  *
 280  * @see peripheral_gpio_read()
 281  */
 282 int peripheral_gpio_write(peripheral_gpio_h gpio, uint32_t value);
 283
 284 /**
 285 * @}
 286 */
 287
 288 /**
 289  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE
 290  * @{
 291  */
 292
 293 /**
 294  * @brief The handle of the I2C slave device.
 295  * @since_tizen 4.0
 296  */
 297 typedef struct _peripheral_i2c_s *peripheral_i2c_h;
 298
 299 /**
 300  * @platform
 301  * @brief Opens an I2C slave device.
 302  * @since_tizen 4.0
 303  * @privlevel platform
 304  * @privilege http://tizen.org/privilege/peripheralio
 305  * @remarks @a i2c should be released with peripheral_i2c_close()
 306  *
 307  * @param[in] bus The I2C bus number that the slave device is connected
 308  * @param[in] address The address of the slave device
 309  * @param[out] i2c The I2C handle is created on success
 310  *
 311  * @return 0 on success, otherwise a negative error value
 312  * @retval #PERIPHERAL_ERROR_NONE Successful
 313  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 314  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 315  * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
 316  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 317  * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
 318  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 320  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 321  *
 322  * @post peripheral_i2c_close()
 323  */
 324 int peripheral_i2c_open(int bus, int address, peripheral_i2c_h *i2c);
 325
 326 /**
 327  * @platform
 328  * @brief Closes an I2C slave device.
 329  * @since_tizen 4.0
 330  * @privlevel platform
 331  * @privilege http://tizen.org/privilege/peripheralio
 332  *
 333  * @param[in] i2c The I2C handle
 334  *
 335  * @return 0 on success, otherwise a negative error value
 336  * @retval #PERIPHERAL_ERROR_NONE Successful
 337  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 338  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 339  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 340  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 341  *
 342  * @pre peripheral_i2c_open()
 343  */
 344 int peripheral_i2c_close(peripheral_i2c_h i2c);
 345
 346 /**
 347  * @platform
 348  * @brief Reads the bytes data from the I2C slave device.
 349  * @since_tizen 4.0
 350  * @privlevel platform
 351  * @privilege http://tizen.org/privilege/peripheralio
 352  *
 353  * @param[in] i2c The I2C handle
 354  * @param[out] data The data buffer to read
 355  * @param[in] length The size of data buffer (in bytes)
 356  *
 357  * @return 0 on success, otherwise a negative error value
 358  * @retval #PERIPHERAL_ERROR_NONE Successful
 359  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 360  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 361  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 362  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 363  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 364  *
 365  * @see peripheral_i2c_write()
 366  */
 367 int peripheral_i2c_read(peripheral_i2c_h i2c, uint8_t *data, uint32_t length);
 368
 369 /**
 370  * @platform
 371  * @brief Writes the bytes data to the I2C slave device.
 372  * @since_tizen 4.0
 373  * @privlevel platform
 374  * @privilege http://tizen.org/privilege/peripheralio
 375  *
 376  * @param[in] i2c The I2C handle
 377  * @param[in] data The data buffer to write
 378  * @param[in] length The size of data buffer (in bytes)
 379  *
 380  * @return 0 on success, otherwise a negative error value
 381  * @retval #PERIPHERAL_ERROR_NONE Successful
 382  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 383  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 384  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 385  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 386  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 387  *
 388  * @see peripheral_i2c_read()
 389  */
 390 int peripheral_i2c_write(peripheral_i2c_h i2c, uint8_t *data, uint32_t length);
 391
 392 /**
 393  * @platform
 394  * @brief Reads single byte data from the register of the I2C slave device.
 395  * @since_tizen 4.0
 396  * @privlevel platform
 397  * @privilege http://tizen.org/privilege/peripheralio
 398  *
 399  * @param[in] i2c The I2C handle
 400  * @param[in] reg The register address of the I2C slave device to read
 401  * @param[out] data The single byte data to read
 402  *
 403  * @return 0 on success, otherwise a negative error value
 404  * @retval #PERIPHERAL_ERROR_NONE Successful
 405  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 406  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 407  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 408  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 409  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 410  *
 411  * @see peripheral_i2c_write_register_byte()
 412  */
 413 int peripheral_i2c_read_register_byte(peripheral_i2c_h i2c, uint8_t reg, uint8_t *data);
 414
 415 /**
 416  * @platform
 417  * @brief Writes single byte data to the register of the I2C slave device.
 418  * @since_tizen 4.0
 419  * @privlevel platform
 420  * @privilege http://tizen.org/privilege/peripheralio
 421  *
 422  * @param[in] i2c The I2C handle
 423  * @param[in] reg The register address of the I2C slave device to write
 424  * @param[in] data The single byte data to write
 425  *
 426  * @return 0 on success, otherwise a negative error value
 427  * @retval #PERIPHERAL_ERROR_NONE Successful
 428  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 429  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 430  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 431  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 432  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 433  *
 434  * @see peripheral_i2c_read_register_byte()
 435  */
 436 int peripheral_i2c_write_register_byte(peripheral_i2c_h i2c, uint8_t reg, uint8_t data);
 437
 438 /**
 439  * @platform
 440  * @brief Reads word data from the register of the I2C slave device.
 441  * @since_tizen 4.0
 442  * @privlevel platform
 443  * @privilege http://tizen.org/privilege/peripheralio
 444  *
 445  * @param[in] i2c The I2C handle
 446  * @param[in] reg The register address of the I2C slave device to read
 447  * @param[out] data The word(2 bytes) data to read
 448  *
 449  * @return 0 on success, otherwise a negative error value
 450  * @retval #PERIPHERAL_ERROR_NONE Successful
 451  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 452  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 453  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 455  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 456  *
 457  * @see peripheral_i2c_write_register_word()
 458  */
 459 int peripheral_i2c_read_register_word(peripheral_i2c_h i2c, uint8_t reg, uint16_t *data);
 460
 461 /**
 462  * @platform
 463  * @brief Writes word data to the register of the I2C slave device.
 464  * @since_tizen 4.0
 465  * @privlevel platform
 466  * @privilege http://tizen.org/privilege/peripheralio
 467  *
 468  * @param[in] i2c The I2C handle
 469  * @param[in] reg The register address of the I2C slave device to write
 470  * @param[in] data The word(2 bytes) data to write
 471  *
 472  * @return 0 on success, otherwise a negative error value
 473  * @retval #PERIPHERAL_ERROR_NONE Successful
 474  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 475  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 476  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 477  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 478  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 479  *
 480  * @see peripheral_i2c_read_register_word()
 481  */
 482 int peripheral_i2c_write_register_word(peripheral_i2c_h i2c, uint8_t reg, uint16_t data);
 483
 484 /**
 485 * @}
 486 */
 487
 488 /**
 489  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE
 490  * @{
 491  */
 492
 493 /**
 494  * @brief The handle of the PWM peripherals.
 495  * @since_tizen 4.0
 496  */
 497 typedef struct _peripheral_pwm_s *peripheral_pwm_h;
 498
 499 /**
 500  * @brief Enumeration for Polarity.
 501  * @since_tizen 4.0
 502  */
 503 typedef enum {
 504         PERIPHERAL_PWM_POLARITY_ACTIVE_HIGH = 0, /**< PWM signal start in the active high state (Normal) */
 505         PERIPHERAL_PWM_POLARITY_ACTIVE_LOW,      /**< PWM signal start in the active low state (Inversed) */
 506 } peripheral_pwm_polarity_e;
 507
 508 /**
 509  * @platform
 510  * @brief Opens the PWM pin.
 511  * @since_tizen 4.0
 512  * @privlevel platform
 513  * @privilege http://tizen.org/privilege/peripheralio
 514  * @remarks @a pwm should be released with peripheral_pwm_close()
 515  *
 516  * @param[in] chip The PWM chip number
 517  * @param[in] pin The PWM pin(channel) number to control
 518  * @param[out] pwm The PWM handle is created on success
 519  *
 520  * @return 0 on success, otherwise a negative error value
 521  * @retval #PERIPHERAL_ERROR_NONE Successful
 522  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 523  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 524  * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
 525  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 526  * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
 527  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 528  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 529  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 530  *
 531  * @post peripheral_pwm_close()
 532  */
 533 int peripheral_pwm_open(int chip, int pin, peripheral_pwm_h *pwm);
 534
 535 /**
 536  * @platform
 537  * @brief Closes the PWM pin.
 538  * @since_tizen 4.0
 539  * @privlevel platform
 540  * @privilege http://tizen.org/privilege/peripheralio
 541  *
 542  * @param[in] pwm The PWM handle
 543  *
 544  * @return 0 on success, otherwise a negative error value
 545  * @retval #PERIPHERAL_ERROR_NONE Successful
 546  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 547  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 548  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 549  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 550  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 551  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 552  *
 553  * @pre peripheral_pwm_open()
 554  */
 555 int peripheral_pwm_close(peripheral_pwm_h pwm);
 556
 557 /**
 558  * @platform
 559  * @brief Sets period of the PWM pin.
 560  * @since_tizen 4.0
 561  * @privlevel platform
 562  * @privilege http://tizen.org/privilege/peripheralio
 563  *
 564  * @param[in] pwm The PWM handle
 565  * @param[in] period_ns The total period of the PWM pin (in nanoseconds)
 566  *
 567  * @return 0 on success, otherwise a negative error value
 568  * @retval #PERIPHERAL_ERROR_NONE Successful
 569  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 570  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 571  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 572  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 573  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 574  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 575  */
 576 int peripheral_pwm_set_period(peripheral_pwm_h pwm, uint32_t period_ns);
 577
 578 /**
 579  * @platform
 580  * @brief Sets duty cycle of the PWM pin.
 581  * @since_tizen 4.0
 582  * @privlevel platform
 583  * @privilege http://tizen.org/privilege/peripheralio
 584  *
 585  * @param[in] pwm The PWM handle
 586  * @param[in] duty_cycle_ns The duty cycle of the PWM pin (in nanoseconds)
 587  *
 588  * @return 0 on success, otherwise a negative error value
 589  * @retval #PERIPHERAL_ERROR_NONE Successful
 590  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 591  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 592  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 593  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 594  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 595  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 596  */
 597 int peripheral_pwm_set_duty_cycle(peripheral_pwm_h pwm, uint32_t duty_cycle_ns);
 598
 599 /**
 600  * @platform
 601  * @brief Sets polarity of the PWM pin.
 602  * @since_tizen 4.0
 603  * @privlevel platform
 604  * @privilege http://tizen.org/privilege/peripheralio
 605  *
 606  * @param[in] pwm The PWM handle
 607  * @param[in] polarity The polarity of the PWM pin
 608  *
 609  * @return 0 on success, otherwise a negative error value
 610  * @retval #PERIPHERAL_ERROR_NONE Successful
 611  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 612  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 613  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 614  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 615  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 616  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 617  *
 618  * @see peripheral_pwm_polarity_e
 619  */
 620 int peripheral_pwm_set_polarity(peripheral_pwm_h pwm, peripheral_pwm_polarity_e polarity);
 621
 622 /**
 623  * @platform
 624  * @brief Enables the PWM pin.
 625  * @since_tizen 4.0
 626  * @privlevel platform
 627  * @privilege http://tizen.org/privilege/peripheralio
 628  *
 629  * @param[in] pwm The PWM handle
 630  * @param[in] enabled Enable/disable the PWM pin
 631  *
 632  * @return 0 on success, otherwise a negative error value
 633  * @retval #PERIPHERAL_ERROR_NONE Successful
 634  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 635  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 636  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 637  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 638  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 639  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 640  */
 641 int peripheral_pwm_set_enabled(peripheral_pwm_h pwm, bool enabled);
 642
 643 /**
 644 * @}
 645 */
 646
 647 /**
 648  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE
 649  * @{
 650  */
 651
 652 /**
 653  * @brief The handle to the UART peripherals.
 654  * @since_tizen 4.0
 655  */
 656 typedef struct _peripheral_uart_s *peripheral_uart_h;
 657
 658 /**
 659  * @brief Enumeration for baud rate.
 660  * @since_tizen 4.0
 661  */
 662 typedef enum {
 663         PERIPHERAL_UART_BAUD_RATE_0 = 0,  /**< The number of signal in one second is 0 */
 664         PERIPHERAL_UART_BAUD_RATE_50,     /**< The number of signal in one second is 50 */
 665         PERIPHERAL_UART_BAUD_RATE_75,     /**< The number of signal in one second is 75 */
 666         PERIPHERAL_UART_BAUD_RATE_110,    /**< The number of signal in one second is 110 */
 667         PERIPHERAL_UART_BAUD_RATE_134,    /**< The number of signal in one second is 134 */
 668         PERIPHERAL_UART_BAUD_RATE_150,    /**< The number of signal in one second is 150 */
 669         PERIPHERAL_UART_BAUD_RATE_200,    /**< The number of signal in one second is 200 */
 670         PERIPHERAL_UART_BAUD_RATE_300,    /**< The number of signal in one second is 300 */
 671         PERIPHERAL_UART_BAUD_RATE_600,    /**< The number of signal in one second is 600 */
 672         PERIPHERAL_UART_BAUD_RATE_1200,   /**< The number of signal in one second is 1200 */
 673         PERIPHERAL_UART_BAUD_RATE_1800,   /**< The number of signal in one second is 1800 */
 674         PERIPHERAL_UART_BAUD_RATE_2400,   /**< The number of signal in one second is 2400 */
 675         PERIPHERAL_UART_BAUD_RATE_4800,   /**< The number of signal in one second is 4800 */
 676         PERIPHERAL_UART_BAUD_RATE_9600,   /**< The number of signal in one second is 9600 */
 677         PERIPHERAL_UART_BAUD_RATE_19200,  /**< The number of signal in one second is 19200 */
 678         PERIPHERAL_UART_BAUD_RATE_38400,  /**< The number of signal in one second is 38400 */
 679         PERIPHERAL_UART_BAUD_RATE_57600,  /**< The number of signal in one second is 57600 */
 680         PERIPHERAL_UART_BAUD_RATE_115200, /**< The number of signal in one second is 115200 */
 681         PERIPHERAL_UART_BAUD_RATE_230400, /**< The number of signal in one second is 230400 */
 682 } peripheral_uart_baud_rate_e;
 683
 684 /**
 685  * @brief Enumeration for byte size.
 686  * @since_tizen 4.0
 687  */
 688 typedef enum {
 689         PERIPHERAL_UART_BYTE_SIZE_5BIT = 0, /**< 5 data bits */
 690         PERIPHERAL_UART_BYTE_SIZE_6BIT,     /**< 6 data bits */
 691         PERIPHERAL_UART_BYTE_SIZE_7BIT,     /**< 7 data bits */
 692         PERIPHERAL_UART_BYTE_SIZE_8BIT,     /**< 8 data bits */
 693 } peripheral_uart_byte_size_e;
 694
 695 /**
 696  * @brief Enumeration for parity bit.
 697  * @since_tizen 4.0
 698  */
 699 typedef enum {
 700         PERIPHERAL_UART_PARITY_NONE = 0, /**< No parity is used */
 701         PERIPHERAL_UART_PARITY_EVEN,     /**< Even parity is used */
 702         PERIPHERAL_UART_PARITY_ODD,      /**< ODD parity is used */
 703 } peripheral_uart_parity_e;
 704
 705 /**
 706  * @brief Enumeration for stop bits.
 707  * @since_tizen 4.0
 708  */
 709 typedef enum {
 710         PERIPHERAL_UART_STOP_BITS_1BIT = 0, /**< One stop bit */
 711         PERIPHERAL_UART_STOP_BITS_2BIT,     /**< Two stop bits */
 712 } peripheral_uart_stop_bits_e;
 713
 714 /**
 715  * @brief Enumeration for hardware flow control.
 716  * @since_tizen 4.0
 717  */
 718 typedef enum {
 719         PERIPHERAL_UART_HARDWARE_FLOW_CONTROL_NONE = 0,    /**< No hardware flow control */
 720         PERIPHERAL_UART_HARDWARE_FLOW_CONTROL_AUTO_RTSCTS, /**< Automatic RTS/CTS hardware flow control*/
 721 } peripheral_uart_hardware_flow_control_e;
 722
 723 /**
 724  * @brief Enumeration for software flow control.
 725  * @since_tizen 4.0
 726  */
 727 typedef enum {
 728         PERIPHERAL_UART_SOFTWARE_FLOW_CONTROL_NONE = 0,    /**< No software flow control */
 729         PERIPHERAL_UART_SOFTWARE_FLOW_CONTROL_XONXOFF,     /**< XON/XOFF software flow control */
 730 } peripheral_uart_software_flow_control_e;
 731
 732 /**
 733  * @platform
 734  * @brief Opens the UART slave device.
 735  * @since_tizen 4.0
 736  * @privlevel platform
 737  * @privilege http://tizen.org/privilege/peripheralio
 738  * @remarks @a uart should be released with peripheral_uart_close()
 739  *
 740  * @param[in] port The UART port number that the slave device is connected
 741  * @param[out] uart The UART handle is created on success
 742  *
 743  * @return 0 on success, otherwise a negative error value
 744  * @retval #PERIPHERAL_ERROR_NONE Successful
 745  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 746  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 747  * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
 748  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 749  * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
 750  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 751  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 752  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 753  *
 754  * @post peripheral_uart_close()
 755  */
 756 int peripheral_uart_open(int port, peripheral_uart_h *uart);
 757
 758 /**
 759  * @platform
 760  * @brief Closes the UART slave device.
 761  * @since_tizen 4.0
 762  * @privlevel platform
 763  * @privilege http://tizen.org/privilege/peripheralio
 764  *
 765  * @param[in] uart The UART handle
 766  *
 767  * @return 0 on success, otherwise a negative error value
 768  * @retval #PERIPHERAL_ERROR_NONE Successful
 769  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 770  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 771  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 772  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 773  *
 774  * @pre peripheral_uart_open()
 775  */
 776 int peripheral_uart_close(peripheral_uart_h uart);
 777
 778 /**
 779  * @platform
 780  * @brief Sets baud rate of the UART slave device.
 781  * @since_tizen 4.0
 782  * @privlevel platform
 783  * @privilege http://tizen.org/privilege/peripheralio
 784  *
 785  * @param[in] uart The UART handle
 786  * @param[in] baud Baud rate of the UART slave device
 787  *
 788  * @return 0 on success, otherwise a negative error value
 789  * @retval #PERIPHERAL_ERROR_NONE Successful
 790  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 791  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 792  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 793  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 794  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 795  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 796  *
 797  * @see peripheral_uart_baud_rate_e
 798  */
 799 int peripheral_uart_set_baud_rate(peripheral_uart_h uart, peripheral_uart_baud_rate_e baud);
 800
 801 /**
 802  * @platform
 803  * @brief Sets byte size of the UART slave device.
 804  * @since_tizen 4.0
 805  * @privlevel platform
 806  * @privilege http://tizen.org/privilege/peripheralio
 807  *
 808  * @param[in] uart The UART handle
 809  * @param[in] byte_size Byte size of the UART slave device
 810  *
 811  * @return 0 on success, otherwise a negative error value
 812  * @retval #PERIPHERAL_ERROR_NONE Successful
 813  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 814  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 815  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 816  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 817  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 818  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 819  *
 820  * @see peripheral_uart_byte_size_e
 821  */
 822 int peripheral_uart_set_byte_size(peripheral_uart_h uart, peripheral_uart_byte_size_e byte_size);
 823
 824 /**
 825  * @platform
 826  * @brief Sets parity bit of the UART slave device.
 827  * @since_tizen 4.0
 828  * @privlevel platform
 829  * @privilege http://tizen.org/privilege/peripheralio
 830  *
 831  * @param[in] uart The UART handle
 832  * @param[in] parity Parity bit of the UART slave device
 833  *
 834  * @return 0 on success, otherwise a negative error value
 835  * @retval #PERIPHERAL_ERROR_NONE Successful
 836  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 837  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 838  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 839  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 840  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 841  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 842  *
 843  * @see peripheral_uart_parity_e
 844  */
 845 int peripheral_uart_set_parity(peripheral_uart_h uart, peripheral_uart_parity_e parity);
 846
 847 /**
 848  * @platform
 849  * @brief Sets stop bits of the UART slave device.
 850  * @since_tizen 4.0
 851  * @privlevel platform
 852  * @privilege http://tizen.org/privilege/peripheralio
 853  *
 854  * @param[in] uart The UART handle
 855  * @param[in] stop_bits Stop bits of the UART slave device
 856  *
 857  * @return 0 on success, otherwise a negative error value
 858  * @retval #PERIPHERAL_ERROR_NONE Successful
 859  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 860  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 861  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 862  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 863  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 864  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 865  *
 866  * @see peripheral_uart_stop_bits_e
 867  */
 868 int peripheral_uart_set_stop_bits(peripheral_uart_h uart, peripheral_uart_stop_bits_e stop_bits);
 869
 870 /**
 871  * @platform
 872  * @brief Sets flow control of the UART slave device.
 873  * @since_tizen 4.0
 874  * @privlevel platform
 875  * @privilege http://tizen.org/privilege/peripheralio
 876  *
 877  * @param[in] uart The UART handle
 878  * @param[in] sw_flow_control Software flow control (Turns a transmitter on or off)
 879  * @param[in] hw_flow_control Hardware flow control (Turns "Request to Send/Clear to Send" on or off)
 880  *
 881  * @return 0 on success, otherwise a negative error value
 882  * @retval #PERIPHERAL_ERROR_NONE Successful
 883  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 884  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 885  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 886  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 887  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 888  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 889  *
 890  * @see peripheral_uart_software_flow_control_e
 891  * @see peripheral_uart_hardware_flow_control_e
 892  */
 893 int peripheral_uart_set_flow_control(peripheral_uart_h uart,
 894                         peripheral_uart_software_flow_control_e sw_flow_control,
 895                         peripheral_uart_hardware_flow_control_e hw_flow_control);
 896
 897 /**
 898  * @platform
 899  * @brief Reads data from the UART slave device.
 900  * @since_tizen 4.0
 901  * @privlevel platform
 902  * @privilege http://tizen.org/privilege/peripheralio
 903  *
 904  * @param[in] uart The UART handle
 905  * @param[out] data The buffer to read
 906  * @param[out] length The size of buffer (in bytes)
 907  *
 908  * @return the number of bytes read on success, otherwise a negative error value
 909  * @retval #PERIPHERAL_ERROR_NONE Successful
 910  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 911  * @retval #PERIPHERAL_ERROR_TRY_AGAIN Try again
 912  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 913  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 914  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 915  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 916  *
 917  * @see peripheral_uart_write()
 918  */
 919 int peripheral_uart_read(peripheral_uart_h uart, uint8_t *data, uint32_t length);
 920
 921 /**
 922  * @platform
 923  * @brief Writes data to the UART slave device.
 924  * @since_tizen 4.0
 925  * @privlevel platform
 926  * @privilege http://tizen.org/privilege/peripheralio
 927  *
 928  * @param[in] uart The UART handle
 929  * @param[in] data The buffer to write
 930  * @param[in] length The size of buffer (in bytes)
 931  *
 932  * @return the number of bytes write on success, otherwise a negative error value
 933  * @retval #PERIPHERAL_ERROR_NONE Successful
 934  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 935  * @retval #PERIPHERAL_ERROR_TRY_AGAIN Try again
 936  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 937  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
 938  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
 939  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
 940  *
 941  * @see peripheral_uart_read()
 942  */
 943 int peripheral_uart_write(peripheral_uart_h uart, uint8_t *data, uint32_t length);
 944
 945 /**
 946 * @}
 947 */
 948
 949 /**
 950  * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE
 951  * @{
 952  */
 953
 954 /**
 955  * @brief The handle of a SPI peripherals.
 956  * @since_tizen 4.0
 957  */
 958 typedef struct _peripheral_spi_s *peripheral_spi_h;
 959
 960 /**
 961  * @brief Enumeration of SPI transfer modes.
 962  * @since_tizen 4.0
 963  */
 964 typedef enum {
 965         PERIPHERAL_SPI_MODE_0 = 0,   /**< CPOL = 0, CPHa = 0 Mode */
 966         PERIPHERAL_SPI_MODE_1,       /**< CPOL = 0, CPHa = 1 Mode */
 967         PERIPHERAL_SPI_MODE_2,       /**< CPOL = 1, CPHa = 0 Mode */
 968         PERIPHERAL_SPI_MODE_3,       /**< CPOL = 1, CPHa = 1 Mode */
 969 } peripheral_spi_mode_e;
 970
 971 /**
 972  * @brief Enumeration of bit orders.
 973  * @since_tizen 4.0
 974  */
 975 typedef enum {
 976         PERIPHERAL_SPI_BIT_ORDER_MSB = 0, /**< Use most siginificant bit first */
 977         PERIPHERAL_SPI_BIT_ORDER_LSB,     /**< Use least significant bit first */
 978 } peripheral_spi_bit_order_e;
 979
 980 /**
 981  * @platform
 982  * @brief Opens a SPI slave device.
 983  * @since_tizen 4.0
 984  * @privlevel platform
 985  * @privilege http://tizen.org/privilege/peripheralio
 986  * @remarks @a spi should be released with peripheral_spi_close()
 987  *
 988  * @param[in] bus The SPI bus number
 989  * @param[in] cs The SPI chip select number
 990  * @param[out] spi The SPI slave device handle
 991  *
 992  * @return 0 on success, otherwise a negative error value
 993  * @retval #PERIPHERAL_ERROR_NONE Successful
 994  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
 995  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
 996  * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed
 997  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
 998  * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use
 999  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1000  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1001  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1002  *
1003  * @post peripheral_spi_close()
1004  */
1005 int peripheral_spi_open(int bus, int cs, peripheral_spi_h *spi);
1006
1007 /**
1008  * @platform
1009  * @brief Closes the SPI slave device.
1010  * @since_tizen 4.0
1011  * @privlevel platform
1012  * @privilege http://tizen.org/privilege/peripheralio
1013  *
1014  * @param[in] spi The SPI slave device handle
1015  *
1016  * @return 0 on success, otherwise a negative error value
1017  * @retval #PERIPHERAL_ERROR_NONE Successful
1018  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1019  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1020  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1021  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1022  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1023  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1024  *
1025  * @see peripheral_spi_open()
1026  */
1027 int peripheral_spi_close(peripheral_spi_h spi);
1028
1029 /**
1030  * @platform
1031  * @brief Sets the SPI transfer mode.
1032  * @since_tizen 4.0
1033  * @privlevel platform
1034  * @privilege http://tizen.org/privilege/peripheralio
1035  *
1036  * @param[in] spi The SPI slave device handle
1037  * @param[in] mode The SPI transfer mode
1038  *
1039  * @return 0 on success, otherwise a negative error value
1040  * @retval #PERIPHERAL_ERROR_NONE Successful
1041  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1042  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1043  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1044  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1045  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1046  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1047  *
1048  * @see peripheral_spi_mode_e
1049  */
1050 int peripheral_spi_set_mode(peripheral_spi_h spi, peripheral_spi_mode_e mode);
1051
1052 /**
1053  * @platform
1054  * @brief Sets the SPI bit order.
1055  * @since_tizen 4.0
1056  * @privlevel platform
1057  * @privilege http://tizen.org/privilege/peripheralio
1058  *
1059  * @param[in] spi The SPI slave device handle
1060  * @param[in] bit_order The transfer bit order
1061  *
1062  * @return 0 on success, otherwise a negative error value
1063  * @retval #PERIPHERAL_ERROR_NONE Successful
1064  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1065  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1066  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1067  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1068  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1069  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1070  *
1071  * @see peripheral_spi_bit_order_e
1072  */
1073 int peripheral_spi_set_bit_order(peripheral_spi_h spi, peripheral_spi_bit_order_e bit_order);
1074
1075 /**
1076  * @platform
1077  * @brief Sets the number of bits per word.
1078  * @since_tizen 4.0
1079  * @privlevel platform
1080  * @privilege http://tizen.org/privilege/peripheralio
1081  *
1082  * @param[in] spi The SPI slave device handle
1083  * @param[in] bits The number of bits per word (in bits)
1084  *
1085  * @return 0 on success, otherwise a negative error value
1086  * @retval #PERIPHERAL_ERROR_NONE Successful
1087  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1088  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1089  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1090  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1091  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1092  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1093  */
1094 int peripheral_spi_set_bits_per_word(peripheral_spi_h spi, uint8_t bits);
1095
1096 /**
1097  * @platform
1098  * @brief Sets the frequency of the SPI bus.
1099  * @since_tizen 4.0
1100  * @privlevel platform
1101  * @privilege http://tizen.org/privilege/peripheralio
1102  * @remarks The frequencies supported are board dependent.
1103  *
1104  * @param[in] spi The SPI slave device handle
1105  * @param[in] freq_hz Frequency to set (in Hz)
1106  *
1107  * @return 0 on success, otherwise a negative error value
1108  * @retval #PERIPHERAL_ERROR_NONE Successful
1109  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1110  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1111  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1112  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1113  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1114  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1115  */
1116 int peripheral_spi_set_frequency(peripheral_spi_h spi, uint32_t freq_hz);
1117
1118 /**
1119  * @platform
1120  * @brief Reads the bytes data from the SPI slave device.
1121  * @since_tizen 4.0
1122  * @privlevel platform
1123  * @privilege http://tizen.org/privilege/peripheralio
1124  *
1125  * @param[in] spi The SPI slave device handle
1126  * @param[out] data The data buffer to read
1127  * @param[in] length The size of data buffer (in bytes)
1128  *
1129  * @return 0 on success, otherwise a negative error value
1130  * @retval #PERIPHERAL_ERROR_NONE Successful
1131  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1132  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1133  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1134  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1135  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1136  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1137  *
1138  * @see peripheral_spi_write()
1139  */
1140 int peripheral_spi_read(peripheral_spi_h spi, uint8_t *data, uint32_t length);
1141
1142 /**
1143  * @platform
1144  * @brief Writes the bytes data to the SPI slave device.
1145  * @since_tizen 4.0
1146  * @privlevel platform
1147  * @privilege http://tizen.org/privilege/peripheralio
1148  *
1149  * @param[in] spi The SPI slave device handle
1150  * @param[in] data The data buffer to write
1151  * @param[in] length The size of data buffer (in bytes)
1152  *
1153  * @return 0 on success, otherwise a negative error value
1154  * @retval #PERIPHERAL_ERROR_NONE Successful
1155  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1156  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1157  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1158  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1159  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1160  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1161  *
1162  * @see peripheral_spi_read()
1163  */
1164 int peripheral_spi_write(peripheral_spi_h spi, uint8_t *data, uint32_t length);
1165
1166 /**
1167  * @platform
1168  * @brief Exchanges the bytes data to the SPI slave device.
1169  * @since_tizen 4.0
1170  * @privlevel platform
1171  * @privilege http://tizen.org/privilege/peripheralio
1172  *
1173  * @param[in] spi The SPI slave device handle
1174  * @param[in] txdata The data buffer to write
1175  * @param[out] rxdata The data buffer to read
1176  * @param[in] length The size of txdata and rxdata buffer (in bytes)
1177  *
1178  * @return 0 on success, otherwise a negative error value
1179  * @retval #PERIPHERAL_ERROR_NONE Successful
1180  * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed
1181  * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed
1182  * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied
1183  * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter
1184  * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported
1185  * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error
1186  *
1187  * @see peripheral_spi_read()
1188  * @see peripheral_spi_write()
1189  */
1190 int peripheral_spi_transfer(peripheral_spi_h spi, uint8_t *txdata, uint8_t *rxdata, uint32_t length);
1191
1192 /**
1193 * @}
1194 */
1195
1196 #ifdef __cplusplus
1197 }
1198 #endif
1199
1200 #endif /* __TIZEN_SYSTEM_PERIPHERAL_IO_H__ */