net/hns3: fix flow rule list in multi-process
[dpdk.git] / drivers / net / hns3 / hns3_ethdev.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2018-2021 HiSilicon Limited.
3  */
4
5 #ifndef _HNS3_ETHDEV_H_
6 #define _HNS3_ETHDEV_H_
7
8 #include <pthread.h>
9 #include <sys/time.h>
10 #include <ethdev_driver.h>
11 #include <rte_byteorder.h>
12 #include <rte_io.h>
13 #include <rte_spinlock.h>
14
15 #include "hns3_cmd.h"
16 #include "hns3_mbx.h"
17 #include "hns3_rss.h"
18 #include "hns3_fdir.h"
19 #include "hns3_stats.h"
20 #include "hns3_tm.h"
21
22 /* Vendor ID */
23 #define PCI_VENDOR_ID_HUAWEI                    0x19e5
24
25 /* Device IDs */
26 #define HNS3_DEV_ID_GE                          0xA220
27 #define HNS3_DEV_ID_25GE                        0xA221
28 #define HNS3_DEV_ID_25GE_RDMA                   0xA222
29 #define HNS3_DEV_ID_50GE_RDMA                   0xA224
30 #define HNS3_DEV_ID_100G_RDMA_MACSEC            0xA226
31 #define HNS3_DEV_ID_200G_RDMA                   0xA228
32 #define HNS3_DEV_ID_100G_VF                     0xA22E
33 #define HNS3_DEV_ID_100G_RDMA_PFC_VF            0xA22F
34
35 /* PCI Config offsets */
36 #define HNS3_PCI_REVISION_ID                    0x08
37 #define HNS3_PCI_REVISION_ID_LEN                1
38
39 #define PCI_REVISION_ID_HIP08_B                 0x21
40 #define PCI_REVISION_ID_HIP09_A                 0x30
41
42 #define HNS3_PF_FUNC_ID                 0
43 #define HNS3_1ST_VF_FUNC_ID             1
44
45 #define HNS3_DEFAULT_PORT_CONF_BURST_SIZE       32
46 #define HNS3_DEFAULT_PORT_CONF_QUEUES_NUM       1
47
48 #define HNS3_SW_SHIFT_AND_DISCARD_MODE          0
49 #define HNS3_HW_SHIFT_AND_DISCARD_MODE          1
50
51 #define HNS3_UNLIMIT_PROMISC_MODE       0
52 #define HNS3_LIMIT_PROMISC_MODE         1
53
54 #define HNS3_SPECIAL_PORT_SW_CKSUM_MODE         0
55 #define HNS3_SPECIAL_PORT_HW_CKSUM_MODE         1
56
57 #define HNS3_UC_MACADDR_NUM             128
58 #define HNS3_VF_UC_MACADDR_NUM          48
59 #define HNS3_MC_MACADDR_NUM             128
60
61 #define HNS3_MAX_BD_SIZE                65535
62 #define HNS3_MAX_NON_TSO_BD_PER_PKT     8
63 #define HNS3_MAX_TSO_BD_PER_PKT         63
64 #define HNS3_MAX_FRAME_LEN              9728
65 #define HNS3_VLAN_TAG_SIZE              4
66 #define HNS3_DEFAULT_RX_BUF_LEN         2048
67 #define HNS3_MAX_BD_PAYLEN              (1024 * 1024 - 1)
68 #define HNS3_MAX_TSO_HDR_SIZE           512
69 #define HNS3_MAX_TSO_HDR_BD_NUM         3
70 #define HNS3_MAX_LRO_SIZE               64512
71
72 #define HNS3_ETH_OVERHEAD \
73         (RTE_ETHER_HDR_LEN + RTE_ETHER_CRC_LEN + HNS3_VLAN_TAG_SIZE * 2)
74 #define HNS3_PKTLEN_TO_MTU(pktlen)      ((pktlen) - HNS3_ETH_OVERHEAD)
75 #define HNS3_MAX_MTU    (HNS3_MAX_FRAME_LEN - HNS3_ETH_OVERHEAD)
76 #define HNS3_DEFAULT_MTU                1500UL
77 #define HNS3_DEFAULT_FRAME_LEN          (HNS3_DEFAULT_MTU + HNS3_ETH_OVERHEAD)
78 #define HNS3_HIP08_MIN_TX_PKT_LEN       33
79 #define HNS3_HIP09_MIN_TX_PKT_LEN       9
80
81 #define HNS3_BITS_PER_BYTE      8
82
83 #define HNS3_4_TCS                      4
84 #define HNS3_8_TCS                      8
85
86 #define HNS3_MAX_PF_NUM                 8
87 #define HNS3_UMV_TBL_SIZE               3072
88 #define HNS3_DEFAULT_UMV_SPACE_PER_PF \
89         (HNS3_UMV_TBL_SIZE / HNS3_MAX_PF_NUM)
90
91 #define HNS3_PF_CFG_BLOCK_SIZE          32
92 #define HNS3_PF_CFG_DESC_NUM \
93         (HNS3_PF_CFG_BLOCK_SIZE / HNS3_CFG_RD_LEN_BYTES)
94
95 #define HNS3_DEFAULT_ENABLE_PFC_NUM     0
96
97 #define HNS3_INTR_UNREG_FAIL_RETRY_CNT  5
98 #define HNS3_INTR_UNREG_FAIL_DELAY_MS   500
99
100 #define HNS3_QUIT_RESET_CNT             10
101 #define HNS3_QUIT_RESET_DELAY_MS        100
102
103 #define HNS3_POLL_RESPONE_MS            1
104
105 #define HNS3_MAX_USER_PRIO              8
106 #define HNS3_PG_NUM                     4
107 enum hns3_fc_mode {
108         HNS3_FC_NONE,
109         HNS3_FC_RX_PAUSE,
110         HNS3_FC_TX_PAUSE,
111         HNS3_FC_FULL,
112         HNS3_FC_DEFAULT
113 };
114
115 #define HNS3_SCH_MODE_SP        0
116 #define HNS3_SCH_MODE_DWRR      1
117 struct hns3_pg_info {
118         uint8_t pg_id;
119         uint8_t pg_sch_mode;  /* 0: sp; 1: dwrr */
120         uint8_t tc_bit_map;
121         uint32_t bw_limit;
122         uint8_t tc_dwrr[HNS3_MAX_TC_NUM];
123 };
124
125 struct hns3_tc_info {
126         uint8_t tc_id;
127         uint8_t tc_sch_mode;  /* 0: sp; 1: dwrr */
128         uint8_t pgid;
129         uint32_t bw_limit;
130         uint8_t up_to_tc_map; /* user priority maping on the TC */
131 };
132
133 struct hns3_dcb_info {
134         uint8_t num_tc;
135         uint8_t num_pg;     /* It must be 1 if vNET-Base schd */
136         uint8_t pg_dwrr[HNS3_PG_NUM];
137         uint8_t prio_tc[HNS3_MAX_USER_PRIO];
138         struct hns3_pg_info pg_info[HNS3_PG_NUM];
139         struct hns3_tc_info tc_info[HNS3_MAX_TC_NUM];
140         uint8_t hw_pfc_map; /* Allow for packet drop or not on this TC */
141         uint8_t pfc_en; /* Pfc enabled or not for user priority */
142 };
143
144 enum hns3_fc_status {
145         HNS3_FC_STATUS_NONE,
146         HNS3_FC_STATUS_MAC_PAUSE,
147         HNS3_FC_STATUS_PFC,
148 };
149
150 struct hns3_tc_queue_info {
151         uint16_t tqp_offset;    /* TQP offset from base TQP */
152         uint16_t tqp_count;     /* Total TQPs */
153         uint8_t tc;             /* TC index */
154         bool enable;            /* If this TC is enable or not */
155 };
156
157 struct hns3_cfg {
158         uint8_t tc_num;
159         uint16_t tqp_desc_num;
160         uint16_t rx_buf_len;
161         uint16_t rss_size_max;
162         uint8_t phy_addr;
163         uint8_t media_type;
164         uint8_t mac_addr[RTE_ETHER_ADDR_LEN];
165         uint8_t default_speed;
166         uint32_t numa_node_map;
167         uint8_t speed_ability;
168         uint16_t umv_space;
169 };
170
171 struct hns3_set_link_speed_cfg {
172         uint32_t speed;
173         uint8_t duplex  : 1;
174         uint8_t autoneg : 1;
175 };
176
177 /* mac media type */
178 enum hns3_media_type {
179         HNS3_MEDIA_TYPE_UNKNOWN,
180         HNS3_MEDIA_TYPE_FIBER,
181         HNS3_MEDIA_TYPE_COPPER,
182         HNS3_MEDIA_TYPE_BACKPLANE,
183         HNS3_MEDIA_TYPE_NONE,
184 };
185
186 #define HNS3_DEFAULT_QUERY              0
187 #define HNS3_ACTIVE_QUERY               1
188
189 struct hns3_mac {
190         uint8_t mac_addr[RTE_ETHER_ADDR_LEN];
191         bool default_addr_setted; /* whether default addr(mac_addr) is set */
192         uint8_t media_type;
193         uint8_t phy_addr;
194         uint8_t link_duplex  : 1; /* ETH_LINK_[HALF/FULL]_DUPLEX */
195         uint8_t link_autoneg : 1; /* ETH_LINK_[AUTONEG/FIXED] */
196         uint8_t link_status  : 1; /* ETH_LINK_[DOWN/UP] */
197         uint32_t link_speed;      /* ETH_SPEED_NUM_ */
198         /*
199          * Some firmware versions support only the SFP speed query. In addition
200          * to the SFP speed query, some firmware supports the query of the speed
201          * capability, auto-negotiation capability, and FEC mode, which can be
202          * selected by the 'query_type' filed in the HNS3_OPC_GET_SFP_INFO CMD.
203          * This field is used to record the SFP information query mode.
204          * Value range:
205          *       HNS3_DEFAULT_QUERY/HNS3_ACTIVE_QUERY
206          *
207          * - HNS3_DEFAULT_QUERY
208          * Speed obtained is from SFP. When the queried speed changes, the MAC
209          * speed needs to be reconfigured.
210          *
211          * - HNS3_ACTIVE_QUERY
212          * Speed obtained is from MAC. At this time, it is unnecessary for
213          * driver to reconfigured the MAC speed. In addition, more information,
214          * such as, the speed capability, auto-negotiation capability and FEC
215          * mode, can be obtained by the HNS3_OPC_GET_SFP_INFO CMD.
216          */
217         uint8_t query_type;
218         uint32_t supported_speed;  /* supported speed for current media type */
219         uint32_t advertising;     /* advertised capability in the local part */
220         uint32_t lp_advertising; /* advertised capability in the link partner */
221         uint8_t support_autoneg;
222 };
223
224 struct hns3_fake_queue_data {
225         void **rx_queues; /* Array of pointers to fake RX queues. */
226         void **tx_queues; /* Array of pointers to fake TX queues. */
227         uint16_t nb_fake_rx_queues; /* Number of fake RX queues. */
228         uint16_t nb_fake_tx_queues; /* Number of fake TX queues. */
229 };
230
231 #define HNS3_PORT_BASE_VLAN_DISABLE     0
232 #define HNS3_PORT_BASE_VLAN_ENABLE      1
233 struct hns3_port_base_vlan_config {
234         uint16_t state;
235         uint16_t pvid;
236 };
237
238 /* Primary process maintains driver state in main thread.
239  *
240  * +---------------+
241  * | UNINITIALIZED |<-----------+
242  * +---------------+            |
243  *      |.eth_dev_init          |.eth_dev_uninit
244  *      V                       |
245  * +---------------+------------+
246  * |  INITIALIZED  |
247  * +---------------+<-----------<---------------+
248  *      |.dev_configure         |               |
249  *      V                       |failed         |
250  * +---------------+------------+               |
251  * |  CONFIGURING  |                            |
252  * +---------------+----+                       |
253  *      |success        |                       |
254  *      |               |               +---------------+
255  *      |               |               |    CLOSING    |
256  *      |               |               +---------------+
257  *      |               |                       ^
258  *      V               |.dev_configure         |
259  * +---------------+----+                       |.dev_close
260  * |  CONFIGURED   |----------------------------+
261  * +---------------+<-----------+
262  *      |.dev_start             |
263  *      V                       |
264  * +---------------+            |
265  * |   STARTING    |------------^
266  * +---------------+ failed     |
267  *      |success                |
268  *      |               +---------------+
269  *      |               |   STOPPING    |
270  *      |               +---------------+
271  *      |                       ^
272  *      V                       |.dev_stop
273  * +---------------+------------+
274  * |    STARTED    |
275  * +---------------+
276  */
277 enum hns3_adapter_state {
278         HNS3_NIC_UNINITIALIZED = 0,
279         HNS3_NIC_INITIALIZED,
280         HNS3_NIC_CONFIGURING,
281         HNS3_NIC_CONFIGURED,
282         HNS3_NIC_STARTING,
283         HNS3_NIC_STARTED,
284         HNS3_NIC_STOPPING,
285         HNS3_NIC_CLOSING,
286         HNS3_NIC_CLOSED,
287         HNS3_NIC_REMOVED,
288         HNS3_NIC_NSTATES
289 };
290
291 /* Reset various stages, execute in order */
292 enum hns3_reset_stage {
293         /* Stop query services, stop transceiver, disable MAC */
294         RESET_STAGE_DOWN,
295         /* Clear reset completion flags, disable send command */
296         RESET_STAGE_PREWAIT,
297         /* Inform IMP to start resetting */
298         RESET_STAGE_REQ_HW_RESET,
299         /* Waiting for hardware reset to complete */
300         RESET_STAGE_WAIT,
301         /* Reinitialize hardware */
302         RESET_STAGE_DEV_INIT,
303         /* Restore user settings and enable MAC */
304         RESET_STAGE_RESTORE,
305         /* Restart query services, start transceiver */
306         RESET_STAGE_DONE,
307         /* Not in reset state */
308         RESET_STAGE_NONE,
309 };
310
311 enum hns3_reset_level {
312         HNS3_FLR_RESET,     /* A VF perform FLR reset */
313         HNS3_VF_FUNC_RESET, /* A VF function reset */
314
315         /*
316          * All VFs under a PF perform function reset.
317          * Kernel PF driver use mailbox to inform DPDK VF to do reset, the value
318          * of the reset level and the one defined in kernel driver should be
319          * same.
320          */
321         HNS3_VF_PF_FUNC_RESET = 2,
322
323         /*
324          * All VFs under a PF perform FLR reset.
325          * Kernel PF driver use mailbox to inform DPDK VF to do reset, the value
326          * of the reset level and the one defined in kernel driver should be
327          * same.
328          *
329          * According to the protocol of PCIe, FLR to a PF resets the PF state as
330          * well as the SR-IOV extended capability including VF Enable which
331          * means that VFs no longer exist.
332          *
333          * In PF FLR, the register state of VF is not reliable, VF's driver
334          * should not access the registers of the VF device.
335          */
336         HNS3_VF_FULL_RESET,
337
338         /* All VFs under the rootport perform a global or IMP reset */
339         HNS3_VF_RESET,
340
341         /*
342          * The enumeration value of HNS3_FUNC_RESET/HNS3_GLOBAL_RESET/
343          * HNS3_IMP_RESET/HNS3_NONE_RESET are also used by firmware, and
344          * can not be changed.
345          */
346
347         HNS3_FUNC_RESET = 5,    /* A PF function reset */
348
349         /* All PFs under the rootport perform a global reset */
350         HNS3_GLOBAL_RESET,
351         HNS3_IMP_RESET,     /* All PFs under the rootport perform a IMP reset */
352         HNS3_NONE_RESET,
353         HNS3_MAX_RESET
354 };
355
356 enum hns3_wait_result {
357         HNS3_WAIT_UNKNOWN,
358         HNS3_WAIT_REQUEST,
359         HNS3_WAIT_SUCCESS,
360         HNS3_WAIT_TIMEOUT
361 };
362
363 #define HNS3_RESET_SYNC_US 100000
364
365 struct hns3_reset_stats {
366         uint64_t request_cnt; /* Total request reset times */
367         uint64_t global_cnt;  /* Total GLOBAL reset times */
368         uint64_t imp_cnt;     /* Total IMP reset times */
369         uint64_t exec_cnt;    /* Total reset executive times */
370         uint64_t success_cnt; /* Total reset successful times */
371         uint64_t fail_cnt;    /* Total reset failed times */
372         uint64_t merge_cnt;   /* Total merged in high reset times */
373 };
374
375 typedef bool (*check_completion_func)(struct hns3_hw *hw);
376
377 struct hns3_wait_data {
378         void *hns;
379         uint64_t end_ms;
380         uint64_t interval;
381         int16_t count;
382         enum hns3_wait_result result;
383         check_completion_func check_completion;
384 };
385
386 struct hns3_reset_ops {
387         void (*reset_service)(void *arg);
388         int (*stop_service)(struct hns3_adapter *hns);
389         int (*prepare_reset)(struct hns3_adapter *hns);
390         int (*wait_hardware_ready)(struct hns3_adapter *hns);
391         int (*reinit_dev)(struct hns3_adapter *hns);
392         int (*restore_conf)(struct hns3_adapter *hns);
393         int (*start_service)(struct hns3_adapter *hns);
394 };
395
396 enum hns3_schedule {
397         SCHEDULE_NONE,
398         SCHEDULE_PENDING,
399         SCHEDULE_REQUESTED,
400         SCHEDULE_DEFERRED,
401 };
402
403 struct hns3_reset_data {
404         enum hns3_reset_stage stage;
405         uint16_t schedule;
406         /* Reset flag, covering the entire reset process */
407         uint16_t resetting;
408         /* Used to disable sending cmds during reset */
409         uint16_t disable_cmd;
410         /* The reset level being processed */
411         enum hns3_reset_level level;
412         /* Reset level set, each bit represents a reset level */
413         uint64_t pending;
414         /* Request reset level set, from interrupt or mailbox */
415         uint64_t request;
416         int attempts; /* Reset failure retry */
417         int retries;  /* Timeout failure retry in reset_post */
418         /*
419          * At the time of global or IMP reset, the command cannot be sent to
420          * stop the tx/rx queues. Tx/Rx queues may be access mbuf during the
421          * reset process, so the mbuf is required to be released after the reset
422          * is completed.The mbuf_deferred_free is used to mark whether mbuf
423          * needs to be released.
424          */
425         bool mbuf_deferred_free;
426         struct timeval start_time;
427         struct hns3_reset_stats stats;
428         const struct hns3_reset_ops *ops;
429         struct hns3_wait_data *wait_data;
430 };
431
432 #define HNS3_INTR_MAPPING_VEC_RSV_ONE           0
433 #define HNS3_INTR_MAPPING_VEC_ALL               1
434
435 #define HNS3_INTR_COALESCE_GL_UINT_2US          0
436 #define HNS3_INTR_COALESCE_GL_UINT_1US          1
437
438 #define HNS3_INTR_QL_NONE                       0
439
440 struct hns3_queue_intr {
441         /*
442          * interrupt mapping mode.
443          * value range:
444          *      HNS3_INTR_MAPPING_VEC_RSV_ONE/HNS3_INTR_MAPPING_VEC_ALL
445          *
446          *  - HNS3_INTR_MAPPING_VEC_RSV_ONE
447          *     For some versions of hardware network engine, because of the
448          *     hardware constraint, we need implement clearing the mapping
449          *     relationship configurations by binding all queues to the last
450          *     interrupt vector and reserving the last interrupt vector. This
451          *     method results in a decrease of the maximum queues when upper
452          *     applications call the rte_eth_dev_configure API function to
453          *     enable Rx interrupt.
454          *
455          *  - HNS3_INTR_MAPPING_VEC_ALL
456          *     PMD driver can map/unmmap all interrupt vectors with queues When
457          *     Rx interrupt in enabled.
458          */
459         uint8_t mapping_mode;
460         /*
461          * The unit of GL(gap limiter) configuration for interrupt coalesce of
462          * queue's interrupt.
463          * value range:
464          *      HNS3_INTR_COALESCE_GL_UINT_2US/HNS3_INTR_COALESCE_GL_UINT_1US
465          */
466         uint8_t gl_unit;
467         /* The max QL(quantity limiter) value */
468         uint16_t int_ql_max;
469 };
470
471 #define HNS3_TSO_SW_CAL_PSEUDO_H_CSUM           0
472 #define HNS3_TSO_HW_CAL_PSEUDO_H_CSUM           1
473
474 #define HNS3_PKTS_DROP_STATS_MODE1              0
475 #define HNS3_PKTS_DROP_STATS_MODE2              1
476
477 struct hns3_hw {
478         struct rte_eth_dev_data *data;
479         void *io_base;
480         uint8_t revision;           /* PCI revision, low byte of class word */
481         struct hns3_cmq cmq;
482         struct hns3_mbx_resp_status mbx_resp; /* mailbox response */
483         struct hns3_mac mac;
484         unsigned int secondary_cnt; /* Number of secondary processes init'd. */
485         struct hns3_tqp_stats tqp_stats;
486         /* Include Mac stats | Rx stats | Tx stats */
487         struct hns3_mac_stats mac_stats;
488         struct hns3_rx_missed_stats imissed_stats;
489         uint64_t oerror_stats;
490         uint32_t fw_version;
491         uint16_t pf_vf_if_version;  /* version of communication interface */
492
493         uint16_t num_msi;
494         uint16_t total_tqps_num;    /* total task queue pairs of this PF */
495         uint16_t tqps_num;          /* num task queue pairs of this function */
496         uint16_t intr_tqps_num;     /* num queue pairs mapping interrupt */
497         uint16_t rss_size_max;      /* HW defined max RSS task queue */
498         uint16_t rx_buf_len;        /* hold min hardware rx buf len */
499         uint16_t num_tx_desc;       /* desc num of per tx queue */
500         uint16_t num_rx_desc;       /* desc num of per rx queue */
501         uint32_t mng_entry_num;     /* number of manager table entry */
502         uint32_t mac_entry_num;     /* number of mac-vlan table entry */
503
504         struct rte_ether_addr mc_addrs[HNS3_MC_MACADDR_NUM];
505         int mc_addrs_num; /* Multicast mac addresses number */
506
507         /* The configuration info of RSS */
508         struct hns3_rss_conf rss_info;
509         bool rss_dis_flag; /* disable rss flag. true: disable, false: enable */
510         uint16_t rss_ind_tbl_size;
511         uint16_t rss_key_size;
512
513         uint8_t num_tc;             /* Total number of enabled TCs */
514         uint8_t hw_tc_map;
515         enum hns3_fc_mode requested_fc_mode; /* FC mode requested by user */
516         struct hns3_dcb_info dcb_info;
517         enum hns3_fc_status current_fc_status; /* current flow control status */
518         struct hns3_tc_queue_info tc_queue[HNS3_MAX_TC_NUM];
519         uint16_t used_rx_queues;
520         uint16_t used_tx_queues;
521
522         /* Config max queue numbers between rx and tx queues from user */
523         uint16_t cfg_max_queues;
524         struct hns3_fake_queue_data fkq_data;     /* fake queue data */
525         uint16_t alloc_rss_size;    /* RX queue number per TC */
526         uint16_t tx_qnum_per_tc;    /* TX queue number per TC */
527
528         uint32_t capability;
529         uint32_t max_tm_rate;
530         /*
531          * The minimum length of the packet supported by hardware in the Tx
532          * direction.
533          */
534         uint32_t min_tx_pkt_len;
535
536         struct hns3_queue_intr intr;
537         /*
538          * tso mode.
539          * value range:
540          *      HNS3_TSO_SW_CAL_PSEUDO_H_CSUM/HNS3_TSO_HW_CAL_PSEUDO_H_CSUM
541          *
542          *  - HNS3_TSO_SW_CAL_PSEUDO_H_CSUM
543          *     In this mode, because of the hardware constraint, network driver
544          *     software need erase the L4 len value of the TCP pseudo header
545          *     and recalculate the TCP pseudo header checksum of packets that
546          *     need TSO.
547          *
548          *  - HNS3_TSO_HW_CAL_PSEUDO_H_CSUM
549          *     In this mode, hardware support recalculate the TCP pseudo header
550          *     checksum of packets that need TSO, so network driver software
551          *     not need to recalculate it.
552          */
553         uint8_t tso_mode;
554         /*
555          * vlan mode.
556          * value range:
557          *      HNS3_SW_SHIFT_AND_DISCARD_MODE/HNS3_HW_SHFIT_AND_DISCARD_MODE
558          *
559          *  - HNS3_SW_SHIFT_AND_DISCARD_MODE
560          *     For some versions of hardware network engine, because of the
561          *     hardware limitation, PMD driver needs to detect the PVID status
562          *     to work with haredware to implement PVID-related functions.
563          *     For example, driver need discard the stripped PVID tag to ensure
564          *     the PVID will not report to mbuf and shift the inserted VLAN tag
565          *     to avoid port based VLAN covering it.
566          *
567          *  - HNS3_HW_SHIT_AND_DISCARD_MODE
568          *     PMD driver does not need to process PVID-related functions in
569          *     I/O process, Hardware will adjust the sequence between port based
570          *     VLAN tag and BD VLAN tag automatically and VLAN tag stripped by
571          *     PVID will be invisible to driver. And in this mode, hns3 is able
572          *     to send a multi-layer VLAN packets when hw VLAN insert offload
573          *     is enabled.
574          */
575         uint8_t vlan_mode;
576         /*
577          * promisc mode.
578          * value range:
579          *      HNS3_UNLIMIT_PROMISC_MODE/HNS3_LIMIT_PROMISC_MODE
580          *
581          *  - HNS3_UNLIMIT_PROMISC_MODE
582          *     In this mode, TX unicast promisc will be configured when promisc
583          *     is set, driver can receive all the ingress and outgoing traffic.
584          *     In the words, all the ingress packets, all the packets sent from
585          *     the PF and other VFs on the same physical port.
586          *
587          *  - HNS3_LIMIT_PROMISC_MODE
588          *     In this mode, TX unicast promisc is shutdown when promisc mode
589          *     is set. So, driver will only receive all the ingress traffic.
590          *     The packets sent from the PF and other VFs on the same physical
591          *     port won't be copied to the function which has set promisc mode.
592          */
593         uint8_t promisc_mode;
594
595         /*
596          * drop_stats_mode mode.
597          * value range:
598          *      HNS3_PKTS_DROP_STATS_MODE1/HNS3_PKTS_DROP_STATS_MODE2
599          *
600          *  - HNS3_PKTS_DROP_STATS_MODE1
601          *     This mode for kunpeng920. In this mode, port level imissed stats
602          *     is supported. It only includes RPU drop stats.
603          *
604          *  - HNS3_PKTS_DROP_STATS_MODE2
605          *     This mode for kunpeng930. In this mode, imissed stats and oerrors
606          *     stats is supported. Function level imissed stats is supported. It
607          *     includes RPU drop stats in VF, and includes both RPU drop stats
608          *     and SSU drop stats in PF. Oerror stats is also supported in PF.
609          */
610         uint8_t drop_stats_mode;
611
612         uint8_t max_non_tso_bd_num; /* max BD number of one non-TSO packet */
613         /*
614          * udp checksum mode.
615          * value range:
616          *      HNS3_SPECIAL_PORT_HW_CKSUM_MODE/HNS3_SPECIAL_PORT_SW_CKSUM_MODE
617          *
618          *  - HNS3_SPECIAL_PORT_SW_CKSUM_MODE
619          *     In this mode, HW can not do checksum for special UDP port like
620          *     4789, 4790, 6081 for non-tunnel UDP packets and UDP tunnel
621          *     packets without the PKT_TX_TUNEL_MASK in the mbuf. So, PMD need
622          *     do the checksum for these packets to avoid a checksum error.
623          *
624          *  - HNS3_SPECIAL_PORT_HW_CKSUM_MODE
625          *     In this mode, HW does not have the preceding problems and can
626          *     directly calculate the checksum of these UDP packets.
627          */
628         uint8_t udp_cksum_mode;
629
630         struct hns3_port_base_vlan_config port_base_vlan_cfg;
631
632         pthread_mutex_t flows_lock; /* rte_flow ops lock */
633         struct hns3_fdir_rule_list flow_fdir_list; /* flow fdir rule list */
634         struct hns3_rss_filter_list flow_rss_list; /* flow RSS rule list */
635         struct hns3_flow_mem_list flow_list;
636
637         /*
638          * PMD setup and configuration is not thread safe. Since it is not
639          * performance sensitive, it is better to guarantee thread-safety
640          * and add device level lock. Adapter control operations which
641          * change its state should acquire the lock.
642          */
643         rte_spinlock_t lock;
644         enum hns3_adapter_state adapter_state;
645         struct hns3_reset_data reset;
646 };
647
648 #define HNS3_FLAG_TC_BASE_SCH_MODE              1
649 #define HNS3_FLAG_VNET_BASE_SCH_MODE            2
650
651 /* vlan entry information. */
652 struct hns3_user_vlan_table {
653         LIST_ENTRY(hns3_user_vlan_table) next;
654         bool hd_tbl_status;
655         uint16_t vlan_id;
656 };
657
658 /* Vlan tag configuration for RX direction */
659 struct hns3_rx_vtag_cfg {
660         bool rx_vlan_offload_en;    /* Whether enable rx vlan offload */
661         bool strip_tag1_en;         /* Whether strip inner vlan tag */
662         bool strip_tag2_en;         /* Whether strip outer vlan tag */
663         /*
664          * If strip_tag_en is enabled, this bit decide whether to map the vlan
665          * tag to descriptor.
666          */
667         bool strip_tag1_discard_en;
668         bool strip_tag2_discard_en;
669         /*
670          * If this bit is enabled, only map inner/outer priority to descriptor
671          * and the vlan tag is always 0.
672          */
673         bool vlan1_vlan_prionly;
674         bool vlan2_vlan_prionly;
675 };
676
677 /* Vlan tag configuration for TX direction */
678 struct hns3_tx_vtag_cfg {
679         bool accept_tag1;           /* Whether accept tag1 packet from host */
680         bool accept_untag1;         /* Whether accept untag1 packet from host */
681         bool accept_tag2;
682         bool accept_untag2;
683         bool insert_tag1_en;        /* Whether insert outer vlan tag */
684         bool insert_tag2_en;        /* Whether insert inner vlan tag */
685         /*
686          * In shift mode, hw will shift the sequence of port based VLAN and
687          * BD VLAN.
688          */
689         bool tag_shift_mode_en;     /* hw shift vlan tag automatically */
690         uint16_t default_tag1;      /* The default outer vlan tag to insert */
691         uint16_t default_tag2;      /* The default inner vlan tag to insert */
692 };
693
694 struct hns3_vtag_cfg {
695         struct hns3_rx_vtag_cfg rx_vcfg;
696         struct hns3_tx_vtag_cfg tx_vcfg;
697 };
698
699 /* Request types for IPC. */
700 enum hns3_mp_req_type {
701         HNS3_MP_REQ_START_RXTX = 1,
702         HNS3_MP_REQ_STOP_RXTX,
703         HNS3_MP_REQ_MAX
704 };
705
706 /* Pameters for IPC. */
707 struct hns3_mp_param {
708         enum hns3_mp_req_type type;
709         int port_id;
710         int result;
711 };
712
713 /* Request timeout for IPC. */
714 #define HNS3_MP_REQ_TIMEOUT_SEC 5
715
716 /* Key string for IPC. */
717 #define HNS3_MP_NAME "net_hns3_mp"
718
719 #define HNS3_L2TBL_NUM  4
720 #define HNS3_L3TBL_NUM  16
721 #define HNS3_L4TBL_NUM  16
722 #define HNS3_OL2TBL_NUM 4
723 #define HNS3_OL3TBL_NUM 16
724 #define HNS3_OL4TBL_NUM 16
725 #define HNS3_PTYPE_NUM  256
726
727 struct hns3_ptype_table {
728         /*
729          * The next fields used to calc packet-type by the
730          * L3_ID/L4_ID/OL3_ID/OL4_ID from the Rx descriptor.
731          */
732         uint32_t l3table[HNS3_L3TBL_NUM];
733         uint32_t l4table[HNS3_L4TBL_NUM];
734         uint32_t inner_l3table[HNS3_L3TBL_NUM];
735         uint32_t inner_l4table[HNS3_L4TBL_NUM];
736         uint32_t ol3table[HNS3_OL3TBL_NUM];
737         uint32_t ol4table[HNS3_OL4TBL_NUM];
738
739         /*
740          * The next field used to calc packet-type by the PTYPE from the Rx
741          * descriptor, it functions only when firmware report the capability of
742          * HNS3_CAPS_RXD_ADV_LAYOUT_B and driver enabled it.
743          */
744         uint32_t ptype[HNS3_PTYPE_NUM] __rte_cache_aligned;
745 };
746
747 #define HNS3_FIXED_MAX_TQP_NUM_MODE             0
748 #define HNS3_FLEX_MAX_TQP_NUM_MODE              1
749
750 struct hns3_pf {
751         struct hns3_adapter *adapter;
752         bool is_main_pf;
753         uint16_t func_num; /* num functions of this pf, include pf and vfs */
754
755         /*
756          * tqp_config mode
757          * tqp_config_mode value range:
758          *      HNS3_FIXED_MAX_TQP_NUM_MODE,
759          *      HNS3_FLEX_MAX_TQP_NUM_MODE
760          *
761          * - HNS3_FIXED_MAX_TQP_NUM_MODE
762          *   There is a limitation on the number of pf interrupts available for
763          *   on some versions of network engines. In this case, the maximum
764          *   queue number of pf can not be greater than the interrupt number,
765          *   such as pf of network engine with revision_id 0x21. So the maximum
766          *   number of queues must be fixed.
767          *
768          * - HNS3_FLEX_MAX_TQP_NUM_MODE
769          *   In this mode, the maximum queue number of pf has not any constraint
770          *   and comes from the macro RTE_LIBRTE_HNS3_MAX_TQP_NUM_PER_PF
771          *   in the config file. Users can modify the macro according to their
772          *   own application scenarios, which is more flexible to use.
773          */
774         uint8_t tqp_config_mode;
775
776         uint32_t pkt_buf_size; /* Total pf buf size for tx/rx */
777         uint32_t tx_buf_size; /* Tx buffer size for each TC */
778         uint32_t dv_buf_size; /* Dv buffer size for each TC */
779
780         uint16_t mps; /* Max packet size */
781
782         uint8_t tx_sch_mode;
783         uint8_t tc_max; /* max number of tc driver supported */
784         uint8_t local_max_tc; /* max number of local tc */
785         uint8_t pfc_max;
786         uint8_t prio_tc[HNS3_MAX_USER_PRIO]; /* TC indexed by prio */
787         uint16_t pause_time;
788         bool support_fc_autoneg;       /* support FC autonegotiate */
789         bool support_multi_tc_pause;
790
791         uint16_t wanted_umv_size;
792         uint16_t max_umv_size;
793         uint16_t used_umv_size;
794
795         bool support_sfp_query;
796         uint32_t fec_mode; /* current FEC mode for ethdev */
797
798         bool ptp_enable;
799
800         /* Stores timestamp of last received packet on dev */
801         uint64_t rx_timestamp;
802
803         struct hns3_vtag_cfg vtag_config;
804         LIST_HEAD(vlan_tbl, hns3_user_vlan_table) vlan_list;
805
806         struct hns3_fdir_info fdir; /* flow director info */
807         LIST_HEAD(counters, hns3_flow_counter) flow_counters;
808
809         struct hns3_tm_conf tm_conf;
810 };
811
812 enum {
813         HNS3_PF_PUSH_LSC_CAP_NOT_SUPPORTED,
814         HNS3_PF_PUSH_LSC_CAP_SUPPORTED,
815         HNS3_PF_PUSH_LSC_CAP_UNKNOWN
816 };
817
818 struct hns3_vf {
819         struct hns3_adapter *adapter;
820
821         /* Whether PF support push link status change to VF */
822         uint16_t pf_push_lsc_cap;
823
824         /*
825          * If PF support push link status change, VF still need send request to
826          * get link status in some cases (such as reset recover stage), so use
827          * the req_link_info_cnt to control max request count.
828          */
829         uint16_t req_link_info_cnt;
830
831         uint16_t poll_job_started; /* whether poll job is started */
832 };
833
834 struct hns3_adapter {
835         struct hns3_hw hw;
836
837         /* Specific for PF or VF */
838         bool is_vf; /* false - PF, true - VF */
839         union {
840                 struct hns3_pf pf;
841                 struct hns3_vf vf;
842         };
843
844         uint32_t rx_func_hint;
845         uint32_t tx_func_hint;
846
847         uint64_t dev_caps_mask;
848
849         struct hns3_ptype_table ptype_tbl __rte_cache_aligned;
850 };
851
852 enum {
853         HNS3_IO_FUNC_HINT_NONE = 0,
854         HNS3_IO_FUNC_HINT_VEC,
855         HNS3_IO_FUNC_HINT_SVE,
856         HNS3_IO_FUNC_HINT_SIMPLE,
857         HNS3_IO_FUNC_HINT_COMMON
858 };
859
860 #define HNS3_DEVARG_RX_FUNC_HINT        "rx_func_hint"
861 #define HNS3_DEVARG_TX_FUNC_HINT        "tx_func_hint"
862
863 #define HNS3_DEVARG_DEV_CAPS_MASK       "dev_caps_mask"
864
865 enum {
866         HNS3_DEV_SUPPORT_DCB_B,
867         HNS3_DEV_SUPPORT_COPPER_B,
868         HNS3_DEV_SUPPORT_FD_QUEUE_REGION_B,
869         HNS3_DEV_SUPPORT_PTP_B,
870         HNS3_DEV_SUPPORT_TX_PUSH_B,
871         HNS3_DEV_SUPPORT_INDEP_TXRX_B,
872         HNS3_DEV_SUPPORT_STASH_B,
873         HNS3_DEV_SUPPORT_RXD_ADV_LAYOUT_B,
874         HNS3_DEV_SUPPORT_OUTER_UDP_CKSUM_B,
875         HNS3_DEV_SUPPORT_RAS_IMP_B,
876         HNS3_DEV_SUPPORT_TM_B,
877         HNS3_DEV_SUPPORT_VF_VLAN_FLT_MOD_B,
878 };
879
880 #define hns3_dev_dcb_supported(hw) \
881         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_DCB_B)
882
883 /* Support copper media type */
884 #define hns3_dev_copper_supported(hw) \
885         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_COPPER_B)
886
887 /* Support the queue region action rule of flow directory */
888 #define hns3_dev_fd_queue_region_supported(hw) \
889         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_FD_QUEUE_REGION_B)
890
891 /* Support PTP timestamp offload */
892 #define hns3_dev_ptp_supported(hw) \
893         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_PTP_B)
894
895 /* Support to Independently enable/disable/reset Tx or Rx queues */
896 #define hns3_dev_indep_txrx_supported(hw) \
897         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_INDEP_TXRX_B)
898
899 #define hns3_dev_stash_supported(hw) \
900         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_STASH_B)
901
902 #define hns3_dev_rxd_adv_layout_supported(hw) \
903         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_RXD_ADV_LAYOUT_B)
904
905 #define hns3_dev_outer_udp_cksum_supported(hw) \
906         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_OUTER_UDP_CKSUM_B)
907
908 #define hns3_dev_ras_imp_supported(hw) \
909         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_RAS_IMP_B)
910
911 #define hns3_dev_tx_push_supported(hw) \
912                 hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_TX_PUSH_B)
913
914 #define hns3_dev_tm_supported(hw) \
915         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_TM_B)
916
917 #define hns3_dev_vf_vlan_flt_supported(hw) \
918         hns3_get_bit((hw)->capability, HNS3_DEV_SUPPORT_VF_VLAN_FLT_MOD_B)
919
920 #define HNS3_DEV_PRIVATE_TO_HW(adapter) \
921         (&((struct hns3_adapter *)adapter)->hw)
922 #define HNS3_DEV_PRIVATE_TO_PF(adapter) \
923         (&((struct hns3_adapter *)adapter)->pf)
924 #define HNS3_DEV_PRIVATE_TO_VF(adapter) \
925         (&((struct hns3_adapter *)adapter)->vf)
926 #define HNS3_DEV_HW_TO_ADAPTER(hw) \
927         container_of(hw, struct hns3_adapter, hw)
928
929 static inline struct hns3_pf *HNS3_DEV_HW_TO_PF(struct hns3_hw *hw)
930 {
931         struct hns3_adapter *adapter = HNS3_DEV_HW_TO_ADAPTER(hw);
932         return &adapter->pf;
933 }
934
935 static inline struct hns3_vf *HNS3_DEV_HW_TO_VF(struct hns3_hw *hw)
936 {
937         struct hns3_adapter *adapter = HNS3_DEV_HW_TO_ADAPTER(hw);
938         return &adapter->vf;
939 }
940
941 #define hns3_set_field(origin, mask, shift, val) \
942         do { \
943                 (origin) &= (~(mask)); \
944                 (origin) |= ((val) << (shift)) & (mask); \
945         } while (0)
946 #define hns3_get_field(origin, mask, shift) \
947         (((origin) & (mask)) >> (shift))
948 #define hns3_set_bit(origin, shift, val) \
949         hns3_set_field((origin), (0x1UL << (shift)), (shift), (val))
950 #define hns3_get_bit(origin, shift) \
951         hns3_get_field((origin), (0x1UL << (shift)), (shift))
952
953 #define hns3_gen_field_val(mask, shift, val) (((val) << (shift)) & (mask))
954
955 /*
956  * upper_32_bits - return bits 32-63 of a number
957  * A basic shift-right of a 64- or 32-bit quantity. Use this to suppress
958  * the "right shift count >= width of type" warning when that quantity is
959  * 32-bits.
960  */
961 #define upper_32_bits(n) ((uint32_t)(((n) >> 16) >> 16))
962
963 /* lower_32_bits - return bits 0-31 of a number */
964 #define lower_32_bits(n) ((uint32_t)(n))
965
966 #define BIT(nr) (1UL << (nr))
967
968 #define BIT_ULL(x) (1ULL << (x))
969
970 #define BITS_PER_LONG   (__SIZEOF_LONG__ * 8)
971 #define GENMASK(h, l) \
972         (((~0UL) << (l)) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
973
974 #define roundup(x, y) ((((x) + ((y) - 1)) / (y)) * (y))
975 #define rounddown(x, y) ((x) - ((x) % (y)))
976
977 #define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))
978
979 /*
980  * Because hardware always access register in little-endian mode based on hns3
981  * network engine, so driver should also call rte_cpu_to_le_32 to convert data
982  * in little-endian mode before writing register and call rte_le_to_cpu_32 to
983  * convert data after reading from register.
984  *
985  * Here the driver encapsulates the data conversion operation in the register
986  * read/write operation function as below:
987  *   hns3_write_reg
988  *   hns3_write_reg_opt
989  *   hns3_read_reg
990  * Therefore, when calling these functions, conversion is not required again.
991  */
992 static inline void hns3_write_reg(void *base, uint32_t reg, uint32_t value)
993 {
994         rte_write32(rte_cpu_to_le_32(value),
995                     (volatile void *)((char *)base + reg));
996 }
997
998 /*
999  * The optimized function for writing registers reduces one address addition
1000  * calculation, it was used in the '.rx_pkt_burst' and '.tx_pkt_burst' ops
1001  * implementation function.
1002  */
1003 static inline void hns3_write_reg_opt(volatile void *addr, uint32_t value)
1004 {
1005         rte_write32(rte_cpu_to_le_32(value), addr);
1006 }
1007
1008 static inline uint32_t hns3_read_reg(void *base, uint32_t reg)
1009 {
1010         uint32_t read_val = rte_read32((volatile void *)((char *)base + reg));
1011         return rte_le_to_cpu_32(read_val);
1012 }
1013
1014 #define hns3_write_dev(a, reg, value) \
1015         hns3_write_reg((a)->io_base, (reg), (value))
1016
1017 #define hns3_read_dev(a, reg) \
1018         hns3_read_reg((a)->io_base, (reg))
1019
1020 #define NEXT_ITEM_OF_ACTION(act, actions, index)                        \
1021         do {                                                            \
1022                 act = (actions) + (index);                              \
1023                 while (act->type == RTE_FLOW_ACTION_TYPE_VOID) {        \
1024                         (index)++;                                      \
1025                         act = actions + index;                          \
1026                 }                                                       \
1027         } while (0)
1028
1029 #define MSEC_PER_SEC              1000L
1030 #define USEC_PER_MSEC             1000L
1031
1032 void hns3_clock_gettime(struct timeval *tv);
1033 uint64_t hns3_clock_calctime_ms(struct timeval *tv);
1034 uint64_t hns3_clock_gettime_ms(void);
1035
1036 static inline uint64_t
1037 hns3_atomic_test_bit(unsigned int nr, volatile uint64_t *addr)
1038 {
1039         uint64_t res;
1040
1041         res = (__atomic_load_n(addr, __ATOMIC_RELAXED) & (1UL << nr)) != 0;
1042         return res;
1043 }
1044
1045 static inline void
1046 hns3_atomic_set_bit(unsigned int nr, volatile uint64_t *addr)
1047 {
1048         __atomic_fetch_or(addr, (1UL << nr), __ATOMIC_RELAXED);
1049 }
1050
1051 static inline void
1052 hns3_atomic_clear_bit(unsigned int nr, volatile uint64_t *addr)
1053 {
1054         __atomic_fetch_and(addr, ~(1UL << nr), __ATOMIC_RELAXED);
1055 }
1056
1057 static inline int64_t
1058 hns3_test_and_clear_bit(unsigned int nr, volatile uint64_t *addr)
1059 {
1060         uint64_t mask = (1UL << nr);
1061
1062         return __atomic_fetch_and(addr, ~mask, __ATOMIC_RELAXED) & mask;
1063 }
1064
1065 int hns3_buffer_alloc(struct hns3_hw *hw);
1066 int hns3_dev_flow_ops_get(struct rte_eth_dev *dev,
1067                           const struct rte_flow_ops **ops);
1068 bool hns3_is_reset_pending(struct hns3_adapter *hns);
1069 bool hns3vf_is_reset_pending(struct hns3_adapter *hns);
1070 void hns3_update_linkstatus_and_event(struct hns3_hw *hw, bool query);
1071 void hns3_ether_format_addr(char *buf, uint16_t size,
1072                         const struct rte_ether_addr *ether_addr);
1073 int hns3_dev_infos_get(struct rte_eth_dev *eth_dev,
1074                        struct rte_eth_dev_info *info);
1075 void hns3vf_update_link_status(struct hns3_hw *hw, uint8_t link_status,
1076                           uint32_t link_speed, uint8_t link_duplex);
1077 void hns3_parse_devargs(struct rte_eth_dev *dev);
1078 void hns3vf_update_push_lsc_cap(struct hns3_hw *hw, bool supported);
1079 int hns3_restore_ptp(struct hns3_adapter *hns);
1080 int hns3_mbuf_dyn_rx_timestamp_register(struct rte_eth_dev *dev,
1081                                     struct rte_eth_conf *conf);
1082 int hns3_ptp_init(struct hns3_hw *hw);
1083 int hns3_timesync_enable(struct rte_eth_dev *dev);
1084 int hns3_timesync_disable(struct rte_eth_dev *dev);
1085 int hns3_timesync_read_rx_timestamp(struct rte_eth_dev *dev,
1086                                 struct timespec *timestamp,
1087                                 uint32_t flags __rte_unused);
1088 int hns3_timesync_read_tx_timestamp(struct rte_eth_dev *dev,
1089                                 struct timespec *timestamp);
1090 int hns3_timesync_read_time(struct rte_eth_dev *dev, struct timespec *ts);
1091 int hns3_timesync_write_time(struct rte_eth_dev *dev,
1092                         const struct timespec *ts);
1093 int hns3_timesync_adjust_time(struct rte_eth_dev *dev, int64_t delta);
1094
1095 static inline bool
1096 is_reset_pending(struct hns3_adapter *hns)
1097 {
1098         bool ret;
1099         if (hns->is_vf)
1100                 ret = hns3vf_is_reset_pending(hns);
1101         else
1102                 ret = hns3_is_reset_pending(hns);
1103         return ret;
1104 }
1105
1106 static inline uint64_t
1107 hns3_txvlan_cap_get(struct hns3_hw *hw)
1108 {
1109         if (hw->port_base_vlan_cfg.state)
1110                 return DEV_TX_OFFLOAD_VLAN_INSERT;
1111         else
1112                 return DEV_TX_OFFLOAD_VLAN_INSERT | DEV_TX_OFFLOAD_QINQ_INSERT;
1113 }
1114
1115 #endif /* _HNS3_ETHDEV_H_ */