From 24831d9548318f4707a4d98a603952287fbeeb70 Mon Sep 17 00:00:00 2001 From: Segwon Date: Thu, 24 Aug 2017 19:39:51 +0900 Subject: [PATCH] api: modified with new API set. - ADC not supported - Provides get list API to get necessary for open APIs - Remove unnecessary and uncertain APIs - Terminology unification - Add peripheral_io_doc.h for doxygen - Add feature key and privilege level to doxygen Signed-off-by: Segwon Change-Id: Ie104753f270fdcc37df62e538c9ee06d254c2db2 --- doc/peripheral_io_doc.h | 173 ++++++++ include/peripheral_io.h | 1096 +++++++++++++++++++++++++---------------------- 2 files changed, 753 insertions(+), 516 deletions(-) create mode 100644 doc/peripheral_io_doc.h diff --git a/doc/peripheral_io_doc.h b/doc/peripheral_io_doc.h new file mode 100644 index 0000000..8c373bf --- /dev/null +++ b/doc/peripheral_io_doc.h @@ -0,0 +1,173 @@ +/* + * Copyright (c) 2017 Samsung Electronics Co., Ltd. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @ingroup CAPI_SYSTEM_FRAMEWORK + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE Peripheral IO + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_MODULE API provides functions to make use of peripherals in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_MODULE_OVERVIEW Overview + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_MODULE API provides access to the low level device providers, + * including GPIO, I2C, PWM, UART and SPI. + */ + + +/** + * @ingroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE GPIO + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE API provides functions to control GPIO in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE_OVERVIEW Overview + * + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE API provides functions to control GPIO in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE_FEATURE Realted Features + * + * This API is related with the following feature:\n + * - http://tizen.org/feature/peripheralio.gpio\n + * + * It is recommended to use features in your application for reliability.\n + * + * You can check if a device supports the related features for this API \n + * by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, \n + * please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + */ + + +/** + * @ingroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE I2C + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE API provides functions to control I2C in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE_OVERVIEW Overview + * + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE API provides functions to control I2C in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE_FEATURE Realted Features + * + * This API is related with the following feature:\n + * - http://tizen.org/feature/peripheralio.i2c\n + * + * It is recommended to use features in your application for reliability.\n + * + * You can check if a device supports the related features for this API \n + * by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, \n + * please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + */ + + +/** + * @ingroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE SPI + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE API provides functions to control SPI in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE_OVERVIEW Overview + * + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE API provides functions to control SPI in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE_FEATURE Realted Features + * + * This API is related with the following feature:\n + * - http://tizen.org/feature/peripheralio.spi\n + * + * It is recommended to use features in your application for reliability.\n + * + * You can check if a device supports the related features for this API \n + * by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, \n + * please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + */ + + +/** + * @ingroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE UART + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE API provides functions to control UART in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE_OVERVIEW Overview + * + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE API provides functions to control UART in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE_FEATURE Realted Features + * + * This API is related with the following feature:\n + * - http://tizen.org/feature/peripheralio.uart\n + * + * It is recommended to use features in your application for reliability.\n + * + * You can check if a device supports the related features for this API \n + * by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, \n + * please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + */ + + +/** + * @ingroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @defgroup CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE PWM + * @brief The @ref CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE API provides functions to control PWM in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE_HEADER Required Header + * \#include + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE_OVERVIEW Overview + * + * This @ref CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE API provides functions to control PWM in the device. + * + * @section CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE_FEATURE Realted Features + * + * This API is related with the following feature:\n + * - http://tizen.org/feature/peripheralio.pwm\n + * + * It is recommended to use features in your application for reliability.\n + * + * You can check if a device supports the related features for this API \n + * by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, and control your application's actions accordingly.\n + * + * To ensure your application is only running on the device with specific features, \n + * please define the features in your manifest file using the manifest editor in the SDK.\n + * + * More details on featuring your application can be found from Feature Element. + */ diff --git a/include/peripheral_io.h b/include/peripheral_io.h index d697a55..7ff48d4 100644 --- a/include/peripheral_io.h +++ b/include/peripheral_io.h @@ -14,8 +14,8 @@ * limitations under the License. */ -#ifndef __PERIPHERAL_IO_H__ -#define __PERIPHERAL_IO_H__ +#ifndef __TIZEN_SYSTEM_PERIPHERAL_IO_H__ +#define __TIZEN_SYSTEM_PERIPHERAL_IO_H__ #include #include @@ -25,1105 +25,1169 @@ extern "C" { #endif /** + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_MODULE + * @{ + */ + +/** * @file peripheral_io.h - * @brief This file contains the peripheral-io API + * @brief This file contains the peripheral-io API. */ /** * @brief Enumeration for peripheral-io error. - * @since_tizen + * @since_tizen 4.0 */ typedef enum { PERIPHERAL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ PERIPHERAL_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */ PERIPHERAL_ERROR_NO_DEVICE = TIZEN_ERROR_NO_SUCH_DEVICE, /**< No such device */ + PERIPHERAL_ERROR_TRY_AGAIN = TIZEN_ERROR_TRY_AGAIN, /**< Try again */ PERIPHERAL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ PERIPHERAL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ PERIPHERAL_ERROR_RESOURCE_BUSY = TIZEN_ERROR_RESOURCE_BUSY, /**< Device or resource busy */ PERIPHERAL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - PERIPHERAL_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data available */ - PERIPHERAL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Function not implemented */ - PERIPHERAL_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< Time out */ PERIPHERAL_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */ PERIPHERAL_ERROR_UNKNOWN = TIZEN_ERROR_UNKNOWN, /**< Unknown error */ } peripheral_error_e; /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_GPIO_MODULE +* @} +*/ + +/** + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_GPIO_MODULE * @{ */ /** - * @brief Enumeration of gpio direction + * @brief Enumeration of GPIO direction options. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_GPIO_DIRECTION_IN = 0, /**< Input Mode */ - PERIPHERAL_GPIO_DIRECTION_OUT, /**< Output mode with low value */ - PERIPHERAL_GPIO_DIRECTION_OUT_LOW = PERIPHERAL_GPIO_DIRECTION_OUT, /**< Same as above */ - PERIPHERAL_GPIO_DIRECTION_OUT_HIGH, /**< Output mode with high value */ + PERIPHERAL_GPIO_DIRECTION_IN = 0, /**< Input Mode */ + PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_HIGH, /**< Output mode with high value */ + PERIPHERAL_GPIO_DIRECTION_OUT_INITIALLY_LOW, /**< Output mode with low value */ } peripheral_gpio_direction_e; /** - * @brief Enumeration of edge type for gpio interrupt + * @brief Enumeration of edge types for the GPIO interrupt. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_GPIO_EDGE_NONE = 0, /**< No interrupt on Gpio */ + PERIPHERAL_GPIO_EDGE_NONE = 0, /**< No interrupt on GPIO */ PERIPHERAL_GPIO_EDGE_RISING, /**< Interrupt on rising only */ PERIPHERAL_GPIO_EDGE_FALLING, /**< Interrupt on falling only */ PERIPHERAL_GPIO_EDGE_BOTH, /**< Interrupt on rising & falling */ } peripheral_gpio_edge_e; /** - * @brief Gpio isr callback data delivered via gpio_isr_cb(). - * @details A gpio isr callback data is delivered as a structure, which contains - * the pin number, the pin value, and the timestamp of the gpio interrupt - * in microseconds. + * @brief The handle of a GPIO pin. * @since_tizen 4.0 */ -typedef struct { - int pin; - int value; - unsigned long long timestamp; -} gpio_isr_cb_s; +typedef struct _peripheral_gpio_s *peripheral_gpio_h; /** - * @brief The handle to the gpio pin - * @since_tizen 4.0 - */ -typedef struct _peripheral_gpio_s* peripheral_gpio_h; - -/** - * @brief Initializes(export) gpio pin and creates gpio handle. + * @platform + * @brief Opens a GPIO pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks @a gpio should be released with peripheral_gpio_close() * - * @param[in] gpio_pin The gpio pin number - * @param[out] gpio The gpio handle is created on success + * @param[in] gpio_pin The GPIO pin number + * @param[out] gpio The GPIO handle is created on success * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied + * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_gpio_close() + * @post peripheral_gpio_close() */ int peripheral_gpio_open(int gpio_pin, peripheral_gpio_h *gpio); /** - * @brief Releases the gpio handle and finalize(unexport) the gpio pin. + * @platform + * @brief Closes a GPIO pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin to release + * @param[in] gpio The GPIO handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_gpio_open() + * @pre peripheral_gpio_open() */ int peripheral_gpio_close(peripheral_gpio_h gpio); /** - * @brief Gets direction of the gpio. + * @platform + * @brief Sets the GPIO direction. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin - * @param[out] value The direction(value) type of the gpio + * @param[in] gpio The GPIO handle + * @param[in] direction The direction of the GPIO pin * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_gpio_set_direction() - */ -int peripheral_gpio_get_direction(peripheral_gpio_h gpio, peripheral_gpio_direction_e *direction); - -/** - * @brief Sets direction of the gpio pin. - * @since_tizen 4.0 - * - * @param[in] gpio The handle to the gpio pin to set - * @param[in] direction Direction(value) type of the gpio pin - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @see peripheral_gpio_direction_e */ int peripheral_gpio_set_direction(peripheral_gpio_h gpio, peripheral_gpio_direction_e direction); /** - * @brief Reads value of the gpio. + * @platform + * @brief Sets the GPIO edge mode. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin - * @param[out] value The value of the gpio (zero or non-zero) + * @param[in] gpio The GPIO handle + * @param[in] edge The edge mode of the GPIO pin * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_gpio_write() + * @see peripheral_gpio_edge_e */ -int peripheral_gpio_read(peripheral_gpio_h gpio, int *value); +int peripheral_gpio_set_edge_mode(peripheral_gpio_h gpio, peripheral_gpio_edge_e edge); /** - * @brief Writes value to the gpio. + * @platform + * @brief The GPIO interrupted callback called when the GPIO interrupt is triggered. * @since_tizen 4.0 * - * @param[in] gpio The handle to the gpio pin - * @param[in] value Value to be written to the gpio (muse be zero or non-zero) - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @param[in] gpio The GPIO handle + * @param[in] error The GPIO error + * @param[in] user_data The user data passed from the callback registration function * - * @see peripheral_gpio_read() + * @see peripheral_gpio_set_interrupted_cb() */ -int peripheral_gpio_write(peripheral_gpio_h gpio, int value); +typedef void(*peripheral_gpio_interrupted_cb)(peripheral_gpio_h gpio, peripheral_error_e error, void *user_data); /** - * @brief Gets the edge mode of the gpio. + * @platform + * @brief Sets the GPIO interrupted callback to be invoked when the GPIO interrupt is triggered. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin - * @param[out] gpio_pin The edge mode of the gpio + * @param[in] gpio The GPIO handle + * @param[in] callback The GPIO interrupted callback function to set + * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * + * @post peripheral_gpio_unset_interrupted_cb() * @see peripheral_gpio_set_edge_mode() */ -int peripheral_gpio_get_edge_mode(peripheral_gpio_h gpio, peripheral_gpio_edge_e *edge); +int peripheral_gpio_set_interrupted_cb(peripheral_gpio_h gpio, peripheral_gpio_interrupted_cb callback, void *user_data); /** - * @brief Sets the edge mode of the gpio pin. + * @platform + * @brief Unsets the GPIO interrupted callback. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin to set - * @param[in] edge The edge mode of the gpio pin + * @param[in] gpio The GPIO handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - * - * @see peripheral_gpio_get_edge_mode() - */ -int peripheral_gpio_set_edge_mode(peripheral_gpio_h gpio, peripheral_gpio_edge_e edge); - -/** - * @brief Called when the gpio interrupt is triggered. - * @since_tizen 4.0 + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * - * @param[in] data The gpio isr callback data - * @param[in] user_data The user data passed from the callback registration function - * - * @see peripheral_gpio_register_cb() - * @see peripheral_gpio_unregister_cb() + * @pre peripheral_gpio_set_interrupted_cb() */ -typedef void(*gpio_isr_cb)(gpio_isr_cb_s *data, void *user_data); +int peripheral_gpio_unset_interrupted_cb(peripheral_gpio_h gpio); /** - * @brief Registers a callback function to be invoked when the gpio interrupt is triggered. + * @platform + * @brief Gets the current value of the GPIO pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin to set - * @param[in] edge The edge type of the gpio pin - * @param[in] callback The callback function to register - * @param[in] user_data The user data to be passed to the callback function + * @param[in] gpio The GPIO handle + * @param[out] value The value to get * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error * - * @see peripheral_gpio_set_edge_mode() - * @see peripheral_gpio_unregister_cb() + * @see peripheral_gpio_write() */ -int peripheral_gpio_register_cb(peripheral_gpio_h gpio, gpio_isr_cb callback, void *user_data); +int peripheral_gpio_read(peripheral_gpio_h gpio, uint32_t *value); /** - * @brief Unregisters the callback function for the gpio handler. + * @platform + * @brief Sets the value of the GPIO pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] gpio The handle to the gpio pin + * @param[in] gpio The GPIO handle + * @param[in] value The value to set (must be 0 or 1) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error * - * @see peripheral_gpio_register_cb() - */ -int peripheral_gpio_unregister_cb(peripheral_gpio_h gpio); - -/** - * @brief Gets pin number of the gpio handle. - * @since_tizen 4.0 - * - * @param[in] gpio The handle to the gpio pin - * @param[out] gpio_pin The pin number of the gpio - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @see peripheral_gpio_read() */ -int peripheral_gpio_get_pin(peripheral_gpio_h gpio, int *gpio_pin); +int peripheral_gpio_write(peripheral_gpio_h gpio, uint32_t value); /** * @} */ /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_I2C_MODULE + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_I2C_MODULE * @{ */ /** - * @brief The handle to the i2c device + * @brief The handle of the I2C slave device. * @since_tizen 4.0 */ typedef struct _peripheral_i2c_s *peripheral_i2c_h; /** - * @brief Initializes i2c communication and creates i2c handle. + * @platform + * @brief Opens an I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks @a i2c should be released with peripheral_i2c_close() * - * @param[in] bus The i2c bus number that the slave device is connected + * @param[in] bus The I2C bus number that the slave device is connected * @param[in] address The address of the slave device - * @param[out] i2c The i2c handle is created on success + * @param[out] i2c The I2C handle is created on success * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied + * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_i2c_close() + * @post peripheral_i2c_close() */ int peripheral_i2c_open(int bus, int address, peripheral_i2c_h *i2c); /** - * @brief Destory the i2c handle and release the communication. + * @platform + * @brief Closes an I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The i2c handle + * @param[in] i2c The I2C handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error * - * @see peripheral_i2c_open() + * @pre peripheral_i2c_open() */ int peripheral_i2c_close(peripheral_i2c_h i2c); /** - * @brief Reads data from the i2c slave device. + * @platform + * @brief Reads the bytes data from the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[out] data The address of data buffer to read + * @param[in] i2c The I2C handle + * @param[out] data The data buffer to read * @param[in] length The size of data buffer (in bytes) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_i2c_write() */ -int peripheral_i2c_read(peripheral_i2c_h i2c, uint8_t *data, int length); +int peripheral_i2c_read(peripheral_i2c_h i2c, uint8_t *data, uint32_t length); /** - * @brief Write data to the i2c slave device. + * @platform + * @brief Writes the bytes data to the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[in] data The address of data buffer to write + * @param[in] i2c The I2C handle + * @param[in] data The data buffer to write * @param[in] length The size of data buffer (in bytes) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - */ -int peripheral_i2c_write(peripheral_i2c_h i2c, uint8_t *data, int length); - -/** - * @brief Reads single byte data from the i2c slave device. - * @since_tizen 4.0 * - * @param[in] i2c The handle to the i2c device - * @param[out] data The address of data buffer to read - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @see peripheral_i2c_read() */ -int peripheral_i2c_read_byte(peripheral_i2c_h i2c, uint8_t *data); +int peripheral_i2c_write(peripheral_i2c_h i2c, uint8_t *data, uint32_t length); /** - * @brief Write single byte data to the i2c slave device. + * @platform + * @brief Reads single byte data from the register of the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[in] data The byte value to write + * @param[in] i2c The I2C handle + * @param[in] reg The register address of the I2C slave device to read + * @param[out] data The single byte data to read * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - */ -int peripheral_i2c_write_byte(peripheral_i2c_h i2c, uint8_t data); - -/** - * @brief Reads byte data from the register of i2c slave device. - * @since_tizen 4.0 * - * @param[in] i2c The handle to the i2c device - * @param[in] address The register address of the i2c slave device to read - * @param[out] data The byte output of slave device(register value) - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @see peripheral_i2c_write_register_byte() */ -int peripheral_i2c_read_register_byte(peripheral_i2c_h i2c, uint8_t address, uint8_t *data); +int peripheral_i2c_read_register_byte(peripheral_i2c_h i2c, uint8_t reg, uint8_t *data); /** - * @brief Write byte data to the register of i2c slave device. + * @platform + * @brief Writes single byte data to the register of the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[in] address The register address of the i2c slave device to write - * @param[in] data The byte value to write + * @param[in] i2c The I2C handle + * @param[in] reg The register address of the I2C slave device to write + * @param[in] data The single byte data to write * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_i2c_read_register_byte() */ -int peripheral_i2c_write_register_byte(peripheral_i2c_h i2c, uint8_t address, uint8_t data); +int peripheral_i2c_write_register_byte(peripheral_i2c_h i2c, uint8_t reg, uint8_t data); /** - * @brief Reads word data from the register of i2c slave device. + * @platform + * @brief Reads word data from the register of the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[in] address The register address of the i2c slave device to read - * @param[out] data The word output(2 bytes) of slave device(register value) + * @param[in] i2c The I2C handle + * @param[in] reg The register address of the I2C slave device to read + * @param[out] data The word(2 bytes) data to read * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_i2c_write_register_word() */ -int peripheral_i2c_read_register_word(peripheral_i2c_h i2c, uint8_t address, uint16_t *data); +int peripheral_i2c_read_register_word(peripheral_i2c_h i2c, uint8_t reg, uint16_t *data); /** - * @brief Write byte data to the register of i2c slave device. + * @platform + * @brief Writes word data to the register of the I2C slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] i2c The handle to the i2c device - * @param[in] address The register address of the i2c slave device to write - * @param[in] data The word(2 bytes) value to write + * @param[in] i2c The I2C handle + * @param[in] reg The register address of the I2C slave device to write + * @param[in] data The word(2 bytes) data to write * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_i2c_read_register_word() */ -int peripheral_i2c_write_register_word(peripheral_i2c_h i2c, uint8_t address, uint16_t data); +int peripheral_i2c_write_register_word(peripheral_i2c_h i2c, uint8_t reg, uint16_t data); /** * @} */ /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_PWM_MODULE + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_PWM_MODULE * @{ */ /** - * @brief The handle to the pwm device + * @brief The handle of the PWM device. * @since_tizen 4.0 */ typedef struct _peripheral_pwm_s *peripheral_pwm_h; /** * @brief Enumeration for Polarity. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_PWM_POLARITY_NORMAL = 0, - PERIPHERAL_PWM_POLARITY_INVERSED, + PERIPHERAL_PWM_POLARITY_ACTIVE_HIGH = 0, /**< PWM signal start in the active high state (Normal) */ + PERIPHERAL_PWM_POLARITY_ACTIVE_LOW, /**< PWM signal start in the active low state (Inversed) */ } peripheral_pwm_polarity_e; /** - * @brief Initializes(export) pwm device and creates pwm handle. + * @platform + * @brief Opens the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks @a pwm should be released with peripheral_pwm_close() * - * @param[in] device The pwm chip number - * @param[in] channel The pwm channel number to control - * @param[out] pwm The pwm handle is created on success + * @param[in] chip The PWM chip number + * @param[in] pin The PWM pin(channel) number to control + * @param[out] pwm The PWM handle is created on success * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_pwm_close() + * @post peripheral_pwm_close() */ -int peripheral_pwm_open(int device, int channel, peripheral_pwm_h *pwm); +int peripheral_pwm_open(int chip, int pin, peripheral_pwm_h *pwm); /** - * @brief Destory the pwm handle and finalize(unexport) the pwm device. + * @platform + * @brief Closes the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] pwm The handle to the pwm device + * @param[in] pwm The PWM handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_pwm_open() + * @pre peripheral_pwm_open() */ int peripheral_pwm_close(peripheral_pwm_h pwm); /** - * @brief Sets Period of the pwm device. - * @since_tizen 4.0 - * - * @param[in] pwm The handle to the pwm device - * @param[in] period The total period of the PWM signal (in nanoseconds) - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_pwm_set_period(peripheral_pwm_h pwm, int period); - -/** - * @brief Gets Period of the pwm device. + * @platform + * @brief Sets period of the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] pwm The handle to the pwm device - * @param[out] period The total period of the PWM signal (in nanoseconds) + * @param[in] pwm The PWM handle + * @param[in] period_ns The total period of the PWM pin (in nanoseconds) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_pwm_get_period(peripheral_pwm_h pwm, int *period); +int peripheral_pwm_set_period(peripheral_pwm_h pwm, uint32_t period_ns); /** - * @brief Sets Duty Cycle of the pwm device. + * @platform + * @brief Sets duty cycle of the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] pwm The handle to the pwm device - * @param[in] duty_cycle The active time of the pwm signal (in nanoseconds) + * @param[in] pwm The PWM handle + * @param[in] duty_cycle_ns The duty cycle of the PWM pin (in nanoseconds) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_pwm_set_duty_cycle(peripheral_pwm_h pwm, int duty_cycle); +int peripheral_pwm_set_duty_cycle(peripheral_pwm_h pwm, uint32_t duty_cycle_ns); /** - * @brief Gets Duty Cycle of the pwm device. + * @platform + * @brief Sets polarity of the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] pwm The handle to the pwm device - * @param[out] duty_cycle The active time of the pwm signal (in nanoseconds) + * @param[in] pwm The PWM handle + * @param[in] polarity The polarity of the PWM pin * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_pwm_get_duty_cycle(peripheral_pwm_h pwm, int *duty_cycle); - -/** - * @brief Sets Polarity of the pwm device. - * @since_tizen 4.0 - * - * @param[in] pwm The handle to the pwm device - * @param[in] polarity The polarity of the pwm signal * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @see peripheral_pwm_polarity_e */ int peripheral_pwm_set_polarity(peripheral_pwm_h pwm, peripheral_pwm_polarity_e polarity); /** - * @brief Gets Polarity of the pwm device. + * @platform + * @brief Enables the PWM pin. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] pwm The handle to the pwm device - * @param[out] polarity The polarity of the pwm signal - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_pwm_get_polarity(peripheral_pwm_h pwm, peripheral_pwm_polarity_e *polarity); - -/** - * @brief Enable of the pwm device. - * @since_tizen 4.0 - * - * @param[in] pwm The handle to the pwm device - * @param[in] enable Enable/disable the pwm signal - * true - enable - * false - disable - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_pwm_set_enable(peripheral_pwm_h pwm, bool enable); - -/** - * @brief Gets Enable status of the pwm device. - * @since_tizen 4.0 - * - * @param[in] pwm The handle to the pwm device - * @param[out] enable Enable/disable the pwm signal + * @param[in] pwm The PWM handle + * @param[in] enabled Enable/disable the PWM pin * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_INVALID_OPERATION Invalid access + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_pwm_get_enable(peripheral_pwm_h pwm, bool *enable); +int peripheral_pwm_set_enabled(peripheral_pwm_h pwm, bool enabled); /** * @} */ /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_ADC_MODULE + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_UART_MODULE * @{ */ /** - * @brief Reads data from the adc device. + * @brief The handle to the UART device. * @since_tizen 4.0 - * - * @param[in] device The device number of the adc device - * @param[in] channel The channel number to read - * @param[out] data The address of buffer to read - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_adc_read(unsigned int device, unsigned int channel, int *data); - -/** -* @} -*/ +typedef struct _peripheral_uart_s *peripheral_uart_h; /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_UART_MODULE - * @{ + * @brief Enumeration for baud rate. + * @since_tizen 4.0 */ - -/** - * @brief The handle to the uart device +typedef enum { + PERIPHERAL_UART_BAUD_RATE_0 = 0, /**< The number of signal in one second is 0 */ + PERIPHERAL_UART_BAUD_RATE_50, /**< The number of signal in one second is 50 */ + PERIPHERAL_UART_BAUD_RATE_75, /**< The number of signal in one second is 75 */ + PERIPHERAL_UART_BAUD_RATE_110, /**< The number of signal in one second is 110 */ + PERIPHERAL_UART_BAUD_RATE_134, /**< The number of signal in one second is 134 */ + PERIPHERAL_UART_BAUD_RATE_150, /**< The number of signal in one second is 150 */ + PERIPHERAL_UART_BAUD_RATE_200, /**< The number of signal in one second is 200 */ + PERIPHERAL_UART_BAUD_RATE_300, /**< The number of signal in one second is 300 */ + PERIPHERAL_UART_BAUD_RATE_600, /**< The number of signal in one second is 600 */ + PERIPHERAL_UART_BAUD_RATE_1200, /**< The number of signal in one second is 1200 */ + PERIPHERAL_UART_BAUD_RATE_1800, /**< The number of signal in one second is 1800 */ + PERIPHERAL_UART_BAUD_RATE_2400, /**< The number of signal in one second is 2400 */ + PERIPHERAL_UART_BAUD_RATE_4800, /**< The number of signal in one second is 4800 */ + PERIPHERAL_UART_BAUD_RATE_9600, /**< The number of signal in one second is 9600 */ + PERIPHERAL_UART_BAUD_RATE_19200, /**< The number of signal in one second is 19200 */ + PERIPHERAL_UART_BAUD_RATE_38400, /**< The number of signal in one second is 38400 */ + PERIPHERAL_UART_BAUD_RATE_57600, /**< The number of signal in one second is 57600 */ + PERIPHERAL_UART_BAUD_RATE_115200, /**< The number of signal in one second is 115200 */ + PERIPHERAL_UART_BAUD_RATE_230400, /**< The number of signal in one second is 230400 */ +} peripheral_uart_baud_rate_e; + +/** + * @brief Enumeration for byte size. * @since_tizen 4.0 */ -typedef struct _peripheral_uart_s *peripheral_uart_h; +typedef enum { + PERIPHERAL_UART_BYTE_SIZE_5BIT = 0, /**< 5 data bits */ + PERIPHERAL_UART_BYTE_SIZE_6BIT, /**< 6 data bits */ + PERIPHERAL_UART_BYTE_SIZE_7BIT, /**< 7 data bits */ + PERIPHERAL_UART_BYTE_SIZE_8BIT, /**< 8 data bits */ +} peripheral_uart_byte_size_e; /** - * @brief Enumeration for Baud Rate. + * @brief Enumeration for parity bit. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_UART_BAUDRATE_0 = 0, - PERIPHERAL_UART_BAUDRATE_50, - PERIPHERAL_UART_BAUDRATE_75, - PERIPHERAL_UART_BAUDRATE_110, - PERIPHERAL_UART_BAUDRATE_134, - PERIPHERAL_UART_BAUDRATE_150, - PERIPHERAL_UART_BAUDRATE_200, - PERIPHERAL_UART_BAUDRATE_300, - PERIPHERAL_UART_BAUDRATE_600, - PERIPHERAL_UART_BAUDRATE_1200, - PERIPHERAL_UART_BAUDRATE_1800, - PERIPHERAL_UART_BAUDRATE_2400, - PERIPHERAL_UART_BAUDRATE_4800, - PERIPHERAL_UART_BAUDRATE_9600, - PERIPHERAL_UART_BAUDRATE_19200, - PERIPHERAL_UART_BAUDRATE_38400, - PERIPHERAL_UART_BAUDRATE_57600, - PERIPHERAL_UART_BAUDRATE_115200, - PERIPHERAL_UART_BAUDRATE_230400 -} peripheral_uart_baudrate_e; - -/** - * @brief Enumeration for Byte Size. + PERIPHERAL_UART_PARITY_NONE = 0, /**< No parity is used */ + PERIPHERAL_UART_PARITY_EVEN, /**< Even parity is used */ + PERIPHERAL_UART_PARITY_ODD, /**< ODD parity is used */ +} peripheral_uart_parity_e; + +/** + * @brief Enumeration for stop bits. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_UART_BYTESIZE_5BIT = 0, - PERIPHERAL_UART_BYTESIZE_6BIT, - PERIPHERAL_UART_BYTESIZE_7BIT, - PERIPHERAL_UART_BYTESIZE_8BIT -} peripheral_uart_bytesize_e; + PERIPHERAL_UART_STOP_BITS_1BIT = 0, /**< One stop bit */ + PERIPHERAL_UART_STOP_BITS_2BIT, /**< Two stop bits */ +} peripheral_uart_stop_bits_e; /** - * @brief Enumeration for Parity Bit. + * @brief Enumeration for hardware flow control. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_UART_PARITY_NONE = 0, - PERIPHERAL_UART_PARITY_EVEN, - PERIPHERAL_UART_PARITY_ODD -} peripheral_uart_parity_e; + PERIPHERAL_UART_HARDWARE_FLOW_CONTROL_NONE = 0, /**< No hardware flow control */ + PERIPHERAL_UART_HARDWARE_FLOW_CONTROL_AUTO_RTSCTS, /**< Automatic RTS/CTS hardware flow control*/ +} peripheral_uart_hardware_flow_control_e; /** - * @brief Enumeration for Stop Bits. + * @brief Enumeration for software flow control. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_UART_STOPBITS_1BIT = 0, - PERIPHERAL_UART_STOPBITS_2BIT -} peripheral_uart_stopbits_e; + PERIPHERAL_UART_SOFTWARE_FLOW_CONTROL_NONE = 0, /**< No software flow control */ + PERIPHERAL_UART_SOFTWARE_FLOW_CONTROL_XONXOFF, /**< XON/XOFF software flow control */ +} peripheral_uart_software_flow_control_e; /** - * @brief Initializes uart communication and creates uart handle. + * @platform + * @brief Opens the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks @a uart should be released with peripheral_uart_close() * - * @param[in] port The uart port number that the slave device is connected - * @param[out] uart The uart handle is created on success + * @param[in] port The UART port number that the slave device is connected + * @param[out] uart The UART handle is created on success * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied + * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed * - * @see peripheral_uart_close() + * @post peripheral_uart_close() */ int peripheral_uart_open(int port, peripheral_uart_h *uart); /** - * @brief Destory the uart handle and release the communication. + * @platform + * @brief Closes the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device + * @param[in] uart The UART handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error * - * @see peripheral_uart_open() + * @pre peripheral_uart_open() */ int peripheral_uart_close(peripheral_uart_h uart); /** - * @brief Flush all input that has received but not yet been read by the uart - * device, or all output written but not transmitted to the uart device. + * @platform + * @brief Sets baud rate of the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The uart handle + * @param[in] uart The UART handle + * @param[in] baud Baud rate of the UART device * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_uart_baud_rate_e */ -int peripheral_uart_flush(peripheral_uart_h uart); +int peripheral_uart_set_baud_rate(peripheral_uart_h uart, peripheral_uart_baud_rate_e baud); /** - * @brief Sets baudrate of the uart device. + * @platform + * @brief Sets byte size of the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device to set - * @param[in] baud Baudrate of the uart device + * @param[in] uart The UART handle + * @param[in] byte_size Byte size of the UART device * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_uart_byte_size_e */ -int peripheral_uart_set_baudrate(peripheral_uart_h uart, peripheral_uart_baudrate_e baud); +int peripheral_uart_set_byte_size(peripheral_uart_h uart, peripheral_uart_byte_size_e byte_size); /** - * @brief Sets mode of the uart device. + * @platform + * @brief Sets parity bit of the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device to set - * @param[in] bytesize Byte size of the uart device - * @param[in] parity Parity bits of the uart device - * @param[in] stopbits Stop bits of the uart device + * @param[in] uart The UART handle + * @param[in] parity Parity bit of the UART device * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_uart_parity_e */ -int peripheral_uart_set_mode(peripheral_uart_h uart, peripheral_uart_bytesize_e bytesize, peripheral_uart_parity_e parity, peripheral_uart_stopbits_e stopbits); +int peripheral_uart_set_parity(peripheral_uart_h uart, peripheral_uart_parity_e parity); /** - * @brief Sets flow control of the uart device. + * @platform + * @brief Sets stop bits of the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device to set - * @param[in] xonxoff Turns a transmitter on or off - * @param[in] rtscts Turns "Request to Send/Clear to Send" on or off + * @param[in] uart The UART handle + * @param[in] stop_bits Stop bits of the UART device * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_uart_stop_bits_e */ -int peripheral_uart_set_flowcontrol(peripheral_uart_h uart, bool xonxoff, bool rtscts); +int peripheral_uart_set_stop_bits(peripheral_uart_h uart, peripheral_uart_stop_bits_e stop_bits); /** - * @brief Reads data from the uart device. + * @platform + * @brief Sets flow control of the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device - * @param[out] data The address of read buffer - * @param[out] length The size of data buffer (in bytes) + * @param[in] uart The UART handle + * @param[in] sw_flow_control Software flow control (Turns a transmitter on or off) + * @param[in] hw_flow_control Hardware flow control (Turns "Request to Send/Clear to Send" on or off) + * + * @return 0 on success, otherwise a negative error value + * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied + * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported + * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_uart_software_flow_control_e + * @see peripheral_uart_hardware_flow_control_e + */ +int peripheral_uart_set_flow_control(peripheral_uart_h uart, + peripheral_uart_software_flow_control_e sw_flow_control, + peripheral_uart_hardware_flow_control_e hw_flow_control); + +/** + * @platform + * @brief Reads data from the UART slave device. + * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * + * @param[in] uart The UART handle + * @param[out] data The buffer to read + * @param[out] length The size of buffer (in bytes) * * @return the number of bytes read on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_TRY_AGAIN Try again + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_uart_write() */ -int peripheral_uart_read(peripheral_uart_h uart, uint8_t *data, int length); +int peripheral_uart_read(peripheral_uart_h uart, uint8_t *data, uint32_t length); /** - * @brief Write data to the uart device. + * @platform + * @brief Writes data to the UART slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] uart The handle to the uart device - * @param[in] data The address of buffer to write - * @param[in] length The size of data (in bytes) + * @param[in] uart The UART handle + * @param[in] data The buffer to write + * @param[in] length The size of buffer (in bytes) * * @return the number of bytes write on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_TRY_AGAIN Try again + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_uart_read() */ -int peripheral_uart_write(peripheral_uart_h uart, uint8_t *data, int length); +int peripheral_uart_write(peripheral_uart_h uart, uint8_t *data, uint32_t length); /** * @} */ /** - * @addtogroup CAPI_SYSTEM_PERIPHERAL_SPI_MODULE + * @addtogroup CAPI_SYSTEM_PERIPHERAL_IO_SPI_MODULE * @{ */ /** - * @brief The handle to the spi device + * @brief The handle of a SPI device. * @since_tizen 4.0 */ -typedef struct _peripheral_spi_s* peripheral_spi_h; +typedef struct _peripheral_spi_s *peripheral_spi_h; /** - * @brief Enumeration for SPI mode. + * @brief Enumeration of SPI transfer modes. + * @since_tizen 4.0 */ typedef enum { - PERIPHERAL_SPI_MODE_0 = 0, - PERIPHERAL_SPI_MODE_1, - PERIPHERAL_SPI_MODE_2, - PERIPHERAL_SPI_MODE_3 + PERIPHERAL_SPI_MODE_0 = 0, /**< CPOL = 0, CPHa = 0 Mode */ + PERIPHERAL_SPI_MODE_1, /**< CPOL = 0, CPHa = 1 Mode */ + PERIPHERAL_SPI_MODE_2, /**< CPOL = 1, CPHa = 0 Mode */ + PERIPHERAL_SPI_MODE_3, /**< CPOL = 1, CPHa = 1 Mode */ } peripheral_spi_mode_e; /** - * @brief Initializes spi communication and creates spi handle. + * @brief Enumeration of bit orders. * @since_tizen 4.0 - * - * @param[in] bus The spi bus number that the slave device is connected - * @param[in] cs The spi chip select number that the slave device is connected - * @param[out] spi The spi handle is created on success - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * - * @see peripheral_spi_close() */ -int peripheral_spi_open(int bus, int cs, peripheral_spi_h *spi); +typedef enum { + PERIPHERAL_SPI_BIT_ORDER_MSB = 0, /**< Use most siginificant bit first */ + PERIPHERAL_SPI_BIT_ORDER_LSB, /**< Use least significant bit first */ +} peripheral_spi_bit_order_e; /** - * @brief Destory the spi handle and release the communication. + * @platform + * @brief Opens a SPI slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks @a spi should be released with peripheral_spi_close() * - * @param[in] spi The handle to the spi device + * @param[in] bus The SPI bus number + * @param[in] cs The SPI chip select number + * @param[out] spi The SPI device handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful + * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_OUT_OF_MEMORY Memory allocation failed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied + * @retval #PERIPHERAL_ERROR_RESOURCE_BUSY Device is in use * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error * - * @see peripheral_spi_open() + * @post peripheral_spi_close() */ -int peripheral_spi_close(peripheral_spi_h spi); +int peripheral_spi_open(int bus, int cs, peripheral_spi_h *spi); /** - * @brief Sets mode of the spi device. + * @platform + * @brief Closes the SPI slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[in] mode The mode of the spi device + * @param[in] spi The SPI device handle * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_spi_set_mode(peripheral_spi_h spi, peripheral_spi_mode_e mode); - -/** - * @brief Gets mode of the spi device. - * @since_tizen 4.0 - * - * @param[in] spi The handle to the spi device - * @param[out] mode The mode of the spi device * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @see peripheral_spi_open() */ -int peripheral_spi_get_mode(peripheral_spi_h spi, peripheral_spi_mode_e *mode); +int peripheral_spi_close(peripheral_spi_h spi); /** - * @brief Sets bits justification of the spi device. + * @platform + * @brief Sets the SPI transfer mode. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[in] lsb The bit position to be transmitted first - * true - LSB first - * false - MSB first + * @param[in] spi The SPI device handle + * @param[in] mode The SPI transfer mode * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_spi_mode_e */ -int peripheral_spi_set_lsb_first(peripheral_spi_h spi, bool lsb); +int peripheral_spi_set_mode(peripheral_spi_h spi, peripheral_spi_mode_e mode); /** - * @brief Gets bits justification of the spi device. + * @platform + * @brief Sets the SPI bit order. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[out] lsb The bit position to be transmitted first + * @param[in] spi The SPI device handle + * @param[in] bit_order The transfer bit order * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * + * @see peripheral_spi_bit_order_e */ -int peripheral_spi_get_lsb_first(peripheral_spi_h spi, bool *lsb); +int peripheral_spi_set_bit_order(peripheral_spi_h spi, peripheral_spi_bit_order_e bit_order); /** - * @brief Sets the number of bits per word of the spi device + * @platform + * @brief Sets the number of bits per word. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device + * @param[in] spi The SPI device handle * @param[in] bits The number of bits per word (in bits) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_spi_set_bits_per_word(peripheral_spi_h spi, unsigned char bits); +int peripheral_spi_set_bits_per_word(peripheral_spi_h spi, uint8_t bits); /** - * @brief Gets the number of bits per word of the spi device + * @platform + * @brief Sets the frequency of the SPI bus. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio + * @remarks The frequencies supported are board dependent. * - * @param[in] spi The handle to the spi device - * @param[out] bits The number of bits per word (in bits) + * @param[in] spi The SPI device handle + * @param[in] freq_hz Frequency to set (in Hz) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed */ -int peripheral_spi_get_bits_per_word(peripheral_spi_h spi, unsigned char *bits); +int peripheral_spi_set_frequency(peripheral_spi_h spi, uint32_t freq_hz); /** - * @brief Sets default max speed of the spi device. + * @platform + * @brief Reads the bytes data from the SPI slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[in] freq Max speed (in hz) + * @param[in] spi The SPI device handle + * @param[out] data The data buffer to read + * @param[in] length The size of data buffer (in bytes) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed - */ -int peripheral_spi_set_frequency(peripheral_spi_h spi, unsigned int freq); - -/** - * @brief Gets default max speed of the spi device. - * @since_tizen 4.0 - * - * @param[in] spi The handle to the spi device - * @param[out] freq Max speed (in hz) * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - * @retval #PERIPHERAL_ERROR_NO_DEVICE Device is not exist or removed + * @see peripheral_spi_write() */ - -int peripheral_spi_get_frequency(peripheral_spi_h spi, unsigned int *freq); +int peripheral_spi_read(peripheral_spi_h spi, uint8_t *data, uint32_t length); /** - * @brief Reads data from the slave device. + * @platform + * @brief Writes the bytes data to the SPI slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[out] data The address of buffer to read + * @param[in] spi The SPI device handle + * @param[in] data The data buffer to write * @param[in] length The size of data buffer (in bytes) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error - */ -int peripheral_spi_read(peripheral_spi_h spi, unsigned char *data, int length); - -/** - * @brief Write data to the slave device. - * @since_tizen 4.0 * - * @param[in] spi The handle to the spi device - * @param[in] data The address of buffer to write - * @param[in] length The size of data (in bytes) - * - * @return 0 on success, otherwise a negative error value - * @retval #PERIPHERAL_ERROR_NONE Successful - * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed - * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * @see peripheral_spi_read() */ -int peripheral_spi_write(peripheral_spi_h spi, unsigned char *data, int length); +int peripheral_spi_write(peripheral_spi_h spi, uint8_t *data, uint32_t length); /** - * @brief Exchange data with the slave device. + * @platform + * @brief Exchanges the bytes data to the SPI slave device. * @since_tizen 4.0 + * @privlevel platform + * @privilege http://tizen.org/privilege/peripheralio * - * @param[in] spi The handle to the spi device - * @param[in] txdata The address of buffer to write - * @param[out] rxdata The address of buffer to read - * @param[in] length The size of data (in bytes) + * @param[in] spi The SPI device handle + * @param[in] txdata The data buffer to write + * @param[out] rxdata The data buffer to read + * @param[in] length The size of txdata and rxdata buffer (in bytes) * * @return 0 on success, otherwise a negative error value * @retval #PERIPHERAL_ERROR_NONE Successful * @retval #PERIPHERAL_ERROR_IO_ERROR I/O operation failed + * @retval #PERIPHERAL_ERROR_NO_DEVICE Device does not exist or is removed + * @retval #PERIPHERAL_ERROR_PERMISSION_DENIED Permission denied * @retval #PERIPHERAL_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #PERIPHERAL_ERROR_NOT_SUPPORTED Not supported * @retval #PERIPHERAL_ERROR_UNKNOWN Unknown internal error + * + * @see peripheral_spi_read() + * @see peripheral_spi_write() */ -int peripheral_spi_read_write(peripheral_spi_h spi, unsigned char *txdata, unsigned char *rxdata, int length); +int peripheral_spi_transfer(peripheral_spi_h spi, uint8_t *txdata, uint8_t *rxdata, uint32_t length); /** * @} @@ -1133,4 +1197,4 @@ int peripheral_spi_read_write(peripheral_spi_h spi, unsigned char *txdata, unsig } #endif -#endif /* __PERIPHERAL_IO_H__ */ +#endif /* __TIZEN_SYSTEM_PERIPHERAL_IO_H__ */ -- 2.7.4