include/linux/hsi/hsi.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * HSI core header file.
   4  *
   5  * Copyright (C) 2010 Nokia Corporation. All rights reserved.
   6  *
   7  * Contact: Carlos Chinea <carlos.chinea@nokia.com>
   8  */
   9
  10 #ifndef __LINUX_HSI_H__
  11 #define __LINUX_HSI_H__
  12
  13 #include <linux/device.h>
  14 #include <linux/mutex.h>
  15 #include <linux/scatterlist.h>
  16 #include <linux/list.h>
  17 #include <linux/module.h>
  18 #include <linux/notifier.h>
  19
  20 /* HSI message ttype */
  21 #define HSI_MSG_READ    0
  22 #define HSI_MSG_WRITE   1
  23
  24 /* HSI configuration values */
  25 enum {
  26         HSI_MODE_STREAM = 1,
  27         HSI_MODE_FRAME,
  28 };
  29
  30 enum {
  31         HSI_FLOW_SYNC,  /* Synchronized flow */
  32         HSI_FLOW_PIPE,  /* Pipelined flow */
  33 };
  34
  35 enum {
  36         HSI_ARB_RR,     /* Round-robin arbitration */
  37         HSI_ARB_PRIO,   /* Channel priority arbitration */
  38 };
  39
  40 #define HSI_MAX_CHANNELS        16
  41
  42 /* HSI message status codes */
  43 enum {
  44         HSI_STATUS_COMPLETED,   /* Message transfer is completed */
  45         HSI_STATUS_PENDING,     /* Message pending to be read/write (POLL) */
  46         HSI_STATUS_PROCEEDING,  /* Message transfer is ongoing */
  47         HSI_STATUS_QUEUED,      /* Message waiting to be served */
  48         HSI_STATUS_ERROR,       /* Error when message transfer was ongoing */
  49 };
  50
  51 /* HSI port event codes */
  52 enum {
  53         HSI_EVENT_START_RX,
  54         HSI_EVENT_STOP_RX,
  55 };
  56
  57 /**
  58  * struct hsi_channel - channel resource used by the hsi clients
  59  * @id: Channel number
  60  * @name: Channel name
  61  */
  62 struct hsi_channel {
  63         unsigned int    id;
  64         const char      *name;
  65 };
  66
  67 /**
  68  * struct hsi_config - Configuration for RX/TX HSI modules
  69  * @mode: Bit transmission mode (STREAM or FRAME)
  70  * @channels: Channel resources used by the client
  71  * @num_channels: Number of channel resources
  72  * @num_hw_channels: Number of channels the transceiver is configured for [1..16]
  73  * @speed: Max bit transmission speed (Kbit/s)
  74  * @flow: RX flow type (SYNCHRONIZED or PIPELINE)
  75  * @arb_mode: Arbitration mode for TX frame (Round robin, priority)
  76  */
  77 struct hsi_config {
  78         unsigned int            mode;
  79         struct hsi_channel      *channels;
  80         unsigned int            num_channels;
  81         unsigned int            num_hw_channels;
  82         unsigned int            speed;
  83         union {
  84                 unsigned int    flow;           /* RX only */
  85                 unsigned int    arb_mode;       /* TX only */
  86         };
  87 };
  88
  89 /**
  90  * struct hsi_board_info - HSI client board info
  91  * @name: Name for the HSI device
  92  * @hsi_id: HSI controller id where the client sits
  93  * @port: Port number in the controller where the client sits
  94  * @tx_cfg: HSI TX configuration
  95  * @rx_cfg: HSI RX configuration
  96  * @platform_data: Platform related data
  97  * @archdata: Architecture-dependent device data
  98  */
  99 struct hsi_board_info {
 100         const char              *name;
 101         unsigned int            hsi_id;
 102         unsigned int            port;
 103         struct hsi_config       tx_cfg;
 104         struct hsi_config       rx_cfg;
 105         void                    *platform_data;
 106         struct dev_archdata     *archdata;
 107 };
 108
 109 #ifdef CONFIG_HSI_BOARDINFO
 110 extern int hsi_register_board_info(struct hsi_board_info const *info,
 111                                                         unsigned int len);
 112 #else
 113 static inline int hsi_register_board_info(struct hsi_board_info const *info,
 114                                                         unsigned int len)
 115 {
 116         return 0;
 117 }
 118 #endif /* CONFIG_HSI_BOARDINFO */
 119
 120 /**
 121  * struct hsi_client - HSI client attached to an HSI port
 122  * @device: Driver model representation of the device
 123  * @tx_cfg: HSI TX configuration
 124  * @rx_cfg: HSI RX configuration
 125  */
 126 struct hsi_client {
 127         struct device           device;
 128         struct hsi_config       tx_cfg;
 129         struct hsi_config       rx_cfg;
 130         /* private: */
 131         void                    (*ehandler)(struct hsi_client *, unsigned long);
 132         unsigned int            pclaimed:1;
 133         struct notifier_block   nb;
 134 };
 135
 136 #define to_hsi_client(dev) container_of(dev, struct hsi_client, device)
 137
 138 static inline void hsi_client_set_drvdata(struct hsi_client *cl, void *data)
 139 {
 140         dev_set_drvdata(&cl->device, data);
 141 }
 142
 143 static inline void *hsi_client_drvdata(struct hsi_client *cl)
 144 {
 145         return dev_get_drvdata(&cl->device);
 146 }
 147
 148 int hsi_register_port_event(struct hsi_client *cl,
 149                         void (*handler)(struct hsi_client *, unsigned long));
 150 int hsi_unregister_port_event(struct hsi_client *cl);
 151
 152 /**
 153  * struct hsi_client_driver - Driver associated to an HSI client
 154  * @driver: Driver model representation of the driver
 155  */
 156 struct hsi_client_driver {
 157         struct device_driver    driver;
 158 };
 159
 160 #define to_hsi_client_driver(drv) container_of(drv, struct hsi_client_driver,\
 161                                                                         driver)
 162
 163 int hsi_register_client_driver(struct hsi_client_driver *drv);
 164
 165 static inline void hsi_unregister_client_driver(struct hsi_client_driver *drv)
 166 {
 167         driver_unregister(&drv->driver);
 168 }
 169
 170 /**
 171  * struct hsi_msg - HSI message descriptor
 172  * @link: Free to use by the current descriptor owner
 173  * @cl: HSI device client that issues the transfer
 174  * @sgt: Head of the scatterlist array
 175  * @context: Client context data associated to the transfer
 176  * @complete: Transfer completion callback
 177  * @destructor: Destructor to free resources when flushing
 178  * @status: Status of the transfer when completed
 179  * @actual_len: Actual length of data transferred on completion
 180  * @channel: Channel were to TX/RX the message
 181  * @ttype: Transfer type (TX if set, RX otherwise)
 182  * @break_frame: if true HSI will send/receive a break frame. Data buffers are
 183  *              ignored in the request.
 184  */
 185 struct hsi_msg {
 186         struct list_head        link;
 187         struct hsi_client       *cl;
 188         struct sg_table         sgt;
 189         void                    *context;
 190
 191         void                    (*complete)(struct hsi_msg *msg);
 192         void                    (*destructor)(struct hsi_msg *msg);
 193
 194         int                     status;
 195         unsigned int            actual_len;
 196         unsigned int            channel;
 197         unsigned int            ttype:1;
 198         unsigned int            break_frame:1;
 199 };
 200
 201 struct hsi_msg *hsi_alloc_msg(unsigned int n_frag, gfp_t flags);
 202 void hsi_free_msg(struct hsi_msg *msg);
 203
 204 /**
 205  * struct hsi_port - HSI port device
 206  * @device: Driver model representation of the device
 207  * @tx_cfg: Current TX path configuration
 208  * @rx_cfg: Current RX path configuration
 209  * @num: Port number
 210  * @shared: Set when port can be shared by different clients
 211  * @claimed: Reference count of clients which claimed the port
 212  * @lock: Serialize port claim
 213  * @async: Asynchronous transfer callback
 214  * @setup: Callback to set the HSI client configuration
 215  * @flush: Callback to clean the HW state and destroy all pending transfers
 216  * @start_tx: Callback to inform that a client wants to TX data
 217  * @stop_tx: Callback to inform that a client no longer wishes to TX data
 218  * @release: Callback to inform that a client no longer uses the port
 219  * @n_head: Notifier chain for signaling port events to the clients.
 220  */
 221 struct hsi_port {
 222         struct device                   device;
 223         struct hsi_config               tx_cfg;
 224         struct hsi_config               rx_cfg;
 225         unsigned int                    num;
 226         unsigned int                    shared:1;
 227         int                             claimed;
 228         struct mutex                    lock;
 229         int                             (*async)(struct hsi_msg *msg);
 230         int                             (*setup)(struct hsi_client *cl);
 231         int                             (*flush)(struct hsi_client *cl);
 232         int                             (*start_tx)(struct hsi_client *cl);
 233         int                             (*stop_tx)(struct hsi_client *cl);
 234         int                             (*release)(struct hsi_client *cl);
 235         /* private */
 236         struct blocking_notifier_head   n_head;
 237 };
 238
 239 #define to_hsi_port(dev) container_of(dev, struct hsi_port, device)
 240 #define hsi_get_port(cl) to_hsi_port((cl)->device.parent)
 241
 242 int hsi_event(struct hsi_port *port, unsigned long event);
 243 int hsi_claim_port(struct hsi_client *cl, unsigned int share);
 244 void hsi_release_port(struct hsi_client *cl);
 245
 246 static inline int hsi_port_claimed(struct hsi_client *cl)
 247 {
 248         return cl->pclaimed;
 249 }
 250
 251 static inline void hsi_port_set_drvdata(struct hsi_port *port, void *data)
 252 {
 253         dev_set_drvdata(&port->device, data);
 254 }
 255
 256 static inline void *hsi_port_drvdata(struct hsi_port *port)
 257 {
 258         return dev_get_drvdata(&port->device);
 259 }
 260
 261 /**
 262  * struct hsi_controller - HSI controller device
 263  * @device: Driver model representation of the device
 264  * @owner: Pointer to the module owning the controller
 265  * @id: HSI controller ID
 266  * @num_ports: Number of ports in the HSI controller
 267  * @port: Array of HSI ports
 268  */
 269 struct hsi_controller {
 270         struct device           device;
 271         struct module           *owner;
 272         unsigned int            id;
 273         unsigned int            num_ports;
 274         struct hsi_port         **port;
 275 };
 276
 277 #define to_hsi_controller(dev) container_of(dev, struct hsi_controller, device)
 278
 279 struct hsi_controller *hsi_alloc_controller(unsigned int n_ports, gfp_t flags);
 280 void hsi_put_controller(struct hsi_controller *hsi);
 281 int hsi_register_controller(struct hsi_controller *hsi);
 282 void hsi_unregister_controller(struct hsi_controller *hsi);
 283 struct hsi_client *hsi_new_client(struct hsi_port *port,
 284                                                 struct hsi_board_info *info);
 285 int hsi_remove_client(struct device *dev, void *data);
 286 void hsi_port_unregister_clients(struct hsi_port *port);
 287
 288 #ifdef CONFIG_OF
 289 void hsi_add_clients_from_dt(struct hsi_port *port,
 290                              struct device_node *clients);
 291 #else
 292 static inline void hsi_add_clients_from_dt(struct hsi_port *port,
 293                                            struct device_node *clients)
 294 {
 295         return;
 296 }
 297 #endif
 298
 299 static inline void hsi_controller_set_drvdata(struct hsi_controller *hsi,
 300                                                                 void *data)
 301 {
 302         dev_set_drvdata(&hsi->device, data);
 303 }
 304
 305 static inline void *hsi_controller_drvdata(struct hsi_controller *hsi)
 306 {
 307         return dev_get_drvdata(&hsi->device);
 308 }
 309
 310 static inline struct hsi_port *hsi_find_port_num(struct hsi_controller *hsi,
 311                                                         unsigned int num)
 312 {
 313         return (num < hsi->num_ports) ? hsi->port[num] : NULL;
 314 }
 315
 316 /*
 317  * API for HSI clients
 318  */
 319 int hsi_async(struct hsi_client *cl, struct hsi_msg *msg);
 320
 321 int hsi_get_channel_id_by_name(struct hsi_client *cl, char *name);
 322
 323 /**
 324  * hsi_id - Get HSI controller ID associated to a client
 325  * @cl: Pointer to a HSI client
 326  *
 327  * Return the controller id where the client is attached to
 328  */
 329 static inline unsigned int hsi_id(struct hsi_client *cl)
 330 {
 331         return  to_hsi_controller(cl->device.parent->parent)->id;
 332 }
 333
 334 /**
 335  * hsi_port_id - Gets the port number a client is attached to
 336  * @cl: Pointer to HSI client
 337  *
 338  * Return the port number associated to the client
 339  */
 340 static inline unsigned int hsi_port_id(struct hsi_client *cl)
 341 {
 342         return  to_hsi_port(cl->device.parent)->num;
 343 }
 344
 345 /**
 346  * hsi_setup - Configure the client's port
 347  * @cl: Pointer to the HSI client
 348  *
 349  * When sharing ports, clients should either relay on a single
 350  * client setup or have the same setup for all of them.
 351  *
 352  * Return -errno on failure, 0 on success
 353  */
 354 static inline int hsi_setup(struct hsi_client *cl)
 355 {
 356         if (!hsi_port_claimed(cl))
 357                 return -EACCES;
 358         return  hsi_get_port(cl)->setup(cl);
 359 }
 360
 361 /**
 362  * hsi_flush - Flush all pending transactions on the client's port
 363  * @cl: Pointer to the HSI client
 364  *
 365  * This function will destroy all pending hsi_msg in the port and reset
 366  * the HW port so it is ready to receive and transmit from a clean state.
 367  *
 368  * Return -errno on failure, 0 on success
 369  */
 370 static inline int hsi_flush(struct hsi_client *cl)
 371 {
 372         if (!hsi_port_claimed(cl))
 373                 return -EACCES;
 374         return hsi_get_port(cl)->flush(cl);
 375 }
 376
 377 /**
 378  * hsi_async_read - Submit a read transfer
 379  * @cl: Pointer to the HSI client
 380  * @msg: HSI message descriptor of the transfer
 381  *
 382  * Return -errno on failure, 0 on success
 383  */
 384 static inline int hsi_async_read(struct hsi_client *cl, struct hsi_msg *msg)
 385 {
 386         msg->ttype = HSI_MSG_READ;
 387         return hsi_async(cl, msg);
 388 }
 389
 390 /**
 391  * hsi_async_write - Submit a write transfer
 392  * @cl: Pointer to the HSI client
 393  * @msg: HSI message descriptor of the transfer
 394  *
 395  * Return -errno on failure, 0 on success
 396  */
 397 static inline int hsi_async_write(struct hsi_client *cl, struct hsi_msg *msg)
 398 {
 399         msg->ttype = HSI_MSG_WRITE;
 400         return hsi_async(cl, msg);
 401 }
 402
 403 /**
 404  * hsi_start_tx - Signal the port that the client wants to start a TX
 405  * @cl: Pointer to the HSI client
 406  *
 407  * Return -errno on failure, 0 on success
 408  */
 409 static inline int hsi_start_tx(struct hsi_client *cl)
 410 {
 411         if (!hsi_port_claimed(cl))
 412                 return -EACCES;
 413         return hsi_get_port(cl)->start_tx(cl);
 414 }
 415
 416 /**
 417  * hsi_stop_tx - Signal the port that the client no longer wants to transmit
 418  * @cl: Pointer to the HSI client
 419  *
 420  * Return -errno on failure, 0 on success
 421  */
 422 static inline int hsi_stop_tx(struct hsi_client *cl)
 423 {
 424         if (!hsi_port_claimed(cl))
 425                 return -EACCES;
 426         return hsi_get_port(cl)->stop_tx(cl);
 427 }
 428 #endif /* __LINUX_HSI_H__ */