linux/hsi/hsi.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * HSI core header file.
0004  *
0005  * Copyright (C) 2010 Nokia Corporation. All rights reserved.
0006  *
0007  * Contact: Carlos Chinea <carlos.chinea@nokia.com>
0008  */
0009
0010 #ifndef __LINUX_HSI_H__
0011 #define __LINUX_HSI_H__
0012
0013 #include <linux/device.h>
0014 #include <linux/mutex.h>
0015 #include <linux/scatterlist.h>
0016 #include <linux/list.h>
0017 #include <linux/module.h>
0018 #include <linux/notifier.h>
0019
0020 /* HSI message ttype */
0021 #define HSI_MSG_READ    0
0022 #define HSI_MSG_WRITE   1
0023
0024 /* HSI configuration values */
0025 enum {
0026     HSI_MODE_STREAM = 1,
0027     HSI_MODE_FRAME,
0028 };
0029
0030 enum {
0031     HSI_FLOW_SYNC,  /* Synchronized flow */
0032     HSI_FLOW_PIPE,  /* Pipelined flow */
0033 };
0034
0035 enum {
0036     HSI_ARB_RR, /* Round-robin arbitration */
0037     HSI_ARB_PRIO,   /* Channel priority arbitration */
0038 };
0039
0040 #define HSI_MAX_CHANNELS    16
0041
0042 /* HSI message status codes */
0043 enum {
0044     HSI_STATUS_COMPLETED,   /* Message transfer is completed */
0045     HSI_STATUS_PENDING, /* Message pending to be read/write (POLL) */
0046     HSI_STATUS_PROCEEDING,  /* Message transfer is ongoing */
0047     HSI_STATUS_QUEUED,  /* Message waiting to be served */
0048     HSI_STATUS_ERROR,   /* Error when message transfer was ongoing */
0049 };
0050
0051 /* HSI port event codes */
0052 enum {
0053     HSI_EVENT_START_RX,
0054     HSI_EVENT_STOP_RX,
0055 };
0056
0057 /**
0058  * struct hsi_channel - channel resource used by the hsi clients
0059  * @id: Channel number
0060  * @name: Channel name
0061  */
0062 struct hsi_channel {
0063     unsigned int    id;
0064     const char  *name;
0065 };
0066
0067 /**
0068  * struct hsi_config - Configuration for RX/TX HSI modules
0069  * @mode: Bit transmission mode (STREAM or FRAME)
0070  * @channels: Channel resources used by the client
0071  * @num_channels: Number of channel resources
0072  * @num_hw_channels: Number of channels the transceiver is configured for [1..16]
0073  * @speed: Max bit transmission speed (Kbit/s)
0074  * @flow: RX flow type (SYNCHRONIZED or PIPELINE)
0075  * @arb_mode: Arbitration mode for TX frame (Round robin, priority)
0076  */
0077 struct hsi_config {
0078     unsigned int        mode;
0079     struct hsi_channel  *channels;
0080     unsigned int        num_channels;
0081     unsigned int        num_hw_channels;
0082     unsigned int        speed;
0083     union {
0084         unsigned int    flow;       /* RX only */
0085         unsigned int    arb_mode;   /* TX only */
0086     };
0087 };
0088
0089 /**
0090  * struct hsi_board_info - HSI client board info
0091  * @name: Name for the HSI device
0092  * @hsi_id: HSI controller id where the client sits
0093  * @port: Port number in the controller where the client sits
0094  * @tx_cfg: HSI TX configuration
0095  * @rx_cfg: HSI RX configuration
0096  * @platform_data: Platform related data
0097  * @archdata: Architecture-dependent device data
0098  */
0099 struct hsi_board_info {
0100     const char      *name;
0101     unsigned int        hsi_id;
0102     unsigned int        port;
0103     struct hsi_config   tx_cfg;
0104     struct hsi_config   rx_cfg;
0105     void            *platform_data;
0106     struct dev_archdata *archdata;
0107 };
0108
0109 #ifdef CONFIG_HSI_BOARDINFO
0110 extern int hsi_register_board_info(struct hsi_board_info const *info,
0111                             unsigned int len);
0112 #else
0113 static inline int hsi_register_board_info(struct hsi_board_info const *info,
0114                             unsigned int len)
0115 {
0116     return 0;
0117 }
0118 #endif /* CONFIG_HSI_BOARDINFO */
0119
0120 /**
0121  * struct hsi_client - HSI client attached to an HSI port
0122  * @device: Driver model representation of the device
0123  * @tx_cfg: HSI TX configuration
0124  * @rx_cfg: HSI RX configuration
0125  */
0126 struct hsi_client {
0127     struct device       device;
0128     struct hsi_config   tx_cfg;
0129     struct hsi_config   rx_cfg;
0130     /* private: */
0131     void            (*ehandler)(struct hsi_client *, unsigned long);
0132     unsigned int        pclaimed:1;
0133     struct notifier_block   nb;
0134 };
0135
0136 #define to_hsi_client(dev) container_of(dev, struct hsi_client, device)
0137
0138 static inline void hsi_client_set_drvdata(struct hsi_client *cl, void *data)
0139 {
0140     dev_set_drvdata(&cl->device, data);
0141 }
0142
0143 static inline void *hsi_client_drvdata(struct hsi_client *cl)
0144 {
0145     return dev_get_drvdata(&cl->device);
0146 }
0147
0148 int hsi_register_port_event(struct hsi_client *cl,
0149             void (*handler)(struct hsi_client *, unsigned long));
0150 int hsi_unregister_port_event(struct hsi_client *cl);
0151
0152 /**
0153  * struct hsi_client_driver - Driver associated to an HSI client
0154  * @driver: Driver model representation of the driver
0155  */
0156 struct hsi_client_driver {
0157     struct device_driver    driver;
0158 };
0159
0160 #define to_hsi_client_driver(drv) container_of(drv, struct hsi_client_driver,\
0161                                     driver)
0162
0163 int hsi_register_client_driver(struct hsi_client_driver *drv);
0164
0165 static inline void hsi_unregister_client_driver(struct hsi_client_driver *drv)
0166 {
0167     driver_unregister(&drv->driver);
0168 }
0169
0170 /**
0171  * struct hsi_msg - HSI message descriptor
0172  * @link: Free to use by the current descriptor owner
0173  * @cl: HSI device client that issues the transfer
0174  * @sgt: Head of the scatterlist array
0175  * @context: Client context data associated to the transfer
0176  * @complete: Transfer completion callback
0177  * @destructor: Destructor to free resources when flushing
0178  * @status: Status of the transfer when completed
0179  * @actual_len: Actual length of data transferred on completion
0180  * @channel: Channel were to TX/RX the message
0181  * @ttype: Transfer type (TX if set, RX otherwise)
0182  * @break_frame: if true HSI will send/receive a break frame. Data buffers are
0183  *      ignored in the request.
0184  */
0185 struct hsi_msg {
0186     struct list_head    link;
0187     struct hsi_client   *cl;
0188     struct sg_table     sgt;
0189     void            *context;
0190
0191     void            (*complete)(struct hsi_msg *msg);
0192     void            (*destructor)(struct hsi_msg *msg);
0193
0194     int         status;
0195     unsigned int        actual_len;
0196     unsigned int        channel;
0197     unsigned int        ttype:1;
0198     unsigned int        break_frame:1;
0199 };
0200
0201 struct hsi_msg *hsi_alloc_msg(unsigned int n_frag, gfp_t flags);
0202 void hsi_free_msg(struct hsi_msg *msg);
0203
0204 /**
0205  * struct hsi_port - HSI port device
0206  * @device: Driver model representation of the device
0207  * @tx_cfg: Current TX path configuration
0208  * @rx_cfg: Current RX path configuration
0209  * @num: Port number
0210  * @shared: Set when port can be shared by different clients
0211  * @claimed: Reference count of clients which claimed the port
0212  * @lock: Serialize port claim
0213  * @async: Asynchronous transfer callback
0214  * @setup: Callback to set the HSI client configuration
0215  * @flush: Callback to clean the HW state and destroy all pending transfers
0216  * @start_tx: Callback to inform that a client wants to TX data
0217  * @stop_tx: Callback to inform that a client no longer wishes to TX data
0218  * @release: Callback to inform that a client no longer uses the port
0219  * @n_head: Notifier chain for signaling port events to the clients.
0220  */
0221 struct hsi_port {
0222     struct device           device;
0223     struct hsi_config       tx_cfg;
0224     struct hsi_config       rx_cfg;
0225     unsigned int            num;
0226     unsigned int            shared:1;
0227     int             claimed;
0228     struct mutex            lock;
0229     int             (*async)(struct hsi_msg *msg);
0230     int             (*setup)(struct hsi_client *cl);
0231     int             (*flush)(struct hsi_client *cl);
0232     int             (*start_tx)(struct hsi_client *cl);
0233     int             (*stop_tx)(struct hsi_client *cl);
0234     int             (*release)(struct hsi_client *cl);
0235     /* private */
0236     struct blocking_notifier_head   n_head;
0237 };
0238
0239 #define to_hsi_port(dev) container_of(dev, struct hsi_port, device)
0240 #define hsi_get_port(cl) to_hsi_port((cl)->device.parent)
0241
0242 int hsi_event(struct hsi_port *port, unsigned long event);
0243 int hsi_claim_port(struct hsi_client *cl, unsigned int share);
0244 void hsi_release_port(struct hsi_client *cl);
0245
0246 static inline int hsi_port_claimed(struct hsi_client *cl)
0247 {
0248     return cl->pclaimed;
0249 }
0250
0251 static inline void hsi_port_set_drvdata(struct hsi_port *port, void *data)
0252 {
0253     dev_set_drvdata(&port->device, data);
0254 }
0255
0256 static inline void *hsi_port_drvdata(struct hsi_port *port)
0257 {
0258     return dev_get_drvdata(&port->device);
0259 }
0260
0261 /**
0262  * struct hsi_controller - HSI controller device
0263  * @device: Driver model representation of the device
0264  * @owner: Pointer to the module owning the controller
0265  * @id: HSI controller ID
0266  * @num_ports: Number of ports in the HSI controller
0267  * @port: Array of HSI ports
0268  */
0269 struct hsi_controller {
0270     struct device       device;
0271     struct module       *owner;
0272     unsigned int        id;
0273     unsigned int        num_ports;
0274     struct hsi_port     **port;
0275 };
0276
0277 #define to_hsi_controller(dev) container_of(dev, struct hsi_controller, device)
0278
0279 struct hsi_controller *hsi_alloc_controller(unsigned int n_ports, gfp_t flags);
0280 void hsi_put_controller(struct hsi_controller *hsi);
0281 int hsi_register_controller(struct hsi_controller *hsi);
0282 void hsi_unregister_controller(struct hsi_controller *hsi);
0283 struct hsi_client *hsi_new_client(struct hsi_port *port,
0284                         struct hsi_board_info *info);
0285 int hsi_remove_client(struct device *dev, void *data);
0286 void hsi_port_unregister_clients(struct hsi_port *port);
0287
0288 #ifdef CONFIG_OF
0289 void hsi_add_clients_from_dt(struct hsi_port *port,
0290                  struct device_node *clients);
0291 #else
0292 static inline void hsi_add_clients_from_dt(struct hsi_port *port,
0293                        struct device_node *clients)
0294 {
0295     return;
0296 }
0297 #endif
0298
0299 static inline void hsi_controller_set_drvdata(struct hsi_controller *hsi,
0300                                 void *data)
0301 {
0302     dev_set_drvdata(&hsi->device, data);
0303 }
0304
0305 static inline void *hsi_controller_drvdata(struct hsi_controller *hsi)
0306 {
0307     return dev_get_drvdata(&hsi->device);
0308 }
0309
0310 static inline struct hsi_port *hsi_find_port_num(struct hsi_controller *hsi,
0311                             unsigned int num)
0312 {
0313     return (num < hsi->num_ports) ? hsi->port[num] : NULL;
0314 }
0315
0316 /*
0317  * API for HSI clients
0318  */
0319 int hsi_async(struct hsi_client *cl, struct hsi_msg *msg);
0320
0321 int hsi_get_channel_id_by_name(struct hsi_client *cl, char *name);
0322
0323 /**
0324  * hsi_id - Get HSI controller ID associated to a client
0325  * @cl: Pointer to a HSI client
0326  *
0327  * Return the controller id where the client is attached to
0328  */
0329 static inline unsigned int hsi_id(struct hsi_client *cl)
0330 {
0331     return  to_hsi_controller(cl->device.parent->parent)->id;
0332 }
0333
0334 /**
0335  * hsi_port_id - Gets the port number a client is attached to
0336  * @cl: Pointer to HSI client
0337  *
0338  * Return the port number associated to the client
0339  */
0340 static inline unsigned int hsi_port_id(struct hsi_client *cl)
0341 {
0342     return  to_hsi_port(cl->device.parent)->num;
0343 }
0344
0345 /**
0346  * hsi_setup - Configure the client's port
0347  * @cl: Pointer to the HSI client
0348  *
0349  * When sharing ports, clients should either relay on a single
0350  * client setup or have the same setup for all of them.
0351  *
0352  * Return -errno on failure, 0 on success
0353  */
0354 static inline int hsi_setup(struct hsi_client *cl)
0355 {
0356     if (!hsi_port_claimed(cl))
0357         return -EACCES;
0358     return  hsi_get_port(cl)->setup(cl);
0359 }
0360
0361 /**
0362  * hsi_flush - Flush all pending transactions on the client's port
0363  * @cl: Pointer to the HSI client
0364  *
0365  * This function will destroy all pending hsi_msg in the port and reset
0366  * the HW port so it is ready to receive and transmit from a clean state.
0367  *
0368  * Return -errno on failure, 0 on success
0369  */
0370 static inline int hsi_flush(struct hsi_client *cl)
0371 {
0372     if (!hsi_port_claimed(cl))
0373         return -EACCES;
0374     return hsi_get_port(cl)->flush(cl);
0375 }
0376
0377 /**
0378  * hsi_async_read - Submit a read transfer
0379  * @cl: Pointer to the HSI client
0380  * @msg: HSI message descriptor of the transfer
0381  *
0382  * Return -errno on failure, 0 on success
0383  */
0384 static inline int hsi_async_read(struct hsi_client *cl, struct hsi_msg *msg)
0385 {
0386     msg->ttype = HSI_MSG_READ;
0387     return hsi_async(cl, msg);
0388 }
0389
0390 /**
0391  * hsi_async_write - Submit a write transfer
0392  * @cl: Pointer to the HSI client
0393  * @msg: HSI message descriptor of the transfer
0394  *
0395  * Return -errno on failure, 0 on success
0396  */
0397 static inline int hsi_async_write(struct hsi_client *cl, struct hsi_msg *msg)
0398 {
0399     msg->ttype = HSI_MSG_WRITE;
0400     return hsi_async(cl, msg);
0401 }
0402
0403 /**
0404  * hsi_start_tx - Signal the port that the client wants to start a TX
0405  * @cl: Pointer to the HSI client
0406  *
0407  * Return -errno on failure, 0 on success
0408  */
0409 static inline int hsi_start_tx(struct hsi_client *cl)
0410 {
0411     if (!hsi_port_claimed(cl))
0412         return -EACCES;
0413     return hsi_get_port(cl)->start_tx(cl);
0414 }
0415
0416 /**
0417  * hsi_stop_tx - Signal the port that the client no longer wants to transmit
0418  * @cl: Pointer to the HSI client
0419  *
0420  * Return -errno on failure, 0 on success
0421  */
0422 static inline int hsi_stop_tx(struct hsi_client *cl)
0423 {
0424     if (!hsi_port_claimed(cl))
0425         return -EACCES;
0426     return hsi_get_port(cl)->stop_tx(cl);
0427 }
0428 #endif /* __LINUX_HSI_H__ */