LCOV - code coverage report
Current view: top level - zephyr/drivers - i2s.h Coverage Total Hit
Test: new.info Lines: 100.0 % 48 48
Test Date: 2025-09-25 19:22:35

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2017 Piotr Mienkowski
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @ingroup i2s_interface
      10              :  * @brief Main header file for I2S (Inter-IC Sound) driver API.
      11              :  */
      12              : 
      13              : #ifndef ZEPHYR_INCLUDE_DRIVERS_I2S_H_
      14              : #define ZEPHYR_INCLUDE_DRIVERS_I2S_H_
      15              : 
      16              : /**
      17              :  * @defgroup i2s_interface I2S
      18              :  * @since 1.9
      19              :  * @version 1.0.0
      20              :  * @ingroup io_interfaces
      21              :  * @brief Interfaces for Inter-IC Sound (I2S) controllers.
      22              :  *
      23              :  * The I2S API provides support for the standard I2S interface standard as well
      24              :  * as common non-standard extensions such as PCM Short/Long Frame Sync,
      25              :  * Left/Right Justified Data Format.
      26              :  * @{
      27              :  */
      28              : 
      29              : #include <zephyr/types.h>
      30              : #include <zephyr/device.h>
      31              : 
      32              : #ifdef __cplusplus
      33              : extern "C" {
      34              : #endif
      35              : 
      36              : /*
      37              :  * The following #defines are used to configure the I2S controller.
      38              :  */
      39              : 
      40              : /** I2S data stream format options */
      41            1 : typedef uint8_t i2s_fmt_t;
      42              : 
      43              : /** Data Format bit field position. */
      44            1 : #define I2S_FMT_DATA_FORMAT_SHIFT           0
      45              : /** Data Format bit field mask. */
      46            1 : #define I2S_FMT_DATA_FORMAT_MASK            (0x7 << I2S_FMT_DATA_FORMAT_SHIFT)
      47              : 
      48              : /** @brief Standard I2S Data Format.
      49              :  *
      50              :  * Serial data is transmitted in two's complement with the MSB first. Both
      51              :  * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
      52              :  * of the clock signal (SCK). The MSB is always sent one clock period after the
      53              :  * WS changes. Left channel data are sent first indicated by WS = 0, followed
      54              :  * by right channel data indicated by WS = 1.
      55              :  *
      56              :  *        -. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
      57              :  *     SCK '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '
      58              :  *        -.                               .-------------------------------.
      59              :  *     WS  '-------------------------------'                               '----
      60              :  *        -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.
      61              :  *     SD  |   |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB| x |...| x |
      62              :  *        -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'
      63              :  *             | Left channel                  | Right channel                 |
      64              :  */
      65            1 : #define I2S_FMT_DATA_FORMAT_I2S             (0 << I2S_FMT_DATA_FORMAT_SHIFT)
      66              : 
      67              : /** @brief PCM Short Frame Sync Data Format.
      68              :  *
      69              :  * Serial data is transmitted in two's complement with the MSB first. Both
      70              :  * Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge
      71              :  * of the clock signal (SCK). The falling edge of the frame sync signal (WS)
      72              :  * indicates the start of the PCM word. The frame sync is one clock cycle long.
      73              :  * An arbitrary number of data words can be sent in one frame.
      74              :  *
      75              :  *          .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
      76              :  *     SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
      77              :  *          .---.                                                       .---.
      78              :  *     WS  -'   '-                                                     -'   '-
      79              :  *         -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
      80              :  *     SD   |   |MSB|   |...|   |LSB|MSB|   |...|   |LSB|MSB|   |...|   |LSB|
      81              :  *         -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
      82              :  *              | Word 1            | Word 2            | Word 3  |  Word n |
      83              :  */
      84            1 : #define I2S_FMT_DATA_FORMAT_PCM_SHORT       (1 << I2S_FMT_DATA_FORMAT_SHIFT)
      85              : 
      86              : /** @brief PCM Long Frame Sync Data Format.
      87              :  *
      88              :  * Serial data is transmitted in two's complement with the MSB first. Both
      89              :  * Word Select (WS) and Serial Data (SD) signals are sampled on the falling edge
      90              :  * of the clock signal (SCK). The rising edge of the frame sync signal (WS)
      91              :  * indicates the start of the PCM word. The frame sync has an arbitrary length,
      92              :  * however it has to fall before the start of the next frame. An arbitrary
      93              :  * number of data words can be sent in one frame.
      94              :  *
      95              :  *          .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
      96              :  *     SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
      97              :  *              .--- ---.    ---.        ---.                               .---
      98              :  *     WS      -'       '-      '-          '-                             -'
      99              :  *         -.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---
     100              :  *     SD   |   |MSB|   |...|   |LSB|MSB|   |...|   |LSB|MSB|   |...|   |LSB|
     101              :  *         -'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---
     102              :  *              | Word 1            | Word 2            | Word 3  |  Word n |
     103              :  */
     104            1 : #define I2S_FMT_DATA_FORMAT_PCM_LONG        (2 << I2S_FMT_DATA_FORMAT_SHIFT)
     105              : 
     106              : /**
     107              :  * @brief Left Justified Data Format.
     108              :  *
     109              :  * Serial data is transmitted in two's complement with the MSB first. Both
     110              :  * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
     111              :  * of the clock signal (SCK). The bits within the data word are left justified
     112              :  * such that the MSB is always sent in the clock period following the WS
     113              :  * transition. Left channel data are sent first indicated by WS = 1, followed
     114              :  * by right channel data indicated by WS = 0.
     115              :  *
     116              :  *          .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
     117              :  *     SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
     118              :  *            .-------------------------------.                               .-
     119              :  *     WS  ---'                               '-------------------------------'
     120              :  *         ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
     121              :  *     SD     |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB| x |...| x |
     122              :  *         ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
     123              :  *            | Left channel                  | Right channel                 |
     124              :  */
     125            1 : #define I2S_FMT_DATA_FORMAT_LEFT_JUSTIFIED  (3 << I2S_FMT_DATA_FORMAT_SHIFT)
     126              : 
     127              : /**
     128              :  * @brief Right Justified Data Format.
     129              :  *
     130              :  * Serial data is transmitted in two's complement with the MSB first. Both
     131              :  * Word Select (WS) and Serial Data (SD) signals are sampled on the rising edge
     132              :  * of the clock signal (SCK). The bits within the data word are right justified
     133              :  * such that the LSB is always sent in the clock period preceding the WS
     134              :  * transition. Left channel data are sent first indicated by WS = 1, followed
     135              :  * by right channel data indicated by WS = 0.
     136              :  *
     137              :  *          .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-. .-.
     138              :  *     SCK -' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-
     139              :  *            .-------------------------------.                               .-
     140              :  *     WS  ---'                               '-------------------------------'
     141              :  *         ---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.-
     142              :  *     SD     | x |...| x |MSB|   |...|   |LSB| x |...| x |MSB|   |...|   |LSB|
     143              :  *         ---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'-
     144              :  *            | Left channel                  | Right channel                 |
     145              :  */
     146            1 : #define I2S_FMT_DATA_FORMAT_RIGHT_JUSTIFIED (4 << I2S_FMT_DATA_FORMAT_SHIFT)
     147              : 
     148              : /** Send MSB first */
     149            1 : #define I2S_FMT_DATA_ORDER_MSB              (0 << 3)
     150              : /** Send LSB first */
     151            1 : #define I2S_FMT_DATA_ORDER_LSB              BIT(3)
     152              : /** Invert bit ordering, send LSB first */
     153            1 : #define I2S_FMT_DATA_ORDER_INV              I2S_FMT_DATA_ORDER_LSB
     154              : 
     155              : /** Data Format bit field position. */
     156            1 : #define I2S_FMT_CLK_FORMAT_SHIFT           4
     157              : /** Data Format bit field mask. */
     158            1 : #define I2S_FMT_CLK_FORMAT_MASK            (0x3 << I2S_FMT_CLK_FORMAT_SHIFT)
     159              : 
     160              : /** Invert bit clock */
     161            1 : #define I2S_FMT_BIT_CLK_INV                 BIT(4)
     162              : /** Invert frame clock */
     163            1 : #define I2S_FMT_FRAME_CLK_INV               BIT(5)
     164              : 
     165              : /** Normal Frame, Normal Bit Clk */
     166            1 : #define I2S_FMT_CLK_NF_NB               (0 << I2S_FMT_CLK_FORMAT_SHIFT)
     167              : /** Normal Frame, Inverted Bit Clk */
     168            1 : #define I2S_FMT_CLK_NF_IB               (1 << I2S_FMT_CLK_FORMAT_SHIFT)
     169              : /** Inverted Frame, Normal Bit Clk */
     170            1 : #define I2S_FMT_CLK_IF_NB               (2 << I2S_FMT_CLK_FORMAT_SHIFT)
     171              : /** Inverted Frame, Inverted Bit Clk */
     172            1 : #define I2S_FMT_CLK_IF_IB               (3 << I2S_FMT_CLK_FORMAT_SHIFT)
     173              : 
     174              : /** I2S configuration options */
     175            1 : typedef uint8_t i2s_opt_t;
     176              : 
     177              : /** Run bit clock continuously */
     178            1 : #define I2S_OPT_BIT_CLK_CONT                (0 << 0)
     179              : /** Run bit clock when sending data only */
     180            1 : #define I2S_OPT_BIT_CLK_GATED               BIT(0)
     181              : /** I2S driver is bit clock master */
     182            1 : #define I2S_OPT_BIT_CLK_MASTER              (0 << 1)
     183              : /** I2S driver is bit clock slave */
     184            1 : #define I2S_OPT_BIT_CLK_SLAVE               BIT(1)
     185              : /** I2S driver is frame clock master */
     186            1 : #define I2S_OPT_FRAME_CLK_MASTER            (0 << 2)
     187              : /** I2S driver is frame clock slave */
     188            1 : #define I2S_OPT_FRAME_CLK_SLAVE             BIT(2)
     189              : 
     190              : /** @brief Loop back mode.
     191              :  *
     192              :  * In loop back mode RX input will be connected internally to TX output.
     193              :  * This is used primarily for testing.
     194              :  */
     195            1 : #define I2S_OPT_LOOPBACK                    BIT(7)
     196              : 
     197              : /** @brief Ping pong mode
     198              :  *
     199              :  * In ping pong mode TX output will keep alternating between a ping buffer
     200              :  * and a pong buffer. This is normally used in audio streams when one buffer
     201              :  * is being populated while the other is being played (DMAed) and vice versa.
     202              :  * So, in this mode, 2 sets of buffers fixed in size are used. Static Arrays
     203              :  * are used to achieve this and hence they are never freed.
     204              :  */
     205            1 : #define I2S_OPT_PINGPONG                    BIT(6)
     206              : 
     207              : /**
     208              :  * @brief I2C Direction
     209              :  */
     210            1 : enum i2s_dir {
     211              :         /** Receive data */
     212              :         I2S_DIR_RX,
     213              :         /** Transmit data */
     214              :         I2S_DIR_TX,
     215              :         /** Both receive and transmit data */
     216              :         I2S_DIR_BOTH,
     217              : };
     218              : 
     219              : /** Interface state */
     220            1 : enum i2s_state {
     221              :         /** @brief The interface is not ready.
     222              :          *
     223              :          * The interface was initialized but is not yet ready to receive /
     224              :          * transmit data. Call i2s_configure() to configure interface and change
     225              :          * its state to READY.
     226              :          */
     227              :         I2S_STATE_NOT_READY,
     228              :         /** The interface is ready to receive / transmit data. */
     229              :         I2S_STATE_READY,
     230              :         /** The interface is receiving / transmitting data. */
     231              :         I2S_STATE_RUNNING,
     232              :         /** The interface is draining its transmit queue. */
     233              :         I2S_STATE_STOPPING,
     234              :         /** TX buffer underrun or RX buffer overrun has occurred. */
     235              :         I2S_STATE_ERROR,
     236              : };
     237              : 
     238              : /** Trigger command */
     239            1 : enum i2s_trigger_cmd {
     240              :         /** @brief Start the transmission / reception of data.
     241              :          *
     242              :          * If I2S_DIR_TX is set some data has to be queued for transmission by
     243              :          * the i2s_write() function. This trigger can be used in READY state
     244              :          * only and changes the interface state to RUNNING.
     245              :          */
     246              :         I2S_TRIGGER_START,
     247              :         /** @brief Stop the transmission / reception of data.
     248              :          *
     249              :          * Stop the transmission / reception of data at the end of the current
     250              :          * memory block. This trigger can be used in RUNNING state only and at
     251              :          * first changes the interface state to STOPPING. When the current TX /
     252              :          * RX block is transmitted / received the state is changed to READY.
     253              :          * Subsequent START trigger will resume transmission / reception where
     254              :          * it stopped.
     255              :          */
     256              :         I2S_TRIGGER_STOP,
     257              :         /** @brief Empty the transmit queue.
     258              :          *
     259              :          * Send all data in the transmit queue and stop the transmission.
     260              :          * If the trigger is applied to the RX queue it has the same effect as
     261              :          * I2S_TRIGGER_STOP. This trigger can be used in RUNNING state only and
     262              :          * at first changes the interface state to STOPPING. When all TX blocks
     263              :          * are transmitted the state is changed to READY.
     264              :          */
     265              :         I2S_TRIGGER_DRAIN,
     266              :         /** @brief Discard the transmit / receive queue.
     267              :          *
     268              :          * Stop the transmission / reception immediately and discard the
     269              :          * contents of the respective queue. This trigger can be used in any
     270              :          * state other than NOT_READY and changes the interface state to READY.
     271              :          */
     272              :         I2S_TRIGGER_DROP,
     273              :         /** @brief Prepare the queues after underrun/overrun error has occurred.
     274              :          *
     275              :          * This trigger can be used in ERROR state only and changes the
     276              :          * interface state to READY.
     277              :          */
     278              :         I2S_TRIGGER_PREPARE,
     279              : };
     280              : 
     281              : /** @struct i2s_config
     282              :  * @brief Interface configuration options.
     283              :  *
     284              :  * Memory slab pointed to by the mem_slab field has to be defined and
     285              :  * initialized by the user. For I2S driver to function correctly number of
     286              :  * memory blocks in a slab has to be at least 2 per queue. Size of the memory
     287              :  * block should be multiple of frame_size where frame_size = (channels *
     288              :  * word_size_bytes). As an example 16 bit word will occupy 2 bytes, 24 or 32
     289              :  * bit word will occupy 4 bytes.
     290              :  *
     291              :  * Please check Zephyr Kernel Primer for more information on memory slabs.
     292              :  *
     293              :  * @remark When I2S data format is selected parameter channels is ignored,
     294              :  * number of words in a frame is always 2.
     295              :  */
     296            1 : struct i2s_config {
     297              :         /** Number of bits representing one data word. */
     298            1 :         uint8_t word_size;
     299              :         /** Number of words per frame. */
     300            1 :         uint8_t channels;
     301              :         /** Data stream format as defined by I2S_FMT_* constants. */
     302            1 :         i2s_fmt_t format;
     303              :         /** Configuration options as defined by I2S_OPT_* constants. */
     304            1 :         i2s_opt_t options;
     305              :         /** Frame clock (WS) frequency, this is sampling rate. */
     306            1 :         uint32_t frame_clk_freq;
     307              :         /** Memory slab to store RX/TX data. */
     308            1 :         struct k_mem_slab *mem_slab;
     309              :         /** Size of one RX/TX memory block (buffer) in bytes. */
     310            1 :         size_t block_size;
     311              :         /** Read/Write timeout. Number of milliseconds to wait in case TX queue
     312              :          * is full or RX queue is empty, or 0, or SYS_FOREVER_MS.
     313              :          */
     314            1 :         int32_t timeout;
     315              : };
     316              : 
     317              : /**
     318              :  * @cond INTERNAL_HIDDEN
     319              :  *
     320              :  * For internal use only, skip these in public documentation.
     321              :  */
     322              : __subsystem struct i2s_driver_api {
     323              :         int (*configure)(const struct device *dev, enum i2s_dir dir,
     324              :                          const struct i2s_config *cfg);
     325              :         const struct i2s_config *(*config_get)(const struct device *dev,
     326              :                                   enum i2s_dir dir);
     327              :         int (*read)(const struct device *dev, void **mem_block, size_t *size);
     328              :         int (*write)(const struct device *dev, void *mem_block, size_t size);
     329              :         int (*trigger)(const struct device *dev, enum i2s_dir dir,
     330              :                        enum i2s_trigger_cmd cmd);
     331              : };
     332              : /**
     333              :  * @endcond
     334              :  */
     335              : 
     336              : /**
     337              :  * @brief Configure operation of a host I2S controller.
     338              :  *
     339              :  * The dir parameter specifies if Transmit (TX) or Receive (RX) direction
     340              :  * will be configured by data provided via cfg parameter.
     341              :  *
     342              :  * The function can be called in NOT_READY or READY state only. If executed
     343              :  * successfully the function will change the interface state to READY.
     344              :  *
     345              :  * If the function is called with the parameter cfg->frame_clk_freq set to 0
     346              :  * the interface state will be changed to NOT_READY.
     347              :  *
     348              :  * @param dev Pointer to the device structure for the driver instance.
     349              :  * @param dir Stream direction: RX, TX, or both, as defined by I2S_DIR_*.
     350              :  *            The I2S_DIR_BOTH value may not be supported by some drivers.
     351              :  *            For those, the RX and TX streams need to be configured separately.
     352              :  * @param cfg Pointer to the structure containing configuration parameters.
     353              :  *
     354              :  * @retval 0 If successful.
     355              :  * @retval -EINVAL Invalid argument.
     356              :  * @retval -ENOSYS I2S_DIR_BOTH value is not supported.
     357              :  */
     358            1 : __syscall int i2s_configure(const struct device *dev, enum i2s_dir dir,
     359              :                             const struct i2s_config *cfg);
     360              : 
     361              : static inline int z_impl_i2s_configure(const struct device *dev,
     362              :                                        enum i2s_dir dir,
     363              :                                        const struct i2s_config *cfg)
     364              : {
     365              :         const struct i2s_driver_api *api =
     366              :                 (const struct i2s_driver_api *)dev->api;
     367              : 
     368              :         return api->configure(dev, dir, cfg);
     369              : }
     370              : 
     371              : /**
     372              :  * @brief Fetch configuration information of a host I2S controller
     373              :  *
     374              :  * @param dev Pointer to the device structure for the driver instance
     375              :  * @param dir Stream direction: RX or TX as defined by I2S_DIR_*
     376              :  * @retval Pointer to the structure containing configuration parameters,
     377              :  *         or NULL if un-configured
     378              :  */
     379            1 : static inline const struct i2s_config *i2s_config_get(const struct device *dev,
     380              :                                                       enum i2s_dir dir)
     381              : {
     382              :         const struct i2s_driver_api *api =
     383              :                 (const struct i2s_driver_api *)dev->api;
     384              : 
     385              :         return api->config_get(dev, dir);
     386              : }
     387              : 
     388              : /**
     389              :  * @brief Read data from the RX queue.
     390              :  *
     391              :  * Data received by the I2S interface is stored in the RX queue consisting of
     392              :  * memory blocks preallocated by this function from rx_mem_slab (as defined by
     393              :  * i2s_configure). Ownership of the RX memory block is passed on to the user
     394              :  * application which has to release it.
     395              :  *
     396              :  * The data is read in chunks equal to the size of the memory block. If the
     397              :  * interface is in READY state the number of bytes read can be smaller.
     398              :  *
     399              :  * If there is no data in the RX queue the function will block waiting for
     400              :  * the next RX memory block to fill in. This operation can timeout as defined
     401              :  * by i2s_configure. If the timeout value is set to K_NO_WAIT the function
     402              :  * is non-blocking.
     403              :  *
     404              :  * Reading from the RX queue is possible in any state other than NOT_READY.
     405              :  * If the interface is in the ERROR state it is still possible to read all the
     406              :  * valid data stored in RX queue. Afterwards the function will return -EIO
     407              :  * error.
     408              :  *
     409              :  * @param dev Pointer to the device structure for the driver instance.
     410              :  * @param mem_block Pointer to the RX memory block containing received data.
     411              :  * @param size Pointer to the variable storing the number of bytes read.
     412              :  *
     413              :  * @retval 0 If successful.
     414              :  * @retval -EIO The interface is in NOT_READY or ERROR state and there are no
     415              :  *         more data blocks in the RX queue.
     416              :  * @retval -EBUSY Returned without waiting.
     417              :  * @retval -EAGAIN Waiting period timed out.
     418              :  */
     419            1 : static inline int i2s_read(const struct device *dev, void **mem_block,
     420              :                                  size_t *size)
     421              : {
     422              :         const struct i2s_driver_api *api =
     423              :                 (const struct i2s_driver_api *)dev->api;
     424              : 
     425              :         return api->read(dev, mem_block, size);
     426              : }
     427              : 
     428              : /**
     429              :  * @brief Read data from the RX queue into a provided buffer
     430              :  *
     431              :  * Data received by the I2S interface is stored in the RX queue consisting of
     432              :  * memory blocks preallocated by this function from rx_mem_slab (as defined by
     433              :  * i2s_configure). Calling this function removes one block from the queue
     434              :  * which is copied into the provided buffer and then freed.
     435              :  *
     436              :  * The provided buffer must be large enough to contain a full memory block
     437              :  * of data, which is parameterized for the channel via i2s_configure().
     438              :  *
     439              :  * This function is otherwise equivalent to i2s_read().
     440              :  *
     441              :  * @param dev Pointer to the device structure for the driver instance.
     442              :  * @param buf Destination buffer for read data, which must be at least the
     443              :  *            as large as the configured memory block size for the RX channel.
     444              :  * @param size Pointer to the variable storing the number of bytes read.
     445              :  *
     446              :  * @retval 0 If successful.
     447              :  * @retval -EIO The interface is in NOT_READY or ERROR state and there are no
     448              :  *         more data blocks in the RX queue.
     449              :  * @retval -EBUSY Returned without waiting.
     450              :  * @retval -EAGAIN Waiting period timed out.
     451              :  */
     452            1 : __syscall int i2s_buf_read(const struct device *dev, void *buf, size_t *size);
     453              : 
     454              : /**
     455              :  * @brief Write data to the TX queue.
     456              :  *
     457              :  * Data to be sent by the I2S interface is stored first in the TX queue. TX
     458              :  * queue consists of memory blocks preallocated by the user from tx_mem_slab
     459              :  * (as defined by i2s_configure). This function takes ownership of the memory
     460              :  * block and will release it when all data are transmitted.
     461              :  *
     462              :  * If there are no free slots in the TX queue the function will block waiting
     463              :  * for the next TX memory block to be send and removed from the queue. This
     464              :  * operation can timeout as defined by i2s_configure. If the timeout value is
     465              :  * set to K_NO_WAIT the function is non-blocking.
     466              :  *
     467              :  * Writing to the TX queue is only possible if the interface is in READY or
     468              :  * RUNNING state.
     469              :  *
     470              :  * @param dev Pointer to the device structure for the driver instance.
     471              :  * @param mem_block Pointer to the TX memory block containing data to be sent.
     472              :  * @param size Number of bytes to write. This value has to be equal or smaller
     473              :  *        than the size of the memory block.
     474              :  *
     475              :  * @retval 0 If successful.
     476              :  * @retval -EIO The interface is not in READY or RUNNING state.
     477              :  * @retval -EBUSY Returned without waiting.
     478              :  * @retval -EAGAIN Waiting period timed out.
     479              :  */
     480            1 : static inline int i2s_write(const struct device *dev, void *mem_block,
     481              :                             size_t size)
     482              : {
     483              :         const struct i2s_driver_api *api =
     484              :                 (const struct i2s_driver_api *)dev->api;
     485              : 
     486              :         return api->write(dev, mem_block, size);
     487              : }
     488              : 
     489              : /**
     490              :  * @brief Write data to the TX queue from a provided buffer
     491              :  *
     492              :  * This function acquires a memory block from the I2S channel TX queue
     493              :  * and copies the provided data buffer into it. It is otherwise equivalent
     494              :  * to i2s_write().
     495              :  *
     496              :  * @param dev Pointer to the device structure for the driver instance.
     497              :  * @param buf Pointer to a buffer containing the data to transmit.
     498              :  * @param size Number of bytes to write. This value has to be equal or smaller
     499              :  *        than the size of the channel's TX memory block configuration.
     500              :  *
     501              :  * @retval 0 If successful.
     502              :  * @retval -EIO The interface is not in READY or RUNNING state.
     503              :  * @retval -EBUSY Returned without waiting.
     504              :  * @retval -EAGAIN Waiting period timed out.
     505              :  * @retval -ENOMEM No memory in TX slab queue.
     506              :  * @retval -EINVAL Size parameter larger than TX queue memory block.
     507              :  */
     508            1 : __syscall int i2s_buf_write(const struct device *dev, void *buf, size_t size);
     509              : 
     510              : /**
     511              :  * @brief Send a trigger command.
     512              :  *
     513              :  * @param dev Pointer to the device structure for the driver instance.
     514              :  * @param dir Stream direction: RX, TX, or both, as defined by I2S_DIR_*.
     515              :  *            The I2S_DIR_BOTH value may not be supported by some drivers.
     516              :  *            For those, triggering need to be done separately for the RX
     517              :  *            and TX streams.
     518              :  * @param cmd Trigger command.
     519              :  *
     520              :  * @retval 0 If successful.
     521              :  * @retval -EINVAL Invalid argument.
     522              :  * @retval -EIO The trigger cannot be executed in the current state or a DMA
     523              :  *         channel cannot be allocated.
     524              :  * @retval -ENOMEM RX/TX memory block not available.
     525              :  * @retval -ENOSYS I2S_DIR_BOTH value is not supported.
     526              :  */
     527            1 : __syscall int i2s_trigger(const struct device *dev, enum i2s_dir dir,
     528              :                           enum i2s_trigger_cmd cmd);
     529              : 
     530              : static inline int z_impl_i2s_trigger(const struct device *dev,
     531              :                                      enum i2s_dir dir,
     532              :                                      enum i2s_trigger_cmd cmd)
     533              : {
     534              :         const struct i2s_driver_api *api =
     535              :                 (const struct i2s_driver_api *)dev->api;
     536              : 
     537              :         return api->trigger(dev, dir, cmd);
     538              : }
     539              : 
     540              : /**
     541              :  * @}
     542              :  */
     543              : 
     544              : #ifdef __cplusplus
     545              : }
     546              : #endif
     547              : 
     548              : #include <zephyr/syscalls/i2s.h>
     549              : 
     550              : #endif /* ZEPHYR_INCLUDE_DRIVERS_I2S_H_ */
        

Generated by: LCOV version 2.0-1