linux/iio/consumer.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Industrial I/O in kernel consumer interface
0004  *
0005  * Copyright (c) 2011 Jonathan Cameron
0006  */
0007 #ifndef _IIO_INKERN_CONSUMER_H_
0008 #define _IIO_INKERN_CONSUMER_H_
0009
0010 #include <linux/types.h>
0011 #include <linux/iio/types.h>
0012
0013 struct iio_dev;
0014 struct iio_chan_spec;
0015 struct device;
0016 struct device_node;
0017
0018 /**
0019  * struct iio_channel - everything needed for a consumer to use a channel
0020  * @indio_dev:      Device on which the channel exists.
0021  * @channel:        Full description of the channel.
0022  * @data:       Data about the channel used by consumer.
0023  */
0024 struct iio_channel {
0025     struct iio_dev *indio_dev;
0026     const struct iio_chan_spec *channel;
0027     void *data;
0028 };
0029
0030 /**
0031  * iio_channel_get() - get description of all that is needed to access channel.
0032  * @dev:        Pointer to consumer device. Device name must match
0033  *          the name of the device as provided in the iio_map
0034  *          with which the desired provider to consumer mapping
0035  *          was registered.
0036  * @consumer_channel:   Unique name to identify the channel on the consumer
0037  *          side. This typically describes the channels use within
0038  *          the consumer. E.g. 'battery_voltage'
0039  */
0040 struct iio_channel *iio_channel_get(struct device *dev,
0041                     const char *consumer_channel);
0042
0043 /**
0044  * iio_channel_release() - release channels obtained via iio_channel_get
0045  * @chan:       The channel to be released.
0046  */
0047 void iio_channel_release(struct iio_channel *chan);
0048
0049 /**
0050  * devm_iio_channel_get() - Resource managed version of iio_channel_get().
0051  * @dev:        Pointer to consumer device. Device name must match
0052  *          the name of the device as provided in the iio_map
0053  *          with which the desired provider to consumer mapping
0054  *          was registered.
0055  * @consumer_channel:   Unique name to identify the channel on the consumer
0056  *          side. This typically describes the channels use within
0057  *          the consumer. E.g. 'battery_voltage'
0058  *
0059  * Returns a pointer to negative errno if it is not able to get the iio channel
0060  * otherwise returns valid pointer for iio channel.
0061  *
0062  * The allocated iio channel is automatically released when the device is
0063  * unbound.
0064  */
0065 struct iio_channel *devm_iio_channel_get(struct device *dev,
0066                      const char *consumer_channel);
0067 /**
0068  * iio_channel_get_all() - get all channels associated with a client
0069  * @dev:        Pointer to consumer device.
0070  *
0071  * Returns an array of iio_channel structures terminated with one with
0072  * null iio_dev pointer.
0073  * This function is used by fairly generic consumers to get all the
0074  * channels registered as having this consumer.
0075  */
0076 struct iio_channel *iio_channel_get_all(struct device *dev);
0077
0078 /**
0079  * iio_channel_release_all() - reverse iio_channel_get_all
0080  * @chan:       Array of channels to be released.
0081  */
0082 void iio_channel_release_all(struct iio_channel *chan);
0083
0084 /**
0085  * devm_iio_channel_get_all() - Resource managed version of
0086  *              iio_channel_get_all().
0087  * @dev: Pointer to consumer device.
0088  *
0089  * Returns a pointer to negative errno if it is not able to get the iio channel
0090  * otherwise returns an array of iio_channel structures terminated with one with
0091  * null iio_dev pointer.
0092  *
0093  * This function is used by fairly generic consumers to get all the
0094  * channels registered as having this consumer.
0095  *
0096  * The allocated iio channels are automatically released when the device is
0097  * unbounded.
0098  */
0099 struct iio_channel *devm_iio_channel_get_all(struct device *dev);
0100
0101 /**
0102  * of_iio_channel_get_by_name() - get description of all that is needed to access channel.
0103  * @np:         Pointer to consumer device tree node
0104  * @consumer_channel:   Unique name to identify the channel on the consumer
0105  *          side. This typically describes the channels use within
0106  *          the consumer. E.g. 'battery_voltage'
0107  */
0108 #ifdef CONFIG_OF
0109 struct iio_channel *of_iio_channel_get_by_name(struct device_node *np, const char *name);
0110 #else
0111 static inline struct iio_channel *
0112 of_iio_channel_get_by_name(struct device_node *np, const char *name)
0113 {
0114     return NULL;
0115 }
0116 #endif
0117
0118 /**
0119  * devm_of_iio_channel_get_by_name() - Resource managed version of of_iio_channel_get_by_name().
0120  * @dev:        Pointer to consumer device.
0121  * @np:         Pointer to consumer device tree node
0122  * @consumer_channel:   Unique name to identify the channel on the consumer
0123  *          side. This typically describes the channels use within
0124  *          the consumer. E.g. 'battery_voltage'
0125  *
0126  * Returns a pointer to negative errno if it is not able to get the iio channel
0127  * otherwise returns valid pointer for iio channel.
0128  *
0129  * The allocated iio channel is automatically released when the device is
0130  * unbound.
0131  */
0132 struct iio_channel *devm_of_iio_channel_get_by_name(struct device *dev,
0133                             struct device_node *np,
0134                             const char *consumer_channel);
0135
0136 struct iio_cb_buffer;
0137 /**
0138  * iio_channel_get_all_cb() - register callback for triggered capture
0139  * @dev:        Pointer to client device.
0140  * @cb:         Callback function.
0141  * @private:        Private data passed to callback.
0142  *
0143  * NB right now we have no ability to mux data from multiple devices.
0144  * So if the channels requested come from different devices this will
0145  * fail.
0146  */
0147 struct iio_cb_buffer *iio_channel_get_all_cb(struct device *dev,
0148                          int (*cb)(const void *data,
0149                                void *private),
0150                          void *private);
0151 /**
0152  * iio_channel_cb_set_buffer_watermark() - set the buffer watermark.
0153  * @cb_buffer:      The callback buffer from whom we want the channel
0154  *          information.
0155  * @watermark: buffer watermark in bytes.
0156  *
0157  * This function allows to configure the buffer watermark.
0158  */
0159 int iio_channel_cb_set_buffer_watermark(struct iio_cb_buffer *cb_buffer,
0160                     size_t watermark);
0161
0162 /**
0163  * iio_channel_release_all_cb() - release and unregister the callback.
0164  * @cb_buffer:      The callback buffer that was allocated.
0165  */
0166 void iio_channel_release_all_cb(struct iio_cb_buffer *cb_buffer);
0167
0168 /**
0169  * iio_channel_start_all_cb() - start the flow of data through callback.
0170  * @cb_buff:        The callback buffer we are starting.
0171  */
0172 int iio_channel_start_all_cb(struct iio_cb_buffer *cb_buff);
0173
0174 /**
0175  * iio_channel_stop_all_cb() - stop the flow of data through the callback.
0176  * @cb_buff:        The callback buffer we are stopping.
0177  */
0178 void iio_channel_stop_all_cb(struct iio_cb_buffer *cb_buff);
0179
0180 /**
0181  * iio_channel_cb_get_channels() - get access to the underlying channels.
0182  * @cb_buffer:      The callback buffer from whom we want the channel
0183  *          information.
0184  *
0185  * This function allows one to obtain information about the channels.
0186  * Whilst this may allow direct reading if all buffers are disabled, the
0187  * primary aim is to allow drivers that are consuming a channel to query
0188  * things like scaling of the channel.
0189  */
0190 struct iio_channel
0191 *iio_channel_cb_get_channels(const struct iio_cb_buffer *cb_buffer);
0192
0193 /**
0194  * iio_channel_cb_get_iio_dev() - get access to the underlying device.
0195  * @cb_buffer:      The callback buffer from whom we want the device
0196  *          information.
0197  *
0198  * This function allows one to obtain information about the device.
0199  * The primary aim is to allow drivers that are consuming a device to query
0200  * things like current trigger.
0201  */
0202 struct iio_dev
0203 *iio_channel_cb_get_iio_dev(const struct iio_cb_buffer *cb_buffer);
0204
0205 /**
0206  * iio_read_channel_raw() - read from a given channel
0207  * @chan:       The channel being queried.
0208  * @val:        Value read back.
0209  *
0210  * Note raw reads from iio channels are in adc counts and hence
0211  * scale will need to be applied if standard units required.
0212  */
0213 int iio_read_channel_raw(struct iio_channel *chan,
0214              int *val);
0215
0216 /**
0217  * iio_read_channel_average_raw() - read from a given channel
0218  * @chan:       The channel being queried.
0219  * @val:        Value read back.
0220  *
0221  * Note raw reads from iio channels are in adc counts and hence
0222  * scale will need to be applied if standard units required.
0223  *
0224  * In opposit to the normal iio_read_channel_raw this function
0225  * returns the average of multiple reads.
0226  */
0227 int iio_read_channel_average_raw(struct iio_channel *chan, int *val);
0228
0229 /**
0230  * iio_read_channel_processed() - read processed value from a given channel
0231  * @chan:       The channel being queried.
0232  * @val:        Value read back.
0233  *
0234  * Returns an error code or 0.
0235  *
0236  * This function will read a processed value from a channel. A processed value
0237  * means that this value will have the correct unit and not some device internal
0238  * representation. If the device does not support reporting a processed value
0239  * the function will query the raw value and the channels scale and offset and
0240  * do the appropriate transformation.
0241  */
0242 int iio_read_channel_processed(struct iio_channel *chan, int *val);
0243
0244 /**
0245  * iio_read_channel_processed_scale() - read and scale a processed value
0246  * @chan:       The channel being queried.
0247  * @val:        Value read back.
0248  * @scale:      Scale factor to apply during the conversion
0249  *
0250  * Returns an error code or 0.
0251  *
0252  * This function will read a processed value from a channel. This will work
0253  * like @iio_read_channel_processed() but also scale with an additional
0254  * scale factor while attempting to minimize any precision loss.
0255  */
0256 int iio_read_channel_processed_scale(struct iio_channel *chan, int *val,
0257                      unsigned int scale);
0258
0259 /**
0260  * iio_write_channel_attribute() - Write values to the device attribute.
0261  * @chan:   The channel being queried.
0262  * @val:    Value being written.
0263  * @val2:   Value being written.val2 use depends on attribute type.
0264  * @attribute:  info attribute to be read.
0265  *
0266  * Returns an error code or 0.
0267  */
0268 int iio_write_channel_attribute(struct iio_channel *chan, int val,
0269                 int val2, enum iio_chan_info_enum attribute);
0270
0271 /**
0272  * iio_read_channel_attribute() - Read values from the device attribute.
0273  * @chan:   The channel being queried.
0274  * @val:    Value being written.
0275  * @val2:   Value being written.Val2 use depends on attribute type.
0276  * @attribute:  info attribute to be written.
0277  *
0278  * Returns an error code if failed. Else returns a description of what is in val
0279  * and val2, such as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val
0280  * + val2/1e6
0281  */
0282 int iio_read_channel_attribute(struct iio_channel *chan, int *val,
0283                    int *val2, enum iio_chan_info_enum attribute);
0284
0285 /**
0286  * iio_write_channel_raw() - write to a given channel
0287  * @chan:       The channel being queried.
0288  * @val:        Value being written.
0289  *
0290  * Note raw writes to iio channels are in dac counts and hence
0291  * scale will need to be applied if standard units required.
0292  */
0293 int iio_write_channel_raw(struct iio_channel *chan, int val);
0294
0295 /**
0296  * iio_read_max_channel_raw() - read maximum available raw value from a given
0297  *              channel, i.e. the maximum possible value.
0298  * @chan:       The channel being queried.
0299  * @val:        Value read back.
0300  *
0301  * Note raw reads from iio channels are in adc counts and hence
0302  * scale will need to be applied if standard units are required.
0303  */
0304 int iio_read_max_channel_raw(struct iio_channel *chan, int *val);
0305
0306 /**
0307  * iio_read_avail_channel_raw() - read available raw values from a given channel
0308  * @chan:       The channel being queried.
0309  * @vals:       Available values read back.
0310  * @length:     Number of entries in vals.
0311  *
0312  * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST.
0313  *
0314  * For ranges, three vals are always returned; min, step and max.
0315  * For lists, all the possible values are enumerated.
0316  *
0317  * Note raw available values from iio channels are in adc counts and
0318  * hence scale will need to be applied if standard units are required.
0319  */
0320 int iio_read_avail_channel_raw(struct iio_channel *chan,
0321                    const int **vals, int *length);
0322
0323 /**
0324  * iio_read_avail_channel_attribute() - read available channel attribute values
0325  * @chan:       The channel being queried.
0326  * @vals:       Available values read back.
0327  * @type:       Type of values read back.
0328  * @length:     Number of entries in vals.
0329  * @attribute:      info attribute to be read back.
0330  *
0331  * Returns an error code, IIO_AVAIL_RANGE or IIO_AVAIL_LIST.
0332  */
0333 int iio_read_avail_channel_attribute(struct iio_channel *chan,
0334                      const int **vals, int *type, int *length,
0335                      enum iio_chan_info_enum attribute);
0336
0337 /**
0338  * iio_get_channel_type() - get the type of a channel
0339  * @channel:        The channel being queried.
0340  * @type:       The type of the channel.
0341  *
0342  * returns the enum iio_chan_type of the channel
0343  */
0344 int iio_get_channel_type(struct iio_channel *channel,
0345              enum iio_chan_type *type);
0346
0347 /**
0348  * iio_read_channel_offset() - read the offset value for a channel
0349  * @chan:       The channel being queried.
0350  * @val:        First part of value read back.
0351  * @val2:       Second part of value read back.
0352  *
0353  * Note returns a description of what is in val and val2, such
0354  * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val
0355  * + val2/1e6
0356  */
0357 int iio_read_channel_offset(struct iio_channel *chan, int *val,
0358                int *val2);
0359
0360 /**
0361  * iio_read_channel_scale() - read the scale value for a channel
0362  * @chan:       The channel being queried.
0363  * @val:        First part of value read back.
0364  * @val2:       Second part of value read back.
0365  *
0366  * Note returns a description of what is in val and val2, such
0367  * as IIO_VAL_INT_PLUS_MICRO telling us we have a value of val
0368  * + val2/1e6
0369  */
0370 int iio_read_channel_scale(struct iio_channel *chan, int *val,
0371                int *val2);
0372
0373 /**
0374  * iio_convert_raw_to_processed() - Converts a raw value to a processed value
0375  * @chan:       The channel being queried
0376  * @raw:        The raw IIO to convert
0377  * @processed:      The result of the conversion
0378  * @scale:      Scale factor to apply during the conversion
0379  *
0380  * Returns an error code or 0.
0381  *
0382  * This function converts a raw value to processed value for a specific channel.
0383  * A raw value is the device internal representation of a sample and the value
0384  * returned by iio_read_channel_raw, so the unit of that value is device
0385  * depended. A processed value on the other hand is value has a normed unit
0386  * according with the IIO specification.
0387  *
0388  * The scale factor allows to increase the precession of the returned value. For
0389  * a scale factor of 1 the function will return the result in the normal IIO
0390  * unit for the channel type. E.g. millivolt for voltage channels, if you want
0391  * nanovolts instead pass 1000000 as the scale factor.
0392  */
0393 int iio_convert_raw_to_processed(struct iio_channel *chan, int raw,
0394     int *processed, unsigned int scale);
0395
0396 /**
0397  * iio_get_channel_ext_info_count() - get number of ext_info attributes
0398  *                    connected to the channel.
0399  * @chan:       The channel being queried
0400  *
0401  * Returns the number of ext_info attributes
0402  */
0403 unsigned int iio_get_channel_ext_info_count(struct iio_channel *chan);
0404
0405 /**
0406  * iio_read_channel_ext_info() - read ext_info attribute from a given channel
0407  * @chan:       The channel being queried.
0408  * @attr:       The ext_info attribute to read.
0409  * @buf:        Where to store the attribute value. Assumed to hold
0410  *          at least PAGE_SIZE bytes.
0411  *
0412  * Returns the number of bytes written to buf (perhaps w/o zero termination;
0413  * it need not even be a string), or an error code.
0414  */
0415 ssize_t iio_read_channel_ext_info(struct iio_channel *chan,
0416                   const char *attr, char *buf);
0417
0418 /**
0419  * iio_write_channel_ext_info() - write ext_info attribute from a given channel
0420  * @chan:       The channel being queried.
0421  * @attr:       The ext_info attribute to read.
0422  * @buf:        The new attribute value. Strings needs to be zero-
0423  *          terminated, but the terminator should not be included
0424  *          in the below len.
0425  * @len:        The size of the new attribute value.
0426  *
0427  * Returns the number of accepted bytes, which should be the same as len.
0428  * An error code can also be returned.
0429  */
0430 ssize_t iio_write_channel_ext_info(struct iio_channel *chan, const char *attr,
0431                    const char *buf, size_t len);
0432
0433 #endif