include/linux/firewire.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _LINUX_FIREWIRE_H
0003 #define _LINUX_FIREWIRE_H
0004
0005 #include <linux/completion.h>
0006 #include <linux/device.h>
0007 #include <linux/dma-mapping.h>
0008 #include <linux/kernel.h>
0009 #include <linux/kref.h>
0010 #include <linux/list.h>
0011 #include <linux/mutex.h>
0012 #include <linux/spinlock.h>
0013 #include <linux/sysfs.h>
0014 #include <linux/timer.h>
0015 #include <linux/types.h>
0016 #include <linux/workqueue.h>
0017
0018 #include <linux/atomic.h>
0019 #include <asm/byteorder.h>
0020
0021 #define CSR_REGISTER_BASE       0xfffff0000000ULL
0022
0023 /* register offsets are relative to CSR_REGISTER_BASE */
0024 #define CSR_STATE_CLEAR         0x0
0025 #define CSR_STATE_SET           0x4
0026 #define CSR_NODE_IDS            0x8
0027 #define CSR_RESET_START         0xc
0028 #define CSR_SPLIT_TIMEOUT_HI        0x18
0029 #define CSR_SPLIT_TIMEOUT_LO        0x1c
0030 #define CSR_CYCLE_TIME          0x200
0031 #define CSR_BUS_TIME            0x204
0032 #define CSR_BUSY_TIMEOUT        0x210
0033 #define CSR_PRIORITY_BUDGET     0x218
0034 #define CSR_BUS_MANAGER_ID      0x21c
0035 #define CSR_BANDWIDTH_AVAILABLE     0x220
0036 #define CSR_CHANNELS_AVAILABLE      0x224
0037 #define CSR_CHANNELS_AVAILABLE_HI   0x224
0038 #define CSR_CHANNELS_AVAILABLE_LO   0x228
0039 #define CSR_MAINT_UTILITY       0x230
0040 #define CSR_BROADCAST_CHANNEL       0x234
0041 #define CSR_CONFIG_ROM          0x400
0042 #define CSR_CONFIG_ROM_END      0x800
0043 #define CSR_OMPR            0x900
0044 #define CSR_OPCR(i)         (0x904 + (i) * 4)
0045 #define CSR_IMPR            0x980
0046 #define CSR_IPCR(i)         (0x984 + (i) * 4)
0047 #define CSR_FCP_COMMAND         0xB00
0048 #define CSR_FCP_RESPONSE        0xD00
0049 #define CSR_FCP_END         0xF00
0050 #define CSR_TOPOLOGY_MAP        0x1000
0051 #define CSR_TOPOLOGY_MAP_END        0x1400
0052 #define CSR_SPEED_MAP           0x2000
0053 #define CSR_SPEED_MAP_END       0x3000
0054
0055 #define CSR_OFFSET      0x40
0056 #define CSR_LEAF        0x80
0057 #define CSR_DIRECTORY       0xc0
0058
0059 #define CSR_DESCRIPTOR      0x01
0060 #define CSR_VENDOR      0x03
0061 #define CSR_HARDWARE_VERSION    0x04
0062 #define CSR_UNIT        0x11
0063 #define CSR_SPECIFIER_ID    0x12
0064 #define CSR_VERSION     0x13
0065 #define CSR_DEPENDENT_INFO  0x14
0066 #define CSR_MODEL       0x17
0067 #define CSR_DIRECTORY_ID    0x20
0068
0069 struct fw_csr_iterator {
0070     const u32 *p;
0071     const u32 *end;
0072 };
0073
0074 void fw_csr_iterator_init(struct fw_csr_iterator *ci, const u32 *p);
0075 int fw_csr_iterator_next(struct fw_csr_iterator *ci, int *key, int *value);
0076 int fw_csr_string(const u32 *directory, int key, char *buf, size_t size);
0077
0078 extern struct bus_type fw_bus_type;
0079
0080 struct fw_card_driver;
0081 struct fw_node;
0082
0083 struct fw_card {
0084     const struct fw_card_driver *driver;
0085     struct device *device;
0086     struct kref kref;
0087     struct completion done;
0088
0089     int node_id;
0090     int generation;
0091     int current_tlabel;
0092     u64 tlabel_mask;
0093     struct list_head transaction_list;
0094     u64 reset_jiffies;
0095
0096     u32 split_timeout_hi;
0097     u32 split_timeout_lo;
0098     unsigned int split_timeout_cycles;
0099     unsigned int split_timeout_jiffies;
0100
0101     unsigned long long guid;
0102     unsigned max_receive;
0103     int link_speed;
0104     int config_rom_generation;
0105
0106     spinlock_t lock; /* Take this lock when handling the lists in
0107               * this struct. */
0108     struct fw_node *local_node;
0109     struct fw_node *root_node;
0110     struct fw_node *irm_node;
0111     u8 color; /* must be u8 to match the definition in struct fw_node */
0112     int gap_count;
0113     bool beta_repeaters_present;
0114
0115     int index;
0116     struct list_head link;
0117
0118     struct list_head phy_receiver_list;
0119
0120     struct delayed_work br_work; /* bus reset job */
0121     bool br_short;
0122
0123     struct delayed_work bm_work; /* bus manager job */
0124     int bm_retries;
0125     int bm_generation;
0126     int bm_node_id;
0127     bool bm_abdicate;
0128
0129     bool priority_budget_implemented;   /* controller feature */
0130     bool broadcast_channel_auto_allocated;  /* controller feature */
0131
0132     bool broadcast_channel_allocated;
0133     u32 broadcast_channel;
0134     __be32 topology_map[(CSR_TOPOLOGY_MAP_END - CSR_TOPOLOGY_MAP) / 4];
0135
0136     __be32 maint_utility_register;
0137 };
0138
0139 static inline struct fw_card *fw_card_get(struct fw_card *card)
0140 {
0141     kref_get(&card->kref);
0142
0143     return card;
0144 }
0145
0146 void fw_card_release(struct kref *kref);
0147
0148 static inline void fw_card_put(struct fw_card *card)
0149 {
0150     kref_put(&card->kref, fw_card_release);
0151 }
0152
0153 int fw_card_read_cycle_time(struct fw_card *card, u32 *cycle_time);
0154
0155 struct fw_attribute_group {
0156     struct attribute_group *groups[2];
0157     struct attribute_group group;
0158     struct attribute *attrs[13];
0159 };
0160
0161 enum fw_device_state {
0162     FW_DEVICE_INITIALIZING,
0163     FW_DEVICE_RUNNING,
0164     FW_DEVICE_GONE,
0165     FW_DEVICE_SHUTDOWN,
0166 };
0167
0168 /*
0169  * Note, fw_device.generation always has to be read before fw_device.node_id.
0170  * Use SMP memory barriers to ensure this.  Otherwise requests will be sent
0171  * to an outdated node_id if the generation was updated in the meantime due
0172  * to a bus reset.
0173  *
0174  * Likewise, fw-core will take care to update .node_id before .generation so
0175  * that whenever fw_device.generation is current WRT the actual bus generation,
0176  * fw_device.node_id is guaranteed to be current too.
0177  *
0178  * The same applies to fw_device.card->node_id vs. fw_device.generation.
0179  *
0180  * fw_device.config_rom and fw_device.config_rom_length may be accessed during
0181  * the lifetime of any fw_unit belonging to the fw_device, before device_del()
0182  * was called on the last fw_unit.  Alternatively, they may be accessed while
0183  * holding fw_device_rwsem.
0184  */
0185 struct fw_device {
0186     atomic_t state;
0187     struct fw_node *node;
0188     int node_id;
0189     int generation;
0190     unsigned max_speed;
0191     struct fw_card *card;
0192     struct device device;
0193
0194     struct mutex client_list_mutex;
0195     struct list_head client_list;
0196
0197     const u32 *config_rom;
0198     size_t config_rom_length;
0199     int config_rom_retries;
0200     unsigned is_local:1;
0201     unsigned max_rec:4;
0202     unsigned cmc:1;
0203     unsigned irmc:1;
0204     unsigned bc_implemented:2;
0205
0206     work_func_t workfn;
0207     struct delayed_work work;
0208     struct fw_attribute_group attribute_group;
0209 };
0210
0211 static inline struct fw_device *fw_device(struct device *dev)
0212 {
0213     return container_of(dev, struct fw_device, device);
0214 }
0215
0216 static inline int fw_device_is_shutdown(struct fw_device *device)
0217 {
0218     return atomic_read(&device->state) == FW_DEVICE_SHUTDOWN;
0219 }
0220
0221 int fw_device_enable_phys_dma(struct fw_device *device);
0222
0223 /*
0224  * fw_unit.directory must not be accessed after device_del(&fw_unit.device).
0225  */
0226 struct fw_unit {
0227     struct device device;
0228     const u32 *directory;
0229     struct fw_attribute_group attribute_group;
0230 };
0231
0232 static inline struct fw_unit *fw_unit(struct device *dev)
0233 {
0234     return container_of(dev, struct fw_unit, device);
0235 }
0236
0237 static inline struct fw_unit *fw_unit_get(struct fw_unit *unit)
0238 {
0239     get_device(&unit->device);
0240
0241     return unit;
0242 }
0243
0244 static inline void fw_unit_put(struct fw_unit *unit)
0245 {
0246     put_device(&unit->device);
0247 }
0248
0249 static inline struct fw_device *fw_parent_device(struct fw_unit *unit)
0250 {
0251     return fw_device(unit->device.parent);
0252 }
0253
0254 struct ieee1394_device_id;
0255
0256 struct fw_driver {
0257     struct device_driver driver;
0258     int (*probe)(struct fw_unit *unit, const struct ieee1394_device_id *id);
0259     /* Called when the parent device sits through a bus reset. */
0260     void (*update)(struct fw_unit *unit);
0261     void (*remove)(struct fw_unit *unit);
0262     const struct ieee1394_device_id *id_table;
0263 };
0264
0265 struct fw_packet;
0266 struct fw_request;
0267
0268 typedef void (*fw_packet_callback_t)(struct fw_packet *packet,
0269                      struct fw_card *card, int status);
0270 typedef void (*fw_transaction_callback_t)(struct fw_card *card, int rcode,
0271                       void *data, size_t length,
0272                       void *callback_data);
0273 /*
0274  * This callback handles an inbound request subaction.  It is called in
0275  * RCU read-side context, therefore must not sleep.
0276  *
0277  * The callback should not initiate outbound request subactions directly.
0278  * Otherwise there is a danger of recursion of inbound and outbound
0279  * transactions from and to the local node.
0280  *
0281  * The callback is responsible that either fw_send_response() or kfree()
0282  * is called on the @request, except for FCP registers for which the core
0283  * takes care of that.
0284  */
0285 typedef void (*fw_address_callback_t)(struct fw_card *card,
0286                       struct fw_request *request,
0287                       int tcode, int destination, int source,
0288                       int generation,
0289                       unsigned long long offset,
0290                       void *data, size_t length,
0291                       void *callback_data);
0292
0293 struct fw_packet {
0294     int speed;
0295     int generation;
0296     u32 header[4];
0297     size_t header_length;
0298     void *payload;
0299     size_t payload_length;
0300     dma_addr_t payload_bus;
0301     bool payload_mapped;
0302     u32 timestamp;
0303
0304     /*
0305      * This callback is called when the packet transmission has completed.
0306      * For successful transmission, the status code is the ack received
0307      * from the destination.  Otherwise it is one of the juju-specific
0308      * rcodes:  RCODE_SEND_ERROR, _CANCELLED, _BUSY, _GENERATION, _NO_ACK.
0309      * The callback can be called from tasklet context and thus
0310      * must never block.
0311      */
0312     fw_packet_callback_t callback;
0313     int ack;
0314     struct list_head link;
0315     void *driver_data;
0316 };
0317
0318 struct fw_transaction {
0319     int node_id; /* The generation is implied; it is always the current. */
0320     int tlabel;
0321     struct list_head link;
0322     struct fw_card *card;
0323     bool is_split_transaction;
0324     struct timer_list split_timeout_timer;
0325
0326     struct fw_packet packet;
0327
0328     /*
0329      * The data passed to the callback is valid only during the
0330      * callback.
0331      */
0332     fw_transaction_callback_t callback;
0333     void *callback_data;
0334 };
0335
0336 struct fw_address_handler {
0337     u64 offset;
0338     u64 length;
0339     fw_address_callback_t address_callback;
0340     void *callback_data;
0341     struct list_head link;
0342 };
0343
0344 struct fw_address_region {
0345     u64 start;
0346     u64 end;
0347 };
0348
0349 extern const struct fw_address_region fw_high_memory_region;
0350
0351 int fw_core_add_address_handler(struct fw_address_handler *handler,
0352                 const struct fw_address_region *region);
0353 void fw_core_remove_address_handler(struct fw_address_handler *handler);
0354 void fw_send_response(struct fw_card *card,
0355               struct fw_request *request, int rcode);
0356 int fw_get_request_speed(struct fw_request *request);
0357 u32 fw_request_get_timestamp(const struct fw_request *request);
0358 void fw_send_request(struct fw_card *card, struct fw_transaction *t,
0359              int tcode, int destination_id, int generation, int speed,
0360              unsigned long long offset, void *payload, size_t length,
0361              fw_transaction_callback_t callback, void *callback_data);
0362 int fw_cancel_transaction(struct fw_card *card,
0363               struct fw_transaction *transaction);
0364 int fw_run_transaction(struct fw_card *card, int tcode, int destination_id,
0365                int generation, int speed, unsigned long long offset,
0366                void *payload, size_t length);
0367 const char *fw_rcode_string(int rcode);
0368
0369 static inline int fw_stream_packet_destination_id(int tag, int channel, int sy)
0370 {
0371     return tag << 14 | channel << 8 | sy;
0372 }
0373
0374 void fw_schedule_bus_reset(struct fw_card *card, bool delayed,
0375                bool short_reset);
0376
0377 struct fw_descriptor {
0378     struct list_head link;
0379     size_t length;
0380     u32 immediate;
0381     u32 key;
0382     const u32 *data;
0383 };
0384
0385 int fw_core_add_descriptor(struct fw_descriptor *desc);
0386 void fw_core_remove_descriptor(struct fw_descriptor *desc);
0387
0388 /*
0389  * The iso packet format allows for an immediate header/payload part
0390  * stored in 'header' immediately after the packet info plus an
0391  * indirect payload part that is pointer to by the 'payload' field.
0392  * Applications can use one or the other or both to implement simple
0393  * low-bandwidth streaming (e.g. audio) or more advanced
0394  * scatter-gather streaming (e.g. assembling video frame automatically).
0395  */
0396 struct fw_iso_packet {
0397     u16 payload_length; /* Length of indirect payload       */
0398     u32 interrupt:1;    /* Generate interrupt on this packet    */
0399     u32 skip:1;     /* tx: Set to not send packet at all    */
0400                 /* rx: Sync bit, wait for matching sy   */
0401     u32 tag:2;      /* tx: Tag in packet header     */
0402     u32 sy:4;       /* tx: Sy in packet header      */
0403     u32 header_length:8;    /* Length of immediate header       */
0404     u32 header[0];      /* tx: Top of 1394 isoch. data_block    */
0405 };
0406
0407 #define FW_ISO_CONTEXT_TRANSMIT         0
0408 #define FW_ISO_CONTEXT_RECEIVE          1
0409 #define FW_ISO_CONTEXT_RECEIVE_MULTICHANNEL 2
0410
0411 #define FW_ISO_CONTEXT_MATCH_TAG0    1
0412 #define FW_ISO_CONTEXT_MATCH_TAG1    2
0413 #define FW_ISO_CONTEXT_MATCH_TAG2    4
0414 #define FW_ISO_CONTEXT_MATCH_TAG3    8
0415 #define FW_ISO_CONTEXT_MATCH_ALL_TAGS   15
0416
0417 /*
0418  * An iso buffer is just a set of pages mapped for DMA in the
0419  * specified direction.  Since the pages are to be used for DMA, they
0420  * are not mapped into the kernel virtual address space.  We store the
0421  * DMA address in the page private. The helper function
0422  * fw_iso_buffer_map() will map the pages into a given vma.
0423  */
0424 struct fw_iso_buffer {
0425     enum dma_data_direction direction;
0426     struct page **pages;
0427     int page_count;
0428     int page_count_mapped;
0429 };
0430
0431 int fw_iso_buffer_init(struct fw_iso_buffer *buffer, struct fw_card *card,
0432                int page_count, enum dma_data_direction direction);
0433 void fw_iso_buffer_destroy(struct fw_iso_buffer *buffer, struct fw_card *card);
0434 size_t fw_iso_buffer_lookup(struct fw_iso_buffer *buffer, dma_addr_t completed);
0435
0436 struct fw_iso_context;
0437 typedef void (*fw_iso_callback_t)(struct fw_iso_context *context,
0438                   u32 cycle, size_t header_length,
0439                   void *header, void *data);
0440 typedef void (*fw_iso_mc_callback_t)(struct fw_iso_context *context,
0441                      dma_addr_t completed, void *data);
0442
0443 union fw_iso_callback {
0444     fw_iso_callback_t sc;
0445     fw_iso_mc_callback_t mc;
0446 };
0447
0448 struct fw_iso_context {
0449     struct fw_card *card;
0450     int type;
0451     int channel;
0452     int speed;
0453     bool drop_overflow_headers;
0454     size_t header_size;
0455     union fw_iso_callback callback;
0456     void *callback_data;
0457 };
0458
0459 struct fw_iso_context *fw_iso_context_create(struct fw_card *card,
0460         int type, int channel, int speed, size_t header_size,
0461         fw_iso_callback_t callback, void *callback_data);
0462 int fw_iso_context_set_channels(struct fw_iso_context *ctx, u64 *channels);
0463 int fw_iso_context_queue(struct fw_iso_context *ctx,
0464              struct fw_iso_packet *packet,
0465              struct fw_iso_buffer *buffer,
0466              unsigned long payload);
0467 void fw_iso_context_queue_flush(struct fw_iso_context *ctx);
0468 int fw_iso_context_flush_completions(struct fw_iso_context *ctx);
0469 int fw_iso_context_start(struct fw_iso_context *ctx,
0470              int cycle, int sync, int tags);
0471 int fw_iso_context_stop(struct fw_iso_context *ctx);
0472 void fw_iso_context_destroy(struct fw_iso_context *ctx);
0473 void fw_iso_resource_manage(struct fw_card *card, int generation,
0474                 u64 channels_mask, int *channel, int *bandwidth,
0475                 bool allocate);
0476
0477 extern struct workqueue_struct *fw_workqueue;
0478
0479 #endif /* _LINUX_FIREWIRE_H */